CComPtrBase Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CComPtrBase Class.

This class provides a basis for smart pointer classes using COM-based memory routines.

Syntax

template <class T>  
class CComPtrBase

Parameters

T
The object type to be referenced by the smart pointer.

Members

Public Constructors

Name	Description
CComPtrBase::~CComPtrBase	The destructor.

Public Methods

Name	Description
CComPtrBase::Advise	Call this method to create a connection between the CComPtrBase's connection point and a client's sink.
CComPtrBase::Attach	Call this method to take ownership of an existing pointer.
CComPtrBase::CoCreateInstance	Call this method to create an object of the class associated with a specified Class ID or Program ID.
CComPtrBase::CopyTo	Call this method to copy the CComPtrBase pointer to another pointer variable.
CComPtrBase::Detach	Call this method to release ownership of a pointer.
CComPtrBase::IsEqualObject	Call this method to check if the specified IUnknown points to the same object associated with the CComPtrBase object.
CComPtrBase::QueryInterface	Call this method to return a pointer to a specified interface.
CComPtrBase::Release	Call this method to release the interface.
CComPtrBase::SetSite	Call this method to set the site of the CComPtrBase object to the IUnknown of the parent object.

Public Operators

Name	Description
CComPtrBase::operator T*	The cast operator.
CComPtrBase::operator !	The NOT operator.
CComPtrBase::operator &	The & operator.
CComPtrBase::operator *	The * operator.
CComPtrBase::operator <	The less-than operator.
CComPtrBase::operator ==	The equality operator.
CComPtrBase::operator ->	The pointer-to-members operator.

Public Data Members

Name	Description
CComPtrBase::p	The pointer data member variable.

Remarks

This class provides the basis for other smart pointers which use COM memory management routines, such as CComQIPtr and CComPtr. The derived classes add their own constructors and operators, but rely on the methods provided by CComPtrBase.

Requirements

Header: atlcomcli.h

CComPtrBase::Advise

Call this method to create a connection between the CComPtrBase's connection point and a client's sink.

HRESULT Advise(
    IUnknown* pUnk,
    const IID& iid,
    LPDWORD pdw) throw();

Parameters

pUnk
A pointer to the client's IUnknown.

iid
The GUID of the connection point. Typically, this is the same as the outgoing interface managed by the connection point.

pdw
A pointer to the cookie that uniquely identifies the connection.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

See AtlAdvise for more information.

CComPtrBase::Attach

Call this method to take ownership of an existing pointer.

void Attach(T* p2) throw();

Parameters

p2
The CComPtrBase object will take ownership of this pointer.

Remarks

Attach calls CComPtrBase::Release on the existing CComPtrBase::p member variable and then assigns p2 to CComPtrBase::p. When a CComPtrBase object takes ownership of a pointer, it will automatically call Release on the pointer which will delete the pointer and any allocated data if the reference count on the object goes to 0.

CComPtrBase::~CComPtrBase

The destructor.

~CComPtrBase() throw();

Remarks

Releases the interface pointed to by CComPtrBase.

CComPtrBase::CoCreateInstance

Call this method to create an object of the class associated with a specified Class ID or Program ID.

HRESULT CoCreateInstance(  
    LPCOLESTR szProgID,
    LPUNKNOWN pUnkOuter = NULL,
    DWORD dwClsContext = CLSCTX_ALL) throw();

HRESULT CoCreateInstance(  
    REFCLSID rclsid,
    LPUNKNOWN pUnkOuter = NULL,
    DWORD dwClsContext = CLSCTX_ALL) throw();

Parameters

szProgID
Pointer to a ProgID, used to recover the CLSID.

pUnkOuter
If NULL, indicates that the object is not being created as part of an aggregate. If non- NULL, is a pointer to the aggregate object's IUnknown interface (the controlling IUnknown).

dwClsContext
Context in which the code that manages the newly created object will run.

rclsid
CLSID associated with the data and code that will be used to create the object.

Return Value

Returns S_OK on success, or REGDB_E_CLASSNOTREG, CLASS_E_NOAGGREGATION, CO_E_CLASSSTRING or E_NOINTERFACE on failure. See CoCreateClassInstance and CLSIDFromProgID for a description of these errors.

Remarks

If the first form of the method is called, CLSIDFromProgID is used to recover the CLSID. Both forms then call CoCreateClassInstance.

In debug builds, an assertion error will occur if CComPtrBase::p is not equal to NULL.

CComPtrBase::CopyTo

Call this method to copy the CComPtrBase pointer to another pointer variable.

HRESULT CopyTo(T** ppT) throw();

Parameters

ppT
Address of the variable which will receive the CComPtrBase pointer.

Return Value

Returns S_OK on success, E_POINTER on failure.

Remarks

Copies the CComPtrBase pointer to ppT. The reference count on the CComPtrBase::p member variable is incremented.

An error HRESULT will be returned if ppT is equal to NULL. In debug builds, an assertion error will occur if ppT is equal to NULL.

CComPtrBase::Detach

Call this method to release ownership of a pointer.

T* Detach() throw();

Return Value

Returns a copy of the pointer.

Remarks

Releases ownership of a pointer, sets the CComPtrBase::p data member variable to NULL, and returns a copy of the pointer.

CComPtrBase::IsEqualObject

Call this method to check if the specified IUnknown points to the same object associated with the CComPtrBase object.

bool IsEqualObject(IUnknown* pOther) throw();

Parameters

pOther
The IUnknown * to compare.

Return Value

Returns true if the objects are identical, false otherwise.

CComPtrBase::operator !

The NOT operator.

bool operator!() const throw();

Return Value

Returns true if the CComHeapPtr pointer is equal to NULL, false otherwise.

CComPtrBase::operator &

The & operator.

T** operator&() throw();

Return Value

Returns the address of the object pointed to by the CComPtrBase object.

CComPtrBase::operator *

The * operator.

T& operator*() const throw();

Return Value

Returns the value of CComPtrBase::p; that is, a pointer to the object referenced by the CComPtrBase object.

If debug builds, an assertion error will occur if CComPtrBase::p is not equal to NULL.

CComPtrBase::operator ==

The equality operator.

bool operator== (T* pT) const throw();

Parameters

pT
A pointer to an object.

Return Value

Returns true if CComPtrBase and pT point to the same object, false otherwise.

CComPtrBase::operator ->

The pointer-to-member operator.

_NoAddRefReleaseOnCComPtr<T>* operator->() const throw();

Return Value

Returns the value of the CComPtrBase::p data member variable.

Remarks

Use this operator to call a method in a class pointed to by the CComPtrBase object. In debug builds, an assertion failure will occur if the CComPtrBase data member points to NULL.

CComPtrBase::operator <

The less-than operator.

bool operator<(T* pT) const throw();

Parameters

pT
A pointer to an object.

Return Value

Returns true if the pointer managed by current object is less than the pointer to which it is being compared.

CComPtrBase::operator T*

The cast operator.

operator T*() const throw();

Remarks

Returns a pointer to the object data type defined in the class template.

CComPtrBase::p

The pointer data member variable.

T* p;

Remarks

This member variable holds the pointer information.

CComPtrBase::QueryInterface

Call this method to return a pointer to a specified interface.

template <class Q> HRESULT QueryInterface(Q
** pp) const throw();

Parameters

Q
The object type whose interface pointer is required.

pp
Address of output variable that receives the requested interface pointer.

Return Value

Returns S_OK on success, or E_NOINTERFACE on failure.

Remarks

This method calls IUnknown::QueryInterface.

In debug builds, an assertion error will occur if pp is not equal to NULL.

CComPtrBase::Release

Call this method to release the interface.

void Release() throw();

Remarks

The interface is released, and CComPtrBase::p is set to NULL.

CComPtrBase::SetSite

Call this method to set the site of the CComPtrBase object to the IUnknown of the parent object.

HRESULT SetSite(IUnknown* punkParent) throw();

Parameters

punkParent
A pointer to the IUnknown interface of the parent.

Return Value

Returns S_OK on success, or an error HRESULT on failure.

Remarks

This method calls AtlSetChildSite.

See Also

Class Overview