Struct windows_core::ComObject

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

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

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

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 InterfaceRef::to_owned.

pub fn to_interface<I: Interface>(&self) -> I

where T::Outer: ComObjectInterface<I>,

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

Converts self into an interface that it implements.

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

pub fn cast_from<I>(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.

Trait Implementations

impl<T: ComObjectInner> AsRef<T> for ComObject<T>

where IUnknown: From<T> + AsImpl<T>,

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: ComObjectInner> Borrow<T> for ComObject<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: ComObjectInner> Clone for ComObject<T>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: ComObjectInner + Debug> Debug for ComObject<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: ComObjectInner + Default> Default for ComObject<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T: ComObjectInner> Deref for ComObject<T>

type Target = <T as ComObjectInner>::Outer

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: ComObjectInner + Display> Display for ComObject<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: ComObjectInner> Drop for ComObject<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<T: ComObjectInner> From<T> for ComObject<T>

fn from(value: T) -> ComObject<T>

Converts to this type from the input type.

impl<T: ComObjectInner + Hash> Hash for ComObject<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: ComObjectInner + Ord> Ord for ComObject<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl<T: ComObjectInner + PartialEq> PartialEq for ComObject<T>

fn eq(&self, other: &ComObject<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T: ComObjectInner + PartialOrd> PartialOrd for ComObject<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T: ComObjectInner + Eq> Eq for ComObject<T>

impl<T: ComObjectInner + Send> Send for ComObject<T>

impl<T: ComObjectInner + Sync> Sync for ComObject<T>