Struct vst3::ComPtr

pub struct ComPtr<I>
where
    I: Interface,
{ /* private fields */ }

An owning smart pointer to a COM object.

A ComPtr<I> represents an owning reference to a COM object implementing interface I. Like ComRef, ComPtr can be used to call interface methods on the referenced object. Unlike ComRef, ComPtr manages the object’s reference count, i.e. it will call the release method of the object it points to when going out of scope. See the crate-level documentation for more information.

A ComPtr can be created safely from a ComRef via ComRef::to_com_ptr, or from a ComWrapper via ComWrapper::to_com_ptr. It can also be created unsafely via ComPtr::from_raw.

Implementations

impl<I> ComPtr<I>

where I: Interface,

pub fn as_ptr(&self) -> *mut I

Gets the wrapped interface pointer.

Does not perform any reference counting operations.

pub unsafe fn from_raw(ptr: *mut I) -> Option<ComPtr<I>>

Creates a ComPtr from a raw interface pointer if the pointer is non-null.

When the resulting ComPtr is dropped, the reference count of the object it points to will be decremented. Thus, using this method can be thought of as “taking ownership” of a pointer to a COM object.

from_raw will check if ptr is null (and return None if so), but this method is still unsafe, as the caller must still ensure that ptr is a valid interface pointer (see below) if it is non-null.

Safety

If ptr is non-null, it must be a valid pointer to a value of type I, and if *ptr is reinterpreted as *const I::Vtbl (see the safety documentation for Interface), it must in turn be a valid pointer to I::Vtbl.

pub unsafe fn from_raw_unchecked(ptr: *mut I) -> ComPtr<I>

Creates a ComPtr from a raw interface pointer.

When the resulting ComPtr is dropped, the reference count of the object it points to will be decremented. Thus, using this method can be thought of as “taking ownership” of a pointer to a COM object.

Safety

ptr must be a valid pointer to a value of type I, and if *ptr is reinterpreted as *const I::Vtbl (see the safety documentation for Interface), it must in turn be a valid pointer to I::Vtbl.

pub fn into_raw(self) -> *mut I

Consumes the ComPtr, returning the wrapped interface pointer.

Since this method consumes the ComPtr, it prevents the ComPtr from decrementing the reference count of the object it points to. Thus, using this method can be thought of as “relinquishing ownership” of a pointer to a COM object.

pub fn as_com_ref<'a>(&'a self) -> ComRef<'a, I>

Returns a ComRef pointing to the same object as this ComPtr. Can be thought of as a borrow.

Does not perform any reference counting operations.

pub fn upcast<J>(self) -> ComPtr<J>

where J: Interface, I: Inherits<J>,

Does not perform any reference counting operations.

pub fn cast<J>(&self) -> Option<ComPtr<J>>

where J: Interface,

Attempts to cast from one interface to another, returning another ComPtr if successful.

If the cast is successful, increments the reference count of the object that the ComPtr points to.

Trait Implementations

impl<I> Clone for ComPtr<I>

where I: Interface,

fn clone(&self) -> ComPtr<I>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<I> Drop for ComPtr<I>

where I: Interface,

fn drop(&mut self)

Executes the destructor for this type.

impl<I> SmartPtr for ComPtr<I>

where I: Interface,

type Target = I

The interface type pointed to by this smart pointer.

fn ptr(&self) -> *mut I

Gets the raw pointer held by this smart pointer.

impl<I> Send for ComPtr<I>

where I: Interface + Sync + Send,

impl<I> Sync for ComPtr<I>

where I: Interface + Sync + Send,