1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
//! 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
//!
//! ```no_run
//! use wincom::{ComObject, Variant};
//!
//! # fn main() -> wincom::Result<()> {
//! // 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;
//! # Ok(())
//! # }
//! ```
//!
//! # 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:
//!
//! ```no_run
//! # fn main() -> windows::core::Result<()> {
//! use windows::Win32::System::Com;
//! unsafe { Com::CoInitialize(None).ok()? };
//! // ... use ComObject ...
//! unsafe { Com::CoUninitialize() };
//! # Ok(())
//! # }
//! ```
//!
//! # 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).
//!
//! [COM Automation]: https://learn.microsoft.com/en-us/windows/win32/com/automation
pub use ComObject;
pub use ;
pub use ;