Expand description
MaulingMonkey’s COM interfaces/types/wrappers.
Smart Pointers
| Type | Send Sync | Lazy | Eager | Windows | Partition | Description |
|---|---|---|---|---|---|---|
Rc | ❌ no | N/A | N/A | 2000+ | any | Your basic, super vanilla, apartment & thread-local COM pointer. |
Git | ✔️ yes | ✔️ yes | ❌ no | 2000+ | any | IGlobalInterfaceTable-based COM pointer. |
Agile | ✔️ yes | ✔️ yes | ✔️ yes | ⚠️ 8.1+ | ❌ | IAgileReference-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.
| Legend | Description |
|---|---|
| Lazy | Errors 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. |
| Eager | Errors 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. |
| Windows | What 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. |
| Partition | WINAPI_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:
- Rc<ID3D12FunctionReflection> and other smart pointer combinations compile, despite ID3D12FunctionReflection not implementing IUnknown, resulting in UB if used.
- Bogus winapi::Interface implementations can allow casting COM interfaces to unrelated rust structs
- Bogus Deref<Target=IUnknown> implementations can return dangling vtables, fn ptrs, or the wrong object
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.
| Feature | Description |
|---|---|
| Expose APIs by required windows version. Highest version wins. | |
| ✔️ windows-latest | Enable APIs that require the most recent version of Windows |
| ✔️ windows-10 | |
| ✔️ windows-8-1 | Enable APIs that require Windows 8.1 or later (Agile) |
| ✔️ windows-8 | |
| ✔️ windows-7 | |
| ✔️ windows-vista | |
| ✔️ windows-xp | |
| ✔️ windows-2000 | Enable APIs that require Windows 2000 or later (most of this crate) |
| Expose APIs by windows environment. Recommend picking one at a time. | |
| ✔️ winapi-family-all | Enable APIs available to absolutely everything at once |
| ✔️ winapi-family-desktop-app | Enable APIs available to Desktop-only non-store apps |
| ✔️ winapi-family-pc-app | Enable APIs available to Desktop-only store apps |
| ✔️ winapi-family-phone-app | Enable APIs available to Phone-only apps |
| ✔️ winapi-family-system | Enable APIs available to Drivers and Tools |
| ✔️ winapi-family-server | Enable APIs available to Windows Server applications |
| ✔️ winapi-family-games | Enable APIs available to Games and Applications |
| Interop with “peer” crates. | |
| ❌ com-0-3 | com = "0.3" interop (convert between Rc<IUnknown> ⮀ com::interfaces::IUnknown) |
| ❌ wio-0-2 | wio = "0.2" interop (convert between Rc ⮀ wio::com::ComPtr) |