pub unsafe trait Interface: Sized + Clone {
const IID: GUID;
// Provided methods
fn as_raw(&self) -> *mut c_void { ... }
fn into_raw(self) -> *mut c_void { ... }
unsafe fn from_raw(raw: *mut c_void) -> Self { ... }
unsafe fn from_raw_borrowed(raw: &*mut c_void) -> Option<&Self> { ... }
fn cast<T>(&self) -> Result<T, Error>
where T: Interface { ... }
fn cast_to_any<T>(&self) -> Result<&(dyn Any + 'static), Error>
where T: ComObjectInner,
<T as ComObjectInner>::Outer: Any + 'static + IUnknownImpl<Impl = T> { ... }
fn is_object<T>(&self) -> bool
where T: ComObjectInner,
<T as ComObjectInner>::Outer: Any + 'static + IUnknownImpl<Impl = T> { ... }
fn cast_object_ref<T>(&self) -> Result<&<T as ComObjectInner>::Outer, Error>
where T: ComObjectInner,
<T as ComObjectInner>::Outer: Any + 'static + IUnknownImpl<Impl = T> { ... }
fn cast_object<T>(&self) -> Result<ComObject<T>, Error>
where T: ComObjectInner,
<T as ComObjectInner>::Outer: Any + 'static + IUnknownImpl<Impl = T> { ... }
fn downgrade(&self) -> Result<Weak<Self>, Error> { ... }
unsafe fn query(
&self,
iid: *const GUID,
interface: *mut *mut c_void,
) -> HRESULT { ... }
fn to_ref(&self) -> InterfaceRef<'_, Self> { ... }
}Expand description
Provides low-level access to an interface vtable.
This trait is automatically implemented by the generated bindings and should not be implemented manually.
§Safety
Required Associated Constants§
Provided Methods§
sourcefn as_raw(&self) -> *mut c_void
fn as_raw(&self) -> *mut c_void
Returns the raw COM interface pointer. The resulting pointer continues to be owned by the Interface implementation.
sourcefn into_raw(self) -> *mut c_void
fn into_raw(self) -> *mut c_void
Returns the raw COM interface pointer and releases ownership. It the caller’s responsibility to release the COM interface pointer.
sourceunsafe fn from_raw(raw: *mut c_void) -> Self
unsafe fn from_raw(raw: *mut c_void) -> Self
Creates an Interface by taking ownership of the raw COM interface pointer.
§Safety
The raw pointer must be owned by the caller and represent a valid COM interface pointer. In other words,
it must point to a vtable beginning with the IUnknown function pointers and match the vtable of Interface.
sourceunsafe fn from_raw_borrowed(raw: &*mut c_void) -> Option<&Self>
unsafe fn from_raw_borrowed(raw: &*mut c_void) -> Option<&Self>
Creates an Interface that is valid so long as the raw COM interface pointer is valid.
§Safety
The raw pointer must be a valid COM interface pointer. In other words, it must point to a vtable
beginning with the IUnknown function pointers and match the vtable of Interface.
sourcefn cast<T>(&self) -> Result<T, Error>where
T: Interface,
fn cast<T>(&self) -> Result<T, Error>where
T: Interface,
Attempts to cast the current interface to another interface using QueryInterface.
The name cast is preferred to query because there is a WinRT method named query but not one
named cast.
sourcefn cast_to_any<T>(&self) -> Result<&(dyn Any + 'static), Error>
fn cast_to_any<T>(&self) -> Result<&(dyn Any + 'static), Error>
This casts the given COM interface to [&dyn Any].
Applications should generally not call this method directly. Instead, use the
Interface::cast_object_ref or Interface::cast_object methods.
T must be a type that has been annotated with #[implement]; this is checked at
compile-time by the generic constraints of this method. However, note that the
returned &dyn Any refers to the outer implementation object that was generated by
#[implement], i.e. the MyApp_Impl type, not the inner MyApp type.
If the given object is not a Rust object, or is a Rust object but not T, or is a Rust
object that contains non-static lifetimes, then this function will return Err(E_NOINTERFACE).
§Safety
IMPORTANT!! This uses a non-standard protocol for QueryInterface! The DYNAMIC_CAST_IID
IID identifies this protocol, but there is no IDynamicCast interface. Instead, objects
that recognize DYNAMIC_CAST_IID simply store their &dyn Any directly at the interface
pointer that was passed to QueryInterface. This means that the returned value has a size that is twice as large (size_of::<&dyn Any>() == 2 * size_of::<*const c_void>()`).
This means that callers that use this protocol cannot simply pass &mut ptr for
an ordinary single-pointer-sized pointer. Only this method understands this protocol.
Another part of this protocol is that the implementation of QueryInterface does not
AddRef the object. The caller must guarantee the liveness of the COM object. In Rust,
this means tying the lifetime of the IUnknown* that we used for the QueryInterface
call to the lifetime of the returned &dyn Any value.
This method preserves type safety and relies on these invariants:
- All
QueryInterfaceimplementations that recognizeDYNAMIC_CAST_IIDare generated by the#[implement]macro and respect the rules described here.
sourcefn is_object<T>(&self) -> bool
fn is_object<T>(&self) -> bool
Returns true if the given COM interface refers to an implementation of T.
T must be a type that has been annotated with #[implement]; this is checked at
compile-time by the generic constraints of this method.
If the given object is not a Rust object, or is a Rust object but not T, or is a Rust
object that contains non-static lifetimes, then this function will return false.
sourcefn cast_object_ref<T>(&self) -> Result<&<T as ComObjectInner>::Outer, Error>
fn cast_object_ref<T>(&self) -> Result<&<T as ComObjectInner>::Outer, Error>
This casts the given COM interface to [&dyn Any]. It returns a reference to the “outer”
object, e.g. &MyApp_Impl, not the inner &MyApp object.
T must be a type that has been annotated with #[implement]; this is checked at
compile-time by the generic constraints of this method. However, note that the
returned &dyn Any refers to the outer implementation object that was generated by
#[implement], i.e. the MyApp_Impl type, not the inner MyApp type.
If the given object is not a Rust object, or is a Rust object but not T, or is a Rust
object that contains non-static lifetimes, then this function will return Err(E_NOINTERFACE).
The returned value is borrowed. If you need an owned (counted) reference, then use
Interface::cast_object.
sourcefn cast_object<T>(&self) -> Result<ComObject<T>, Error>
fn cast_object<T>(&self) -> Result<ComObject<T>, Error>
This casts the given COM interface to [&dyn Any]. It returns a reference to the “outer”
object, e.g. MyApp_Impl, not the inner MyApp object.
T must be a type that has been annotated with #[implement]; this is checked at
compile-time by the generic constraints of this method. However, note that the
returned &dyn Any refers to the outer implementation object that was generated by
#[implement], i.e. the MyApp_Impl type, not the inner MyApp type.
If the given object is not a Rust object, or is a Rust object but not T, or is a Rust
object that contains non-static lifetimes, then this function will return Err(E_NOINTERFACE).
The returned value is an owned (counted) reference; this function calls AddRef on the
underlying COM object. If you do not need an owned reference, then you can use the
Interface::cast_object_ref method instead, and avoid the cost of AddRef / Release.
sourcefn downgrade(&self) -> Result<Weak<Self>, Error>
fn downgrade(&self) -> Result<Weak<Self>, Error>
Attempts to create a Weak reference to this object.
sourceunsafe fn query(&self, iid: *const GUID, interface: *mut *mut c_void) -> HRESULT
unsafe fn query(&self, iid: *const GUID, interface: *mut *mut c_void) -> HRESULT
Call QueryInterface on this interface
§Safety
interface must be a non-null, valid pointer for writing an interface pointer.
sourcefn to_ref(&self) -> InterfaceRef<'_, Self>
fn to_ref(&self) -> InterfaceRef<'_, Self>
Creates an InterfaceRef for this reference. The InterfaceRef tracks lifetimes statically,
and eliminates the need for dynamic reference count adjustments (AddRef/Release).