[−][src]Struct com_rs::ComPtr
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>
[src]
pub fn new() -> ComPtr<T>
[src]
Constructs a new ComPtr<T>
.
pub fn as_ptr<U>(&self) -> *const U where
T: AsComPtr<U>,
[src]
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>,
[src]
T: AsComPtr<U>,
Returns a mutable reference to the raw pointer. Depends on the 'AsComPtr' trait.
pub fn is_null(&self) -> bool
[src]
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
[src]
Return the IID associated with type T
.
Trait Implementations
impl<T: ComInterface> Drop for ComPtr<T>
[src]
fn drop(&mut self)
[src]
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>,
[src]
T: ComInterface,
U: ComInterface + AsComPtr<c_void>,
fn from(other: &'a ComPtr<T>) -> ComPtr<U>
[src]
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> Clone for ComPtr<T>
[src]
fn clone(&self) -> ComPtr<T>
[src]
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)
1.0.0[src]
impl<T: Debug + ComInterface> Debug for ComPtr<T>
[src]
impl<T: ComInterface> Deref for ComPtr<T>
[src]
Auto Trait Implementations
impl<T> !Send for ComPtr<T>
impl<T> !Sync for ComPtr<T>
impl<T> Unpin for ComPtr<T>
impl<T> UnwindSafe for ComPtr<T> where
T: RefUnwindSafe,
T: RefUnwindSafe,
impl<T> RefUnwindSafe for ComPtr<T> where
T: RefUnwindSafe,
T: RefUnwindSafe,
Blanket Implementations
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> From<T> for T
[src]
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
fn to_owned(&self) -> T
[src]
fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,