TSDuck Version 3.16-1064 (TSDuck - The MPEG Transport Stream Toolkit)
ts::ComPtr< COMCLASS > Class Template Reference

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

Public Member Functions

 ComPtr (COMCLASS *p=0, ::HRESULT hr=S_OK)
 Default constructor. More...
 
 ComPtr (const ComPtr< COMCLASS > &p)
 Copy constructor. More...
 
 ComPtr (const ::IID &class_id, const ::IID &interface_id, Report &report=CERR)
 Constructor using CoCreateInstance(). More...
 
 ComPtr (::IUnknown *obj, const IID &interface_id, Report &report=CERR)
 Constructor using IUnknown::QueryInterface(). More...
 
 ~ComPtr ()
 Destructor. More...
 
template<class COMSUBCLASS >
ComPtr< COMCLASS > & assign (const ComPtr< COMSUBCLASS > &p)
 Assignment from a ComPtr to a subclass. More...
 
ComPtr< COMCLASS > & bindToObject (::IMoniker *moniker, const IID &interface_id, Report &report=CERR)
 Assign using IMoniker::BindToObject If the COM interface is successfully retrieved, it becomes managed and its reference count is unchanged (== 1). More...
 
UString className () const
 Get the "class name" (formatted GUID) of this object. More...
 
ComPtr< COMCLASS > & createInstance (const ::IID &class_id, const ::IID &interface_id, Report &report=CERR)
 Assign using CoCreateInstance(). More...
 
COMCLASS ** creator ()
 Release previous pointer, return a receiver for new pointer. More...
 
bool expose (const ::IID &iid) const
 Check if the object exposes an interface. More...
 
bool isNull () const
 Check if null pointer. More...
 
COMCLASS & operator* () const
 Dereference operator. More...
 
COMCLASS * operator-> () const
 Dereference operator. More...
 
ComPtr< COMCLASS > & operator= (const ComPtr< COMCLASS > &p)
 Assignment operator. More...
 
ComPtr< COMCLASS > & operator= (COMCLASS *p)
 Assignment operator from a COM object pointer. More...
 
COMCLASS * pointer () const
 To access a COM object pointer, without releasing it. More...
 
ComPtr< COMCLASS > & queryInterface (::IUnknown *obj, const IID &interface_id, Report &report=CERR)
 Assign using IUnknown::QueryInterface If the COM interface is successfully retrieved, it becomes managed and its reference count is unchanged (== 1). More...
 
int refCount () const
 Get the reference count to the object. More...
 
void release ()
 Release the COM object, its reference count is decremented. More...
 

Detailed Description

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

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

Template Parameters
COMCLASSA COM interface or object class.

If TS_COMPTR_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/4]

template<class COMCLASS>
ts::ComPtr< COMCLASS >::ComPtr ( COMCLASS *  p = 0,
::HRESULT  hr = S_OK 
)

Default constructor.

Parameters
[in]pAddress 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]hrAn HRESULT value, typically the returned status of the system call which created p.

◆ ComPtr() [2/4]

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

Copy constructor.

The reference count of the COM object is incremented.

Parameters
[in]pAnother ComPtr instance.

◆ ComPtr() [3/4]

template<class COMCLASS>
ts::ComPtr< COMCLASS >::ComPtr ( const ::IID &  class_id,
const ::IID &  interface_id,
Report report = CERR 
)

Constructor using CoCreateInstance().

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

Parameters
[in]class_idClass id of the COM object to create.
[in]interface_idId of the interface we request in the object.
[in]reportWhere to report errors.

Example:

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

◆ ComPtr() [4/4]

template<class COMCLASS>
ts::ComPtr< COMCLASS >::ComPtr ( ::IUnknown *  obj,
const IID &  interface_id,
Report report = CERR 
)

Constructor using IUnknown::QueryInterface().

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

Parameters
[in]objA COM object.
[in]interface_idId of the interface we request in the object.
[in]reportWhere to report errors.
Returns
A reference to this object.

◆ ~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 >
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
COMSUBCLASSA COM interface or object class, a subclass of COMCLASS.
Parameters
[in]pA ComPtr to a COMSUBCLASS object.
Returns
A reference to this object.

◆ operator=() [1/2]

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]pA ComPtr to a COM object.
Returns
A reference to this object.

◆ operator=() [2/2]

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]pAddress 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 = CERR 
)

Assign using CoCreateInstance().

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

Parameters
[in]class_idClass id of the COM object to create.
[in]interface_idId of the interface we request in the object.
[in]reportWhere 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 = CERR 
)

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

Parameters
[in]objA COM object.
[in]interface_idId of the interface we request in the object.
[in]reportWhere 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 = CERR 
)

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

Parameters
[in]monikerThe moniker to use.
[in]interface_idId of the interface we request in the object.
[in]reportWhere 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]iidId 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: