ArcGIS Engine Developer Guide

C++ APPLICATION PROGRAMMING INTERFACE
If you have used smart pointers before, you
might have seen differences in the implementation
of the equality (“==”) operator for smart
pointer comparisons. The COM specification
states object identity is performed by comparing
the pointer values of IUnknown. The smart
pointers will perform necessary QI and comparison
when using the “==” operator.
// results in an AddRef (if pointer is not 0).
IBarPtr ipBar(m_ipBar);
// Detach will clear the local smart pointer and the
// interface is written into the output parameter.
*pVal = ipBar.Detach();
// This can be combined into one line:
// *pVal = IBarPtr(m_ipBar).Detach();
CComVariant(VARIANT_TRUE) will create a
short integer variant (type VT_I2) and not a
Boolean variant (type VT_BOOL) as expected.
You can use CComVariant(true) to create a
Boolean variant.
return S_OK;
}
The above pattern has the same result as the following code. Note that a conditional
test for a 0 pointer is required before AddRef can be called; calling
AddRef (or any method) on a 0 pointer will result in an access violation exception
and typically crash the application:
HRESULT CFoo::get_Bar(IBar **pVal)
{
if (pVal==0) return E_POINTER;
// Copy the interface pointer (no AddRef) into the output parameter.
*pVal = m_ipBar;
// Make sure the interface pointer is nonzero before calling AddRef.
if (*pVal)
*pVal->AddRef();
CComVariant myVar(ipSmartPointer) will result
in a variant type of Boolean (VT_BOOL) and
not a variant with an object reference
(VT_UNKNOWN) as expected. It is better to
pass unambiguous types to constructors—that is,
types that are not smart types with overloaded
cast operators.
// Perform QI of IUnknown.
IUnknownPtr ipUnk = ipSmartPointer;
// Ensure we use IUnknown* constructor of
CComVariant.
CComVariant myVar2(ipUnk.GetInterfacePtr());
return S_OK;
}
When using a smart pointer to receive an object from an [out] parameter on a
method, use the smart pointer “&” de-reference operator. This will cause the
previous interface pointer in the smart pointer to be released. The smart pointer is
then populated with the new [out] value. The implementation of the method will
have already incremented the object reference count. This will be released when
the smart pointer goes out of scope:
{
IFooPtr ipFoo1, ipFoo2;
ipFoo1.CreateInstance(CLSID_Foo);
ipFoo2.CreateInstance(CLSID_Foo);
// Initialize ipBar Smart pointer from Foo1.
IBarPtr ipBar;
ipFoo1->get_Bar(&ipBar);
// The "&" de-reference will call Release on ipBar.
// ipBar is then repopulated with a new instance of IBar.
ipFoo2->get_Bar(&ipBar);
}
// ipBar goes out of scope, and the smart pointer destructor calls Release.
200 • ArcGIS Engine Developer Guide