Struct intercom::ComBox

#[repr(C)]
pub struct ComBox<T: CoClass> { /* fields omitted */ }

Type factory for the concrete COM coclass types.

Includes the virtual tables required for COM method invocations, reference count required for IUnknown implementation and the custom value struct required for any user defined interfaces.

While this struct is available for manual handling of raw COM interface pointers, it's worth realizing that it's use is inherently unsafe. Most of the methods implemented for the type come with conditions that Rust isn't able to enforce.

The methods that handle RawComPtr types must only be invoked with correct pointer values. There's no type checking for the pointers and the ComBox will make serious assumptions on the pointers passed in.

Furthermore the new_ptr constructor and the IUnknown methods add_ref and release must be used correctly together. Failure to do so will result either in memory leaks or access to dangling pointers.

Methods

impl<T: CoClass> ComBox<T>

pub fn new(value: T) -> Box<ComBox<T>>

Creates a new ComBox and returns a pointer to it.

The box is initialized with a reference count of zero. In most cases the ComBox creation is followed by query_interface, which increments the ref_count.

The value should be cleaned by calling 'release'.

pub unsafe fn query_interface(
    this: &mut Self,
    riid: REFIID,
    out: *mut RawComPtr
) -> HRESULT

Acquires a specific interface pointer.

Increments the reference count to include the reference through the returned interface pointer.

The acquired interface must be released explicitly when not needed anymore.

The method isn't technically unsafe in regard to Rust unsafety, but it's marked as unsafe to discourage it's use due to high risks of memory leaks.

pub unsafe fn add_ref(this: &mut Self) -> u32

Increments the reference count.

Returns the reference count after the increment.

The method isn't technically unsafe in regard to Rust unsafety, but it's marked as unsafe to discourage it's use due to high risks of memory leaks.

pub fn get_ref_count(&self) -> u32

Gets the reference count of the object.

pub unsafe fn release(this: *mut Self) -> u32

Decrements the reference count. Destroys the object if the count reaches zero.

Returns the reference count after the release.

pub unsafe fn interface_supports_error_info(
    _this: &mut Self,
    riid: REFIID
) -> HRESULT

Checks whether the given interface identified by the IID supports error info through IErrorInfo.

pub unsafe fn from_ptr<'a>(ptr: RawComPtr) -> &'a mut ComBox<T>

Converts a RawComPtr to a ComBox reference.

The method is unsafe in two different ways:

• There is no way for the method to ensure the RawComPtr points to a valid ComBox instance. It's the caller's responsibility to ensure the method is not called with invalid pointers.

• As the pointers have no lifetime tied to them, the borrow checker is unable to enforce the lifetime of the ComBox reference. If the ComBox is free'd by calling release on the pointer, the ComBox reference will still reference the old, now free'd value. The caller must ensure that the returned reference won't be used in case the ComBox is released.

pub unsafe extern "stdcall" fn query_interface_ptr(
    self_iunk: RawComPtr,
    riid: REFIID,
    out: *mut RawComPtr
) -> HRESULT

Pointer variant of the query_interface function.

pub unsafe extern "stdcall" fn add_ref_ptr(self_iunk: RawComPtr) -> u32

Pointer variant of the add_ref function.

pub unsafe extern "stdcall" fn release_ptr(self_iunk: RawComPtr) -> u32

Pointer variant of the release function.

pub unsafe extern "stdcall" fn interface_supports_error_info_ptr(
    self_iunk: RawComPtr,
    riid: REFIID
) -> HRESULT

Pointer variant of the release function.

pub unsafe fn vtable(this: &Self) -> &T::VTableList

Returns a reference to the virtual on the ComBox.

pub unsafe fn of(value: &T) -> &ComBox<T>

Gets the ComBox holding the value.

This is unsafe for two reasons:

• There is no way for the method to check that the value is actually contained in a ComBox. It is up to the caller to ensure this method is only called with values that exist within a ComBox.

• The method returns a mutable reference to the ComBox containing the value. As demonstrated by the parameter type, the caller already has a mutable reference to the value itself. As a result the caller will end up with two different mutable references to the value - the direct one given as a parameter and an indirect one available through the return value. The caller should not attempt to access the value data through the returned ComBox reference.

pub unsafe fn of_mut(value: &mut T) -> &mut ComBox<T>

Gets the ComBox holding the value.

This is unsafe for two reasons:

• There is no way for the method to check that the value is actually contained in a ComBox. It is up to the caller to ensure this method is only called with values that exist within a ComBox.

• The method returns a mutable reference to the ComBox containing the value. As demonstrated by the parameter type, the caller already has a mutable reference to the value itself. As a result the caller will end up with two different mutable references to the value - the direct one given as a parameter and an indirect one available through the return value. The caller should not attempt to access the value data through the returned ComBox reference.

pub unsafe fn null_vtable() -> &'static T::VTableList

Returns a reference to a null-ComBox vtable pointer list.

The reference itself is invalid and must not be dereferenced.

The reference may be used to further get references to the various VTableList fields to resolve offset values between the various VTable pointers and the actual ComBox containing these pointers.

Trait Implementations

impl<T> Deref for ComBox<T> where
    T: CoClass, 

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T> DerefMut for ComBox<T> where
    T: CoClass, 

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.