Struct ComPtr

pub struct ComPtr<T: ComInterface> { /* private fields */ }

Wrapper type for COM interface pointers.

Usage

Passing COM pointers to/from FFI methods

ComPtr<T> has the following methods for accessing the underlying pointer:

• as_ptr returns the raw pointer *const T
• as_mut_ptr returns a mutable reference to the raw pointer &mut *mut T

The AsComPtr trait defines which pointer types can be returned by these methods. These methods should be used carefully to ensure the returned pointers do not outlive the ComPtr object.

extern crate com_rs;
use com_rs::*;

fn create_iunknown_object(p: *mut *mut IUnknown) { }
fn use_iunknown_object(p: *const IUnknown) { }

fn main() {
    let mut unknown: ComPtr<IUnknown> = ComPtr::new();
    create_iunknown_object(unknown.as_mut_ptr());
    use_iunknown_object(unknown.as_ptr());
}

Reference Counting

ComPtr implements the Clone and Drop traits, which call the IUnknown::add_ref and IUnknown::release methods respectively to handle the internal reference counting.

Accessing COM interface methods

ComPtr<T> coerces into T using the Deref trait, allowing interface methods to be called directly. However, dereferencing a ComPtr containing a null pointer in this way results in a panic. All method calls should be guarded with is_null checks to prevent this.

let mut ptr: ComPtr<IUnknown> = ComPtr::new();
create_iunknown_object(ptr.as_mut_ptr());
if !ptr.is_null() {
    // This is just for demonstration, don't call these directly
    unsafe { ptr.add_ref() };
    unsafe { ptr.release() };
}

Conversion using From

ComPtr<T> also implements the From trait for conversion between different COM interfaces. This is a wrapper around the IUnknown::query_interface method which automatically uses the IID of the target type.

let mut unknown: ComPtr<IUnknown> = ComPtr::new();
create_iunknown_object(unknown.as_mut_ptr());
let other: ComPtr<IFoobar> = ComPtr::from(&unknown);

This will try to query the IFoobar interface on the unknown object. If the interface is unavailable (or unknown is null), the returned object will be null.

Implementations

impl<T: ComInterface> ComPtr<T>

pub fn new() -> ComPtr<T>

Constructs a new ComPtr<T>.

pub fn as_ptr<U>(&self) -> *const U

where T: AsComPtr<U>,

Returns the raw pointer as type U. Depends on the AsComPtr trait.

pub fn as_mut_ptr<U>(&mut self) -> &mut *mut U

where T: AsComPtr<U>,

Returns a mutable reference to the raw pointer. Depends on the ‘AsComPtr’ trait.

pub fn is_null(&self) -> bool

Returns true if the contained interface pointer is null. This should always be checked before calling any methods on the contained interface.

pub fn iid(&self) -> IID

Return the IID associated with type T.

Trait Implementations

impl<T: ComInterface> Clone for ComPtr<T>

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

Clones the ComPtr<T>. Increments the internal reference counter by calling IUnknown::add_ref on the contained COM object (if the pointer is non-null).

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

Performs copy-assignment from source.

impl<T: Debug + ComInterface> Debug for ComPtr<T>

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

Formats the value using the given formatter.

impl<T: ComInterface> Deref for ComPtr<T>

fn deref<'a>(&'a self) -> &'a T

Dereference into contained interface T to call methods directly.

Panics

If the contained pointer is null, any dereference will result in a panic. Use the is_null method before dereferencing.

type Target = T

The resulting type after dereferencing.

impl<T: ComInterface> Drop for ComPtr<T>

fn drop(&mut self)

Drops the ComPtr<T>. Decrements the internal reference counter by calling IUnknown::release on the contained COM object (if the pointer is non-null).

impl<'a, T, U> From<&'a ComPtr<T>> for ComPtr<U>

where T: ComInterface, U: ComInterface + AsComPtr<c_void>,

fn from(other: &'a ComPtr<T>) -> ComPtr<U>

Create a ComPtr of a different interface type U. Calls IUnknown::query_interface and returns a new ComPtr<U> object. If the requested interface is unavailable, the returned ComPtr<U> will contain a null pointer.