Skip to main content

Interface

windows_core

Trait 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> { ... }
}
Expand description

Provides low-level access to a COM interface vtable.

§Safety

Implementors must be transparent wrappers over an owned COM interface pointer. Vtable and IID must describe that interface, and cloning the wrapper must retain the COM reference.

Required Associated Constants§

const IID: GUID

The GUID associated with the interface.

Provided Methods§

fn as_raw(&self) -> *mut c_void

Returns the borrowed COM interface pointer.

fn into_raw(self) -> *mut c_void

Transfers ownership of the COM interface pointer to the caller.

unsafe fn from_raw(raw: *mut c_void) -> Self

Takes ownership of a COM interface pointer.

§Safety

raw must be owned and point to the vtable for Self, beginning with IUnknown.

unsafe fn from_raw_borrowed(raw: &*mut c_void) -> Option<&Self>

Borrows a COM interface pointer.

§Safety

raw must remain valid and point to the vtable for Self, beginning with IUnknown.

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

Queries the object for another interface.

fn cast_to_any<T>(&self) -> Result<&dyn Any>
where T: ComObjectInner, T::Outer: Any + 'static + IUnknownImpl<Impl = T>,

Returns the generated outer Rust implementation as [&dyn Any].

Applications should use Interface::cast_object_ref or Interface::cast_object instead.

The reference points to the generated outer type, such as MyApp_Impl, not MyApp.

Returns Err(E_NOINTERFACE) if the object is not a Rust object, not T, or contains non-static lifetimes.

§Safety

This uses a private QueryInterface protocol identified by DYNAMIC_CAST_IID. The implementation writes a two-pointer &dyn Any, not a COM interface pointer, to the output.

The protocol does not call AddRef. The returned reference must not outlive self, and only #[implement]-generated objects may recognize this IID.

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.

Returns false if the object is not a Rust object, not T, or contains non-static lifetimes.

fn cast_object_ref<T>(&self) -> Result<&T::Outer>
where T: ComObjectInner, T::Outer: Any + 'static + IUnknownImpl<Impl = T>,

Returns a borrowed reference to the generated outer Rust implementation.

Returns Err(E_NOINTERFACE) if the object is not a Rust object, not T, or contains non-static lifetimes.

The returned value is borrowed; use Interface::cast_object for an owned (counted) reference.

fn cast_object<T>(&self) -> Result<ComObject<T>>
where T: ComObjectInner, T::Outer: Any + 'static + IUnknownImpl<Impl = T>,

Returns an owned reference to the generated outer Rust implementation.

Returns Err(E_NOINTERFACE) if the object is not a Rust object, not T, or contains non-static lifetimes.

The returned value is an owned (counted) reference: this function calls AddRef. Use Interface::cast_object_ref to avoid AddRef / Release overhead if you do not need ownership.

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

Calls QueryInterface.

§Safety

interface must be a non-null, valid pointer for writing an interface pointer.

fn to_ref(&self) -> InterfaceRef<'_, Self>

Borrows this interface without changing its reference count.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§