Trait windows_core::Interface

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: Interface>(&self) -> Result<T> { ... }
    fn cast_to_any<T>(&self) -> Result<&dyn Any>
       where T: ComObjectInner,
             T::Outer: Any + 'static + IUnknownImpl<Impl = T> { ... }
    fn is_object<T>(&self) -> bool
       where T: ComObjectInner,
             T::Outer: Any + 'static + IUnknownImpl<Impl = T> { ... }
    fn cast_object_ref<T>(&self) -> Result<&T::Outer>
       where T: ComObjectInner,
             T::Outer: Any + 'static + IUnknownImpl<Impl = T> { ... }
    fn cast_object<T>(&self) -> Result<ComObject<T>>
       where T: ComObjectInner,
             T::Outer: Any + 'static + IUnknownImpl<Impl = T> { ... }
    fn downgrade(&self) -> Result<Weak<Self>> { ... }
    unsafe fn query(
        &self,
        iid: *const GUID,
        interface: *mut *mut c_void,
    ) -> HRESULT { ... }
    fn to_ref(&self) -> InterfaceRef<'_, Self> { ... }
}

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

const IID: GUID

The GUID associated with the interface.

Provided Methods

fn as_raw(&self) -> *mut c_void

Returns the raw COM interface pointer. The resulting pointer continues to be owned by the Interface implementation.

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.

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.

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.

fn cast<T: Interface>(&self) -> Result<T>

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.

fn cast_to_any<T>(&self) -> Result<&dyn Any>

where T: ComObjectInner, T::Outer: Any + 'static + IUnknownImpl<Impl = T>,

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 QueryInterface implementations that recognize DYNAMIC_CAST_IID are generated by the #[implement] macro and respect the rules described here.

fn is_object<T>(&self) -> bool

where T: ComObjectInner, T::Outer: Any + 'static + IUnknownImpl<Impl = T>,

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.

fn cast_object_ref<T>(&self) -> Result<&T::Outer>

where T: ComObjectInner, T::Outer: Any + 'static + IUnknownImpl<Impl = T>,

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.

fn cast_object<T>(&self) -> Result<ComObject<T>>

where T: ComObjectInner, T::Outer: Any + 'static + IUnknownImpl<Impl = T>,

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.

fn downgrade(&self) -> Result<Weak<Self>>

Attempts to create a Weak reference to this object.

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.

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).

Object Safety

This trait is not object safe.

Implementors

impl Interface for IInspectable

const IID: GUID = _

impl Interface for IUnknown

const IID: GUID = _