This update introduces a number of improvements to the implement and interface macros as well as the windows-core crate that work together to enhance support for COM interface declarations and implementations as well as general FFI/ABI support.
This function must be exported by DLLs for WinRT (COM) support. The ABI requirements are such that the HSTRING and IActivationFactory types are "borrowed" in the sense that neither the caller nor the callee must free or drop those values as part of the call itself. This leads to Rust developers having to write something like this:
The implementation is then forced to carefully consider and manage lifetimes and transfer ownership and is easy to get wrong.
The Ref and OutRef types represent borrowed types, providing the same memory layout but also offer lifetime management and conveniences to make dealing with in and out parameters safe and convenient:
Ref implements the Deref trait that returns a reference to the borrowed type while OutRef provides the write method that will overwrite the memory location with the given value. The write method can only be called once and checks for null. It also provides the is_null method if you need to conditionally support optional out parameters.
The interface macro will also generate bindings for Ref and OutRef that behave like the bindings generated by the windows-bindgen crate, making it easier to call such interface methods naturally from Rust. This leverages the new ParamMut trait that compliments the existing Param trait for handling out parameters. It takes care of dealing with uninitialized memory in out parameters as well as dropping &mut values in Rust to avoid leaks.
In addition, the interface macro now supports Result return types for convenience. The underlying virtual function will still return an HRESULT but the interface and implement macros will automatically translate that for you:
This update introduces a number of improvements to the
implement
andinterface
macros as well as thewindows-core
crate that work together to enhance support for COM interface declarations and implementations as well as general FFI/ABI support.Consider the following C++ function signature:
This function must be exported by DLLs for WinRT (COM) support. The ABI requirements are such that the
HSTRING
andIActivationFactory
types are "borrowed" in the sense that neither the caller nor the callee must free or drop those values as part of the call itself. This leads to Rust developers having to write something like this:The implementation is then forced to carefully consider and manage lifetimes and transfer ownership and is easy to get wrong.
The
Ref
andOutRef
types represent borrowed types, providing the same memory layout but also offer lifetime management and conveniences to make dealing with in and out parameters safe and convenient:Ref
implements theDeref
trait that returns a reference to the borrowed type whileOutRef
provides thewrite
method that will overwrite the memory location with the given value. Thewrite
method can only be called once and checks for null. It also provides theis_null
method if you need to conditionally support optional out parameters.The
interface
macro will also generate bindings forRef
andOutRef
that behave like the bindings generated by thewindows-bindgen
crate, making it easier to call such interface methods naturally from Rust. This leverages the newParamMut
trait that compliments the existingParam
trait for handling out parameters. It takes care of dealing with uninitialized memory in out parameters as well as dropping&mut
values in Rust to avoid leaks.In addition, the
interface
macro now supportsResult
return types for convenience. The underlying virtual function will still return anHRESULT
but theinterface
andimplement
macros will automatically translate that for you: