wincom 0.3.0

A lightweight Rust wrapper for Windows COM IDispatch automation, providing RAII VARIANT management and simplified property/method invocation.
Documentation
//! 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

#![cfg(windows)]
#![warn(missing_docs)]
#![warn(rustdoc::broken_intra_doc_links)]
#![warn(rustdoc::private_intra_doc_links)]

pub mod dispatch;
pub mod err;
pub mod variant;

pub use dispatch::ComObject;
pub use err::{Error, Result};
pub use variant::{Variant, VariantExt};