1 // Copyright 2010 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 // WMI (Windows Management and Instrumentation) is a big, complex, COM-based 6 // API that can be used to perform all sorts of things. Sometimes is the best 7 // way to accomplish something under windows but its lack of an approachable 8 // C++ interface prevents its use. This collection of functions is a step in 9 // that direction. 10 // There are two classes; WMIUtil and WMIProcessUtil. The first 11 // one contains generic helpers and the second one contains the only 12 // functionality that is needed right now which is to use WMI to launch a 13 // process. 14 // To use any function on this header you must call CoInitialize or 15 // CoInitializeEx beforehand. 16 // 17 // For more information about WMI programming: 18 // https://docs.microsoft.com/en-us/windows/win32/wmisdk 19 20 #ifndef BASE_WIN_WMI_H_ 21 #define BASE_WIN_WMI_H_ 22 23 #include <wbemidl.h> 24 #include <wrl/client.h> 25 26 #include "base/base_export.h" 27 #include "base/strings/string_piece.h" 28 #include "third_party/abseil-cpp/absl/types/optional.h" 29 30 namespace base { 31 namespace win { 32 33 // Enumeration of errors that can arise when connecting to a WMI server and 34 // running a query. 35 // Do not change ordering. This enum is captured as `WmiQueryError` in 36 // enums.xml. 37 enum class WmiError { 38 kFailedToCreateInstance = 0, 39 kFailedToConnectToWMI = 1, 40 kFailedToSetSecurityBlanket = 2, 41 kFailedToExecWMIQuery = 3, 42 kMaxValue = kFailedToExecWMIQuery 43 }; 44 45 // String used to connect to the CIMV2 WMI server. 46 BASE_EXPORT extern const wchar_t kCimV2ServerName[]; 47 48 // String used to connect to the SecurityCenter2 WMI server. 49 BASE_EXPORT extern const wchar_t kSecurityCenter2ServerName[]; 50 51 // Connects to a server named `server_name` on the local computer through COM 52 // and run the given WQL `query`. Sets `enumerator` with the values returned by 53 // that `query`. Will return a WmiError value if an error occurs, else returns 54 // absl::nullopt. 55 BASE_EXPORT absl::optional<WmiError> RunWmiQuery( 56 const std::wstring& server_name, 57 const std::wstring& query, 58 Microsoft::WRL::ComPtr<IEnumWbemClassObject>* enumerator); 59 60 // Creates an instance of the WMI service connected to the local computer and 61 // returns its COM interface. If |set_blanket| is set to true, the basic COM 62 // security blanket is applied to the returned interface. This is almost 63 // always desirable unless you set the parameter to false and apply a custom 64 // COM security blanket. 65 // Returns true if succeeded and |wmi_services|: the pointer to the service. 66 BASE_EXPORT bool CreateLocalWmiConnection( 67 bool set_blanket, 68 Microsoft::WRL::ComPtr<IWbemServices>* wmi_services); 69 70 // Creates an instance of the WMI service connected to the resource and 71 // returns its COM interface. If |set_blanket| is set to true, the basic COM 72 // security blanket is applied to the returned interface. This is almost 73 // always desirable unless you set the parameter to false and apply a custom 74 // COM security blanket. 75 // Returns a valid ComPtr<IWbemServices> on success, nullptr on failure. 76 BASE_EXPORT Microsoft::WRL::ComPtr<IWbemServices> CreateWmiConnection( 77 bool set_blanket, 78 const std::wstring& resource); 79 80 // Creates a WMI method using from a WMI class named |class_name| that 81 // contains a method named |method_name|. Only WMI classes that are CIM 82 // classes can be created using this function. 83 // Returns true if succeeded and |class_instance| returns a pointer to the 84 // WMI method that you can fill with parameter values using SetParameter. 85 BASE_EXPORT bool CreateWmiClassMethodObject( 86 IWbemServices* wmi_services, 87 WStringPiece class_name, 88 WStringPiece method_name, 89 Microsoft::WRL::ComPtr<IWbemClassObject>* class_instance); 90 91 // Creates a new process from |command_line|. The advantage over CreateProcess 92 // is that it allows you to always break out from a Job object that the caller 93 // is attached to even if the Job object flags prevent that. 94 // Returns true and the process id in process_id if the process is launched 95 // successful. False otherwise. 96 // Note that a fully qualified path must be specified in most cases unless 97 // the program is not in the search path of winmgmt.exe. 98 // Processes created this way are children of wmiprvse.exe and run with the 99 // caller credentials. 100 // More info: http://msdn2.microsoft.com/en-us/library/aa394372(VS.85).aspx 101 BASE_EXPORT bool WmiLaunchProcess(const std::wstring& command_line, 102 int* process_id); 103 104 // An encapsulation of information retrieved from the 'Win32_ComputerSystem' and 105 // 'Win32_Bios' WMI classes; see : 106 // https://docs.microsoft.com/en-us/windows/desktop/CIMWin32Prov/win32-computersystem 107 // https://docs.microsoft.com/en-us/windows/desktop/CIMWin32Prov/win32-systembios 108 // Note that while model and manufacturer can be obtained through WMI, it is 109 // more efficient to obtain them via SysInfo::GetHardwareInfo() which uses the 110 // registry. 111 class BASE_EXPORT WmiComputerSystemInfo { 112 public: 113 static WmiComputerSystemInfo Get(); 114 serial_number()115 const std::wstring& serial_number() const { return serial_number_; } 116 117 private: 118 void PopulateSerialNumber( 119 const Microsoft::WRL::ComPtr<IEnumWbemClassObject>& enumerator_bios); 120 121 std::wstring serial_number_; 122 }; 123 124 } // namespace win 125 } // namespace base 126 127 #endif // BASE_WIN_WMI_H_ 128