[][src]Crate mcom

MaulingMonkey's COM interfaces/types/wrappers.

Smart Pointers

Rc❌ noN/AN/A2000+anyYour basic, super vanilla, apartment & thread-local COM pointer.
Git✔️ yes✔️ yes❌ no2000+anyIGlobalInterfaceTable-based COM pointer.
Agile✔️ yes✔️ yes✔️ yes⚠️ 8.1+gamesIAgileReference-based COM pointer.

COM interfaces have complicated thread safety guarantees - when they have thread safety guarantees at all. While some of those guarantees can be expressed through the type system (e.g. many/most WinRT interfaces are guaranteed agile), many of the more subtle ones can only be effectively expressed at runtime.

For example, an interface pointer to a given COM object might be usable on other threads of a MTA apartment, but not on STA threads. While we could have some kind of MTA token type only constructable on MTA threads, and require that for accessing the smart pointer, such a token would likely need to be retrieved at runtime anyways - and just add more steps an extra complexity.

Since WinRT's free-threaded agile guarantees are the only ones that really line up well with WinRT's type system, and WinRT's rich metadata calls for WinRT-specific crates that can tackle that (e.g. winrt), that leaves this crate to tackle the messier runtime-enforced thread safety of more vanilla COM.

All these smart pointers assume the COM interface implements IUnknown. It's worth noting that some "COM" interfaces like ID3D12FunctionReflection do not implement IUnknown, and cannot be held in any of these COM smart pointers as a result.

LazyErrors out when converting Agile/Git 🠆 Rc if the COM object is being being used in another COM Apartment, unless it is safe to do so. This is usable even for unmarshalable types (such as Direct3D interfaces) if you stay within the appropriate COM apartment and they implement IUnknown.
EagerErrors out when converting Rc 🠆 Agile/Git if the COM object isn't portable between COM Apartments (e.g. not 100% thread safe) and cannot be wrapped in a marshaling layer that would make it portable.
WindowsWhat version of windows is required for this interface. Most APIs are marked 2000+ because that's what docs.microsoft.com says, but likely predate Windows 2000.
PartitionWINAPI_PARTITION_* references, as selected by winapi-family-* features. Allows hiding e.g. CoCreateInstance from UWP apps that must use CoCreateInstanceFromApp instead. See winapifamily.h for more details.

Known Soundness Holes & Undefined Behavior Bait

winapi#961 details some of these:

This crate is technically globally sound (you cannot construct the types that allow UB without unsafe), but bogus/evil-but-safe implementations of winapi traits can make safe-looking code locally unsound (e.g. a "safe" cast could invoke UB.) While this does offend my sensibilities a bit, I will fix it if/when able (e.g. if winapi can provide me with the necessary tools), and any reasonable implementor of such traits will be filling the file with the unsafe keyword anyways.

Crate Features

✔️ All windows version related features are enabled by default.
❌ All crate interop features are disabled by default.

Expose APIs by required windows version. Highest version wins.
✔️ windows-latestEnable APIs that require the most recent version of Windows
✔️ windows-10
✔️ windows-8-1Enable APIs that require Windows 8.1 or later (Agile)
✔️ windows-8
✔️ windows-7
✔️ windows-vista
✔️ windows-xp
✔️ windows-2000Enable APIs that require Windows 2000 or later (most of this crate)
Expose APIs by windows environment. Recommend picking one at a time.
✔️ winapi-family-allEnable APIs available to absolutely everything at once
✔️ winapi-family-desktop-appEnable APIs available to Desktop-only non-store apps
✔️ winapi-family-pc-appEnable APIs available to Desktop-only store apps
✔️ winapi-family-phone-appEnable APIs available to Phone-only apps
✔️ winapi-family-systemEnable APIs available to Drivers and Tools
✔️ winapi-family-serverEnable APIs available to Windows Server applications
✔️ winapi-family-gamesEnable APIs available to Games and Applications
Interop with "peer" crates.
❌ com-0-3com = "0.3" interop (convert between Rc<IUnknown> ⮀ com::interfaces::IUnknown)
❌ wio-0-2wio = "0.2" interop (convert between Rcwio::com::ComPtr)





Wrappers around CoInitializeEx etc. for initializing COM.



A Send+Sync, IAgileReference-held interface pointer.


A Send+Sync, IGlobalInterfaceTable-held interface pointer.


A !Send+!Sync basic reference counting smart pointer residing within the current COM apartment.