Expand description
Windows COM IDispatch automation for Rust.
wincom provides a thin, ergonomic wrapper around the Windows
COM Automation interfaces. It focuses on the IDispatch late-binding
path, which is what most scripting hosts (AutoCAD, CorelDRAW, Office, …)
expose.
§Features
- [
ComObject] wraps anIDispatchand exposes property reads/writes and method invocation by name. - [
Variant] is a RAII wrapper overVARIANTthat callsVariantClearon drop, eliminating a common source of leaks in COM code. - Conversions to and from native Rust types (
i32,f64,String,bool,Vec<f64>, …) are provided via [Variant]’s methods.
§Example
use wincom::{ComObject, Variant};
// Bind to a running instance of CorelDRAW via its ProgID.
let app = ComObject::new_from_active("CorelDRAW.Application")?;
// Read a property and convert it to a Rust value.
let version: String = app.get_property("Version")?.to_string()?;
println!("CorelDRAW version: {version}");
// Write a property.
app.set_property("Visible", vec![Variant::from_bool(true)])?;
// Call a method.
let doc = app.invoke_method("AddDocument", Vec::new())?;
let _ = doc;§Platform
This crate only compiles on Windows. On other platforms the crate is
empty (behind #![cfg(windows)]).
§Threading
COM objects are apartment-bound: an IDispatch obtained on one
thread must not be used from another without marshalling. Consequently,
[ComObject] is !Send and !Sync. To use a COM object from multiple
threads, marshal it with CoMarshalInterThreadInterfaceInStream or
create a separate object per thread.
§Initialization
wincom does not call CoInitialize for you. Every thread that
uses a [ComObject] must first initialize COM:
use windows::Win32::System::Com;
unsafe { Com::CoInitialize(None).ok()? };
// ... use ComObject ...
unsafe { Com::CoUninitialize() };§Error handling
All fallible operations return Result<T>, where the error type is
[Error]. HRESULT values from COM are preserved and can be inspected
via [Error::Windows].
§Minimum supported Rust version
Rust 1.71 or later is required (windows-link depends on the
stable raw-dylib feature).