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 <string_view> 27 28 #include "base/base_export.h" 29 #include "third_party/abseil-cpp/absl/types/optional.h" 30 31 namespace base { 32 namespace win { 33 34 // Enumeration of errors that can arise when connecting to a WMI server and 35 // running a query. 36 // Do not change ordering. This enum is captured as `WmiQueryError` in 37 // enums.xml. 38 enum class WmiError { 39 kFailedToCreateInstance = 0, 40 kFailedToConnectToWMI = 1, 41 kFailedToSetSecurityBlanket = 2, 42 kFailedToExecWMIQuery = 3, 43 kMaxValue = kFailedToExecWMIQuery 44 }; 45 46 // String used to connect to the CIMV2 WMI server. 47 BASE_EXPORT extern const wchar_t kCimV2ServerName[]; 48 49 // String used to connect to the SecurityCenter2 WMI server. 50 BASE_EXPORT extern const wchar_t kSecurityCenter2ServerName[]; 51 52 // Connects to a server named `server_name` on the local computer through COM 53 // and run the given WQL `query`. Sets `enumerator` with the values returned by 54 // that `query`. Will return a WmiError value if an error occurs, else returns 55 // absl::nullopt. 56 BASE_EXPORT absl::optional<WmiError> RunWmiQuery( 57 const std::wstring& server_name, 58 const std::wstring& query, 59 Microsoft::WRL::ComPtr<IEnumWbemClassObject>* enumerator); 60 61 // Creates an instance of the WMI service connected to the local computer and 62 // returns its COM interface. If |set_blanket| is set to true, the basic COM 63 // security blanket is applied to the returned interface. This is almost 64 // always desirable unless you set the parameter to false and apply a custom 65 // COM security blanket. 66 // Returns true if succeeded and |wmi_services|: the pointer to the service. 67 BASE_EXPORT bool CreateLocalWmiConnection( 68 bool set_blanket, 69 Microsoft::WRL::ComPtr<IWbemServices>* wmi_services); 70 71 // Creates an instance of the WMI service connected to the resource and 72 // returns its COM interface. If |set_blanket| is set to true, the basic COM 73 // security blanket is applied to the returned interface. This is almost 74 // always desirable unless you set the parameter to false and apply a custom 75 // COM security blanket. 76 // Returns a valid ComPtr<IWbemServices> on success, nullptr on failure. 77 BASE_EXPORT Microsoft::WRL::ComPtr<IWbemServices> CreateWmiConnection( 78 bool set_blanket, 79 const std::wstring& resource); 80 81 // Creates a WMI method using from a WMI class named |class_name| that 82 // contains a method named |method_name|. Only WMI classes that are CIM 83 // classes can be created using this function. 84 // Returns true if succeeded and |class_instance| returns a pointer to the 85 // WMI method that you can fill with parameter values using SetParameter. 86 BASE_EXPORT bool CreateWmiClassMethodObject( 87 IWbemServices* wmi_services, 88 std::wstring_view class_name, 89 std::wstring_view method_name, 90 Microsoft::WRL::ComPtr<IWbemClassObject>* class_instance); 91 92 // Creates a new process from |command_line|. The advantage over CreateProcess 93 // is that it allows you to always break out from a Job object that the caller 94 // is attached to even if the Job object flags prevent that. 95 // Returns true and the process id in process_id if the process is launched 96 // successful. False otherwise. 97 // Note that a fully qualified path must be specified in most cases unless 98 // the program is not in the search path of winmgmt.exe. 99 // Processes created this way are children of wmiprvse.exe and run with the 100 // caller credentials. 101 // More info: http://msdn2.microsoft.com/en-us/library/aa394372(VS.85).aspx 102 BASE_EXPORT bool WmiLaunchProcess(const std::wstring& command_line, 103 int* process_id); 104 105 // An encapsulation of information retrieved from the 'Win32_ComputerSystem' and 106 // 'Win32_Bios' WMI classes; see : 107 // https://docs.microsoft.com/en-us/windows/desktop/CIMWin32Prov/win32-computersystem 108 // https://docs.microsoft.com/en-us/windows/desktop/CIMWin32Prov/win32-systembios 109 // Note that while model and manufacturer can be obtained through WMI, it is 110 // more efficient to obtain them via SysInfo::GetHardwareInfo() which uses the 111 // registry. 112 class BASE_EXPORT WmiComputerSystemInfo { 113 public: 114 static WmiComputerSystemInfo Get(); 115 serial_number()116 const std::wstring& serial_number() const { return serial_number_; } 117 118 private: 119 void PopulateSerialNumber( 120 const Microsoft::WRL::ComPtr<IEnumWbemClassObject>& enumerator_bios); 121 122 std::wstring serial_number_; 123 }; 124 125 } // namespace win 126 } // namespace base 127 128 #endif // BASE_WIN_WMI_H_ 129