ferroui_microcom/lib.rs
1//! ferroui-microcom
2//!
3//! Minimal COM runtime used by the bindings that `microcom-codegen` generates
4//! from MicroCom IDL files (the Rust counterpart of the MicroCom runtime and its callback base class).
5//!
6//! Two directions are covered:
7//!
8//! * **native -> Rust proxies**: an interface type such as `IFrnWindow` is a
9//! `#[repr(C)]` struct whose only field is the vtable pointer, i.e. a
10//! `*mut IFrnWindow` *is* the native interface pointer. [`ComPtr<T>`] owns
11//! one reference to such an object (`AddRef` on clone, `Release` on drop)
12//! and derefs to `&T`, on which the generated methods live.
13//! * **Rust -> native callbacks** (COM callable wrappers): [`ComObject<T>`]
14//! is one interface of a Rust value as native code sees it: a vtable
15//! pointer, followed by a pointer to the object, which holds an atomic
16//! reference count, the wrappers of its interfaces and the Rust value.
17//! Generated code provides the vtables (`extern "system"` thunks) for
18//! every `T` implementing the interface's `...Impl` trait through
19//! [`ImplementedBy`]. [`make_com`] makes an object with one interface,
20//! [`make_com_with`] one with several, each of which answers
21//! `QueryInterface` for all of them.
22//!
23//! ABI: Itanium C++ single-inheritance layout — slot 0..2 are
24//! `QueryInterface`, `AddRef`, `Release`, followed by the methods of each
25//! interface in the chain in declaration order; `this` is the first argument
26//! of every slot. The calling convention is the one of the system
27//! (`extern "system"`): the C convention on every target but 32-bit x86
28//! Windows, where COM is `stdcall`. On that target a virtual method of the
29//! system's COM returns a structure through a hidden parameter after `this`,
30//! which the generated signatures do not model: no interface the port binds
31//! returns one.
32
33mod com_object;
34mod com_ptr;
35mod guid;
36mod hresult;
37mod unknown;
38
39pub use com_object::{make_com, make_com_with, set_inner, ComObject, ImplementedBy, InterfaceEntry};
40pub use com_ptr::ComPtr;
41pub use guid::Guid;
42pub use hresult::{
43 HResult, RawHResult, COR_E_INVALIDOPERATION, COR_E_OBJECTDISPOSED, E_ABORT, E_FAIL, E_HANDLE,
44 E_INVALIDARG, E_NOINTERFACE, E_NOTIMPL, E_POINTER, E_UNEXPECTED, S_OK,
45};
46pub use unknown::{IUnknown, IUnknownImpl, IUnknownVtbl, Interface};
47
48/// Result of a COM call returning `HRESULT`.
49pub type ComResult<T> = Result<T, HResult>;