#include <tsComPtr.h>

Public Member Functions
	ComPtr (::IUnknown *obj, const IID &interface_id, Report &report=(ts::CerrReport::Instance()))
	ComPtr (COMCLASS *p=nullptr, ::HRESULT hr=S_OK)
	ComPtr (ComPtr< COMCLASS > &&p)
	ComPtr (const ::IID &class_id, const ::IID &interface_id, Report &report=(ts::CerrReport::Instance()))
	ComPtr (const ComPtr< COMCLASS > &p)
	~ComPtr ()
template<class COMSUBCLASS> requires std::derived_from<COMSUBCLASS, COMCLASS>
ComPtr< COMCLASS > &	assign (const ComPtr< COMSUBCLASS > &p)
ComPtr< COMCLASS > &	bindToObject (::IMoniker *moniker, const IID &interface_id, Report &report=(ts::CerrReport::Instance()))
UString	className () const
ComPtr< COMCLASS > &	createInstance (const ::IID &class_id, const ::IID &interface_id, Report &report=(ts::CerrReport::Instance()))
COMCLASS **	creator ()
bool	expose (const ::IID &iid) const
bool	isNull () const
COMCLASS &	operator* () const
COMCLASS *	operator-> () const
ComPtr< COMCLASS > &	operator= (COMCLASS *p)
ComPtr< COMCLASS > &	operator= (ComPtr< COMCLASS > &&p)
ComPtr< COMCLASS > &	operator= (const ComPtr< COMCLASS > &p)
COMCLASS *	pointer () const
ComPtr< COMCLASS > &	queryInterface (::IUnknown *obj, const IID &interface_id, Report &report=(ts::CerrReport::Instance()))
int	refCount () const
void	release ()

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::ComPtr

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

◆ 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()