Struct ComObject

pub struct ComObject<T: ComObjectInner> { /* private fields */ }

Expand description

A counted pointer to a heap-allocated type that implements COM interfaces.

This type lets you place an object onto the heap and query for COM interfaces without losing the safe reference to the implementation object.

Because the pointer inside is non-null, Option<ComObject<T>> is the same size as a single pointer.

§Safety

The contained ptr is an owned, reference-counted pointer to a pinned Pin<Box<T::Outer>>. The implementation does not currently use Pin<T> directly but is careful not to expose unsafe semantics to safe code; callers of unsafe functions on ComObject must preserve these invariants.

Implementations§

§

impl<T: ComObjectInner> ComObject<T>

pub fn new(value: T) -> Self

Allocates a heap cell (box) and moves value into it. Returns a counted pointer to value.

pub unsafe fn from_raw(ptr: NonNull<T::Outer>) -> Self

Creates a new ComObject from an existing boxed instance.

§Safety

ptr must point to a valid, heap-allocated T::Outer (typically from Box::into_raw(Box::new(...))).

The pointed-to box must have a reference count greater than zero.

This takes ownership of the existing pointer; it does not call AddRef. The reference count must accurately reflect all outstanding references to the box, including ptr.

pub fn get(&self) -> &T

Gets a reference to the shared object stored in the box.

ComObject also implements Deref, so it is often more convenient to deref directly. Use this method when the Deref impl is inconvenient.

pub fn get_mut(&mut self) -> Option<&mut T>

Gets a mutable reference to the object stored in the box, if the reference count is exactly 1. Returns None if there are multiple references.

pub fn take(self) -> Result<T, Self>

If this object has only a single reference (i.e. this ComObject is the only reference to the heap allocation), extracts the inner T and frees the heap allocation. Returns Err(self) if there is more than one reference.

pub fn cast<I: Interface>(&self) -> Result
where T::Outer: ComObjectInterface<IUnknown>,

Casts to the given interface type.

This always performs a QueryInterface, even if T is known to implement I. If you know that T implements I, use Self::as_interface or Self::to_interface instead to avoid the dynamic QueryInterface call.

pub fn as_interface<I: Interface>(&self) -> InterfaceRef<'_, I>
where T::Outer: ComObjectInterface,

Gets a borrowed reference to an interface that is implemented by T.

The returned reference is not AddRefed; call InterfaceRef::to_owned to obtain an owned reference.

pub fn to_interface<I: Interface>(&self) -> I
where T::Outer: ComObjectInterface,

Gets an owned (counted) reference to an interface that is implemented by this ComObject.

pub fn into_interface<I: Interface>(self) -> I
where T::Outer: ComObjectInterface,

Converts self into an interface that it implements.

This does not need to adjust reference counts because self is consumed.

pub fn cast_from(interface: &I) -> Result<Self>
where I: Interface, T::Outer: Any + 'static + IUnknownImpl<Impl = T>,

Casts the given COM interface to &dyn Any, returning a reference to the “outer” object (e.g. MyApp_Impl), not the inner MyApp.

T must be a type annotated with #[implement]; this is enforced at compile time by the generic constraints.

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. If you do not need an owned reference, use Interface::cast_object_ref instead to avoid the AddRef / Release overhead.