COM Pointers
[Utilities]

Collaboration diagram for COM Pointers:

Functions
template<typename T >
boost::enable_if < boost::is_base_of< IUnknown, T > >::type	boost::intrusive_ptr_add_ref (T *p)
	Add reference to COM pointer.
template<typename T >
boost::enable_if < boost::is_base_of< IUnknown, T > >::type	boost::intrusive_ptr_release (T *p)
	Release reference to COM pointer.
template<class Target , class Source >
boost::intrusive_ptr< Target >	tk11::query_interface (Source ps, const IID &iid=__uuidof(Target))
	Query a COM interface from another.

---

Detailed Description

Pointers to COM interfaces should be wrapped into boost::intrusive_ptr. See http://www.boost.org/doc/libs/1_42_0/libs/smart_ptr/intrusive_ptr.html for more information. Intrusive pointers can be passed around like any other pointers, except that the user does not need to care about reference management (calling IUnknown::AddRef and IUnknown::Release).

A plain pointer to a COM interface must be assigned to an intrusive pointer as follows:

 IUnknown* tmp_unknown = ...;
 boost::intrusive_ptr<IUnknown> unknown(tmp_unknown, false);

Afterwards, the plain pointer should no longer be used, because the above code does not call AddRef.

Example: Using IUnknown::QueryInterface:

 IID iid = ...;
 IUnknown* source = ...;
 void* pv = 0;
 source->QueryInterface(iid, &pv);
 IOtherInterface* tmp_other = static_cast<IOtherInterface*>(pv);
 boost::intrusive_ptr<IOtherInterface> other(tmp_other, false);
 // Do not use tmp_other below this point

For convenience, a template helper function query_interface is also provided.

Some headers provide typedefs for certain COM interfaces to save some typing, e.g.

 typedef boost::intrusive_ptr<ID3D11Device> ID3D11Device_ptr;

---

Function Documentation

template<typename T >

boost::enable_if< boost::is_base_of<IUnknown, T> >::type boost::intrusive_ptr_add_ref

(

T *

p

)

[inline]

Add reference to COM pointer.

This function is used by boost::intrusive_ptr to increment the reference count for a pointer. This overload is used for all and only for types derived from IUnknown.

Parameters:

p

Pointer to COM interface

template<typename T >

boost::enable_if< boost::is_base_of<IUnknown, T> >::type boost::intrusive_ptr_release

(

T *

p

)

[inline]

Release reference to COM pointer.

This function is used by boost::intrusive_ptr to decrement the reference count for a pointer. This overload is used for all and only for types derived from IUnknown.

Parameters:

p

Pointer to COM interface

template<class Target , class Source >

boost::intrusive_ptr<Target> tk11::query_interface	(	Source	ps,
		const IID &	iid = __uuidof(Target)
	)			[inline]

Query a COM interface from another.

Type-safe and exception-safe wrapper for IUnknown::QueryInterface.

Usage:

 boost::intrusive_ptr<ISource> i1;
 boost::intrusive_ptr<ITarget> i2(query_interface<ITarget>(i1));

It is possible to explicitly specify the interface UUID, e.g. if the UUID is not known at runtime:

 boost::intrusive_ptr<IUnknown> i1;
 boost::intrusive_ptr<IUnknown> i2(query_interface<IUnknown>(i1, iid));

Parameters:

	ps	Pointer to COM interface of source type
	iid	Interface ID of target interface

Returns:

Pointer to COM interface of destination type