Managed pointers for COM objects, auto-released (Windows-specific). More...

#include <tsComPtr.h>

Public Member Functions
	ComPtr (::IUnknown *obj, const IID &interface_id, Report &report=(ts::CerrReport::Instance()))
	Constructor using IUnknown::QueryInterface().

	ComPtr (COMCLASS *p=nullptr, ::HRESULT hr=S_OK)
	Default constructor.

	ComPtr (ComPtr< COMCLASS > &&p)
	Move constructor.

	ComPtr (const ::IID &class_id, const ::IID &interface_id, Report &report=(ts::CerrReport::Instance()))
	Constructor using CoCreateInstance().

	ComPtr (const ComPtr< COMCLASS > &p)
	Copy constructor.

	~ComPtr ()
	Destructor.

template<class COMSUBCLASS > requires std::derived_from<COMSUBCLASS, COMCLASS>
ComPtr< COMCLASS > &	assign (const ComPtr< COMSUBCLASS > &p)
	Assignment from a ComPtr to a subclass.

ComPtr< COMCLASS > &	bindToObject (::IMoniker *moniker, const IID &interface_id, Report &report=(ts::CerrReport::Instance()))
	Assign using IMoniker::BindToObject If the COM interface is successfully retrieved, it becomes managed and its reference count is unchanged (== 1).

UString	className () const
	Get the "class name" (formatted GUID) of this object.

ComPtr< COMCLASS > &	createInstance (const ::IID &class_id, const ::IID &interface_id, Report &report=(ts::CerrReport::Instance()))
	Assign using CoCreateInstance().

COMCLASS **	creator ()
	Release previous pointer, return a receiver for new pointer.

bool	expose (const ::IID &iid) const
	Check if the object exposes an interface.

bool	isNull () const
	Check if null pointer.

COMCLASS &	operator* () const
	Dereference operator.

COMCLASS *	operator-> () const
	Dereference operator.

ComPtr< COMCLASS > &	operator= (COMCLASS *p)
	Assignment operator from a COM object pointer.

ComPtr< COMCLASS > &	operator= (ComPtr< COMCLASS > &&p)
	Move assignment operator.

ComPtr< COMCLASS > &	operator= (const ComPtr< COMCLASS > &p)
	Assignment operator.

COMCLASS *	pointer () const
	To access a COM object pointer, without releasing it.

ComPtr< COMCLASS > &	queryInterface (::IUnknown *obj, const IID &interface_id, Report &report=(ts::CerrReport::Instance()))
	Assign using IUnknown::QueryInterface If the COM interface is successfully retrieved, it becomes managed and its reference count is unchanged (== 1).

int	refCount () const
	Get the reference count to the object.

void	release ()
	Release the COM object, its reference count is decremented.

Detailed Description

template<class COMCLASS>
class ts::ComPtr< COMCLASS >

Managed pointers for COM objects, auto-released (Windows-specific).

Template Parameters

COMCLASS A COM interface or object class.

If TS_COM_INSTRUMENTATION is defined and the application is compiled in debug mode, the ComPtr class produces abundant trace messages on the standard error.

Trace line format:

[COMPTR] comaddr=refcount (@ptraddr): message

With:

comaddr : Address of the COM object.
refcount : Current reference count on the COM object after the operation.
ptraddr : Address of the ComPtr object.

Constructor & Destructor Documentation

◆ ComPtr() [1/5]

template<class COMCLASS >

ts::ComPtr< COMCLASS >::ComPtr	(	COMCLASS *	p = `nullptr`,
		::HRESULT	hr = `S_OK`
	)

Default constructor.

Parameters

[in]	p	Address of a COM object. If p is not null and hr is success, the COM object becomes managed by ComPtr. Its reference count is unchanged.
[in]	hr	An `HRESULT` value, typically the returned status of the system call which created p.

◆ ComPtr() [2/5]

template<class COMCLASS >

ts::ComPtr< COMCLASS >::ComPtr ( const ComPtr< COMCLASS > & p )

Copy constructor.

The reference count of the COM object is incremented.

Parameters

[in] p Another ComPtr instance.

◆ ComPtr() [3/5]

template<class COMCLASS >

ts::ComPtr< COMCLASS >::ComPtr ( ComPtr< COMCLASS > && p )

Move constructor.

The reference count of the COM object is not incremented.

Parameters

[in,out] p Another ComPtr instance. Cleared on output.

◆ ComPtr() [4/5]

template<class COMCLASS >

ts::ComPtr< COMCLASS >::ComPtr	(	const ::IID &	class_id,
		const ::IID &	interface_id,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Constructor using CoCreateInstance().

If the COM object is successfully created, it becomes managed and its reference count is unchanged (== 1).

Parameters

[in]	class_id	Class id of the COM object to create.
[in]	interface_id	Id of the interface we request in the object.
[in]	report	Where to report errors.

Example:

ComPtr<::ICreateDevEnum> enum_devices(::CLSID_SystemDeviceEnum, ::IID_ICreateDevEnum, report);

ts::ComPtr

Managed pointers for COM objects, auto-released (Windows-specific).

Definition tsComPtr.h:59

◆ ComPtr() [5/5]

template<class COMCLASS >

ts::ComPtr< COMCLASS >::ComPtr	(	::IUnknown *	obj,
		const IID &	interface_id,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Constructor using IUnknown::QueryInterface().

If the COM interface is successfully retrieved, it becomes managed and its reference count is unchanged (== 1).

Parameters

[in]	obj	A COM object.
[in]	interface_id	Id of the interface we request in the object.
[in]	report	Where to report errors.

◆ ~ComPtr()

template<class COMCLASS >

ts::ComPtr< COMCLASS >::~ComPtr ( )

Destructor.

The COM object is released (its reference count is decremented).

Member Function Documentation

◆ isNull()

template<class COMCLASS >

bool ts::ComPtr< COMCLASS >::isNull ( ) const

Check if null pointer.

Returns: True if this is a null pointer (no object).

◆ pointer()

template<class COMCLASS >

COMCLASS * ts::ComPtr< COMCLASS >::pointer ( ) const

To access a COM object pointer, without releasing it.

Returns: A pointer to the COM object.

◆ operator*()

template<class COMCLASS >

COMCLASS & ts::ComPtr< COMCLASS >::operator* ( ) const

Dereference operator.

To access a COM object.

Returns: A reference to the COM object.

◆ operator->()

template<class COMCLASS >

COMCLASS * ts::ComPtr< COMCLASS >::operator-> ( ) const

Dereference operator.

To access members of COM objects.

Returns: A pointer to the COM object.

◆ creator()

template<class COMCLASS >

COMCLASS ** ts::ComPtr< COMCLASS >::creator ( )

Release previous pointer, return a receiver for new pointer.

Typically used in CoCreateInstance() and COM methods returning a new COM interface.

Returns: The address of the internal COM object pointer.

◆ release()

template<class COMCLASS >

void ts::ComPtr< COMCLASS >::release ( )

Release the COM object, its reference count is decremented.

The pointer becomes null.

◆ refCount()

template<class COMCLASS >

int ts::ComPtr< COMCLASS >::refCount ( ) const

Get the reference count to the object.

WARNING: This should be used for test or debug purpose only. Since there is no direct way to get the reference count of a COM object, we perform an AddRef / Release operation. The reference count is returned by Release().

Returns: The reference count for the object or zero if this is a null pointer.

◆ assign()

template<class COMCLASS >

template<class COMSUBCLASS >
requires std::derived_from<COMSUBCLASS, COMCLASS>

ComPtr< COMCLASS > & ts::ComPtr< COMCLASS >::assign ( const ComPtr< COMSUBCLASS > & p )

Assignment from a ComPtr to a subclass.

The reference count of the COM object is incremented.

Template Parameters

COMSUBCLASS A COM interface or object class, a subclass of COMCLASS.

Parameters

[in] p A ComPtr to a COMSUBCLASS object.

Returns: A reference to this object.

◆ operator=() [1/3]

template<class COMCLASS >

ComPtr< COMCLASS > & ts::ComPtr< COMCLASS >::operator= ( const ComPtr< COMCLASS > & p )

Assignment operator.

The reference count of the COM object is incremented.

Parameters

[in] p A ComPtr to a COM object.

Returns: A reference to this object.

◆ operator=() [2/3]

template<class COMCLASS >

ComPtr< COMCLASS > & ts::ComPtr< COMCLASS >::operator= ( ComPtr< COMCLASS > && p )

Move assignment operator.

The reference count of the COM object is not incremented.

Parameters

[in,out] p A ComPtr to a COM object. Cleared on return.

Returns: A reference to this object.

◆ operator=() [3/3]

template<class COMCLASS >

ComPtr< COMCLASS > & ts::ComPtr< COMCLASS >::operator= ( COMCLASS * p )

Assignment operator from a COM object pointer.

The COM object becomes managed. Its reference count is unchanged.

Parameters

[in] p Address of a COM object. Can be null.

Returns: A reference to this object.

◆ createInstance()

template<class COMCLASS >

ComPtr< COMCLASS > & ts::ComPtr< COMCLASS >::createInstance	(	const ::IID &	class_id,
		const ::IID &	interface_id,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Assign using CoCreateInstance().

If the COM object is successfully created, it becomes managed and its reference count is unchanged (== 1).

Parameters

[in]	class_id	Class id of the COM object to create.
[in]	interface_id	Id of the interface we request in the object.
[in]	report	Where to report errors.

Returns: A reference to this object.

◆ queryInterface()

template<class COMCLASS >

ComPtr< COMCLASS > & ts::ComPtr< COMCLASS >::queryInterface	(	::IUnknown *	obj,
		const IID &	interface_id,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Assign using IUnknown::QueryInterface If the COM interface is successfully retrieved, it becomes managed and its reference count is unchanged (== 1).

Parameters

[in]	obj	A COM object.
[in]	interface_id	Id of the interface we request in the object.
[in]	report	Where to report errors.

Returns: A reference to this object.

◆ bindToObject()

template<class COMCLASS >

ComPtr< COMCLASS > & ts::ComPtr< COMCLASS >::bindToObject	(	::IMoniker *	moniker,
		const IID &	interface_id,
		Report &	report = `(ts::CerrReport::Instance())`
	)

Assign using IMoniker::BindToObject If the COM interface is successfully retrieved, it becomes managed and its reference count is unchanged (== 1).

Parameters

[in]	moniker	The moniker to use.
[in]	interface_id	Id of the interface we request in the object.
[in]	report	Where to report errors.

Returns: A reference to this object.

◆ expose()

template<class COMCLASS >

bool ts::ComPtr< COMCLASS >::expose ( const ::IID & iid ) const

Check if the object exposes an interface.

Parameters

[in] iid Id of the interface we request in the object.

Returns: True if the object exposes the iid interface.

◆ className()

template<class COMCLASS >

UString ts::ComPtr< COMCLASS >::className ( ) const

Get the "class name" (formatted GUID) of this object.

Warning: Very slow, eat CPU time, use with care.

Returns: A formatted GUID or an empty string on error or if the object does not expose IPersist interface.

The documentation for this class was generated from the following file:

tsComPtr.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ComPtr() [1/5]

◆ ComPtr() [2/5]

◆ ComPtr() [3/5]

◆ ComPtr() [4/5]

◆ ComPtr() [5/5]

◆ ~ComPtr()

Member Function Documentation

◆ isNull()

◆ pointer()

◆ operator*()

◆ operator->()

◆ creator()

◆ release()

◆ refCount()

◆ assign()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ createInstance()

◆ queryInterface()

◆ bindToObject()

◆ expose()

◆ className()