Struct com_rs::ComPtr

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

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.

Methods

impl<T: ComInterface> ComPtr<T>

fn new() -> ComPtr<T>

Constructs a new ComPtr<T>.

fn as_ptr<U>(&self) -> *const U where
    T: AsComPtr<U>, 

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

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.

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.

fn iid(&self) -> IID

Return the IID associated with type T.

Trait Implementations

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

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

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.

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

type Target = T

The resulting type after dereferencing

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.

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: 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).