Struct windows_core::ComObject

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

Expand description

A counted pointer to a type that implements COM interfaces, where the object has been placed in the heap (boxed).

This type exists so that you can place an object into the heap and query for COM interfaces, without losing the safe reference to the implementation object.

Because the pointer inside this type is known to be non-null, Option<ComObject<T>> should always have the same size as a single pointer.

§Safety

The contained ptr field is an owned, reference-counted pointer to a pinned Pin<Box<T::Outer>>. Although this code does not currently use Pin<T>, it takes care not to expose any unsafe semantics to safe code. However, code that calls unsafe functions on ComObject must, like all unsafe code, understand and preserve 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 that points to an existing boxed instance.

§Safety

The caller must ensure that ptr points to a valid, heap-allocated instance of T::Outer. Normally, this pointer comes from using Box::into_raw(Box::new(...)).

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

This function 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 in the count.

pub fn get(&self) -> &T

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

ComObject also implements Deref, so you can often deref directly into the object. For those situations where using the Deref impl is inconvenient, you can use this method to explicitly get a reference to the contents.

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. If there are multiple references to this object then this returns None.

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

If this object has only a single object reference (i.e. this ComObject is the only reference to the heap allocation), then this method will extract the inner T (and return it in an Ok) and then free the heap allocation.

If there is more than one reference to this object, then this returns Err(self).

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

Casts to a given interface type.

This always performs a QueryInterface, even if T is known to implement I. If you know that T implements I, then use Self::as_interface or Self::to_interface because those functions do not require a 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 does not have an additional reference count. You can AddRef it by calling [Self::to_owned].

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>,

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.