Skip to main content

Crate wincom

Crate wincom 

Source
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 an IDispatch and exposes property reads/writes and method invocation by name.
  • [Variant] is a RAII wrapper over VARIANT that calls VariantClear on 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).