Struct wmi::connection::WMIConnection

pub struct WMIConnection { /* private fields */ }

Implementations

impl WMIConnection

A connection to the local WMI provider, which provides querying capabilities.

Currently does not support remote providers (e.g connecting to other computers).

pub fn new(com_lib: Rc<COMLibrary>) -> Result<Self, WMIError>

Creates a connection with a default CIMV2 namespace path.

pub fn with_namespace_path(
    namespace_path: &str,
    com_lib: Rc<COMLibrary>
) -> Result<Self, WMIError>

Creates a connection with the given namespace path.

let wmi_con = WMIConnection::with_namespace_path("ROOT\\Microsoft\\Windows\\Storage", COMLibrary::new()?.into())?;

pub unsafe fn with_initialized_com(
    namespace_path: Option<&str>
) -> Result<Self, WMIError>

Like with_namespace_path, but assumes that COM is managed externally.

Safety

This function is unsafe as it is the caller’s responsibility to ensure that COM is initialized and will not be uninitialized before the connection object is dropped.

let _initialized_com = COMLibrary::new()?;

// Later, in the same thread.
let wmi_con = unsafe { WMIConnection::with_initialized_com(Some("ROOT\\CIMV2"))? };

pub fn svc(&self) -> *mut IWbemServices

impl WMIConnection

pub fn exec_query_native_wrapper(
    &self,
    query: impl AsRef<str>
) -> Result<QueryResultEnumerator<'_>, WMIError>

Execute the given query and return an iterator of WMI pointers. It’s better to use the other query methods, since this is relatively low level.

pub fn raw_query<T>(&self, query: impl AsRef<str>) -> Result<Vec<T>, WMIError> where
    T: DeserializeOwned, 

Execute a free-text query and deserialize the results. Can be used either with a struct (like query and filtered_query), but also with a generic map.

let results: Vec<HashMap<String, Variant>> = con.raw_query("SELECT Name FROM Win32_OperatingSystem")?;

pub fn query<T>(&self) -> Result<Vec<T>, WMIError> where
    T: DeserializeOwned, 

Query all the objects of type T.

use wmi::*;
use serde::Deserialize;

let con = WMIConnection::new(COMLibrary::new()?.into())?;

#[derive(Deserialize, Debug)]
struct Win32_Process {
    Name: String,
}

let procs: Vec<Win32_Process> = con.query()?;

pub fn filtered_query<T>(
    &self,
    filters: &HashMap<String, FilterValue>
) -> Result<Vec<T>, WMIError> where
    T: DeserializeOwned, 

Query all the objects of type T, while filtering according to filters.

use serde::Deserialize;
#[derive(Deserialize, Debug)]
struct Win32_Process {
    Name: String,
}

let mut filters = HashMap::new();

filters.insert("Name".to_owned(), FilterValue::Str("cargo.exe"));

let results = con.filtered_query::<Win32_Process>(&filters).unwrap();

assert!(results.len() >= 1);

pub fn get<T>(&self) -> Result<T, WMIError> where
    T: DeserializeOwned, 

Get a single object of type T. If none are found, an error is returned. If more than one object is found, all but the first are ignored.

use serde::Deserialize;
#[derive(Deserialize)]
struct Win32_OperatingSystem {
    Name: String,
}

let os = con.get::<Win32_OperatingSystem>()?;

pub fn get_raw_by_path(
    &self,
    object_path: impl AsRef<str>
) -> Result<IWbemClassWrapper, WMIError>

Get a WMI object by path, and return a wrapper around a WMI pointer. It’s better to use the get_by_path method, since this function is more low level.

let raw_os = con.get_raw_by_path(r#"\\.\root\cimv2:Win32_OperatingSystem=@"#)?;
assert_eq!(raw_os.class()?, "Win32_OperatingSystem");

#[derive(Deserialize)]
struct Win32_OperatingSystem {
    Name: String,
}

let os: Win32_OperatingSystem = raw_os.into_desr()?;
println!("{}", os.Name);

pub fn get_by_path<T>(&self, object_path: &str) -> Result<T, WMIError> where
    T: DeserializeOwned, 

Get a WMI object by path, and return a deserialized object. This is useful when the type of the object at the path in known at compile time.

#[derive(Deserialize)]
struct Win32_OperatingSystem {
    Name: String,
}
let os = con.get_by_path::<Win32_OperatingSystem>(r#"\\.\root\cimv2:Win32_OperatingSystem=@"#)?;

It’s possible to have a path where the type of the WMI object is not known at compile time. Either use get_raw_by_path and the .class() to find out the real type of the object, or if the object is only of a few possible types, deserialize it to an enum:

#[derive(Deserialize, Debug, PartialEq)]
struct Win32_Group {
    __Path: String,
}

let mut filters = HashMap::new();
filters.insert("Name".into(), "Administrators".into());


let admin_group: Win32_Group = con
    .filtered_query(&filters)?
    .into_iter()
    .next()
    .unwrap();

#[derive(Deserialize, Debug, PartialEq)]
struct Win32_Account {
    __Path: String,
}

#[derive(Deserialize, Debug, PartialEq)]
struct Win32_UserAccount {
    Caption: String,
}

#[derive(Deserialize, Debug, PartialEq)]
struct Win32_SystemAccount {
    Caption: String,
}

#[derive(Deserialize, Debug, PartialEq)]
struct Win32_GroupUser{ }

// Groups contain multiple types of objects, all inheriting from `Win32_Account`.
let accounts_in_group: Vec<Win32_Account> = con.associators::<_, Win32_GroupUser>(&admin_group.__Path)?;

#[derive(Deserialize, Debug)]
enum User {
    #[serde(rename = "Win32_SystemAccount")]
    System(Win32_SystemAccount),
    #[serde(rename = "Win32_UserAccount")]
    User(Win32_UserAccount),
    #[serde(rename = "Win32_Group")]
    Group(Win32_Group),
};

for account in accounts_in_group {
    let user: User = con.get_by_path(&account.__Path)?;
    println!("{:?}", user);
}

pub fn associators<ResultClass, AssocClass>(
    &self,
    object_path: &str
) -> Result<Vec<ResultClass>, WMIError> where
    ResultClass: DeserializeOwned,
    AssocClass: DeserializeOwned, 

Query all the associators of type T of the given object. The object_path argument can be provided by querying an object wih it’s __Path property. AssocClass must be have the name as the conneting association class between the original object and the results. See https://docs.microsoft.com/en-us/windows/desktop/cimwin32prov/win32-diskdrivetodiskpartition for example.

#[derive(Deserialize, Debug)]
struct Win32_DiskDrive {
    // `__Path` is a WMI-internal property used to uniquely identify objects.
    __Path: String,
    Caption: String,
}

#[derive(Deserialize, Debug)]
struct Win32_DiskPartition {
    Caption: String,
}

// There's no need to specify any fields here, since only the name of the struct is used by `associators`.
#[derive(Deserialize, Debug)]
struct Win32_DiskDriveToDiskPartition {}

let disk = con.get::<Win32_DiskDrive>()?;
let results = con.associators::<Win32_DiskPartition, Win32_DiskDriveToDiskPartition>(&disk.__Path)?;

Trait Implementations

impl Drop for WMIConnection

fn drop(&mut self)

Executes the destructor for this type.