Struct intercom::ComBoxData

#[repr(C)]
pub struct ComBoxData<T: ComClass> { /* private fields */ }

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 ComBoxData 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.

Implementations

impl<T: ComClass> ComBoxData<T>

pub fn new(value: T) -> *mut ComBoxData<T>

Creates a new ComBoxData and returns a pointer to it.

The box is initialized with a reference count of zero. In most cases the ComBoxData 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: &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.

Safety

The out pointer must be valid for writing the interface pointer to.

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

Increments the reference count.

Returns the reference count after the increment.

Safety

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.

Safety

The pointer must be valid and not previously released. After the call completes, the struct may have been deallocated and the pointer should be considered dangling.

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

Converts a RawComPtr to a ComBoxData reference.

Safety

The method is unsafe in two different ways:

• There is no way for the method to ensure the RawComPtr points to a valid ComBoxData 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 ComBoxData reference. If the ComBoxData is free’d by calling release on the pointer, the ComBoxData 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 ComBoxData is released.

pub fn vtable(ct: &ComBox<T>) -> &T::VTableList

Returns a reference to the virtual table on the ComBoxData.

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

Gets the ComBoxData holding the value.

Safety

This is unsafe for two reasons:

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

• The method returns a mutable reference to the ComBoxData 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 ComBoxData reference.

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

Gets the ComBoxData holding the value.

Safety

This is unsafe for two reasons:

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

• The method returns a mutable reference to the ComBoxData 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 ComBoxData reference.

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

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

Safety

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 ComBoxData containing these pointers.

Trait Implementations

impl<T: ComClass> AsMut<ComBoxData<T>> for ComBox<T>

fn as_mut(&mut self) -> &mut ComBoxData<T>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T: ComClass> AsRef<ComBoxData<T>> for ComBox<T>

fn as_ref(&self) -> &ComBoxData<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Deref for ComBoxData<T> where
    T: ComClass, 

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T> DerefMut for ComBoxData<T> where
    T: ComClass, 

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

Mutably dereferences the value.