description | title | ms.date | f1_keywords | helpviewer_keywords | ms.assetid | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Learn more about: CComPtrBase Class |
CComPtrBase Class |
11/04/2016 |
|
|
6dbe9543-dee8-4a97-b02f-dd3a25f4a1a0 |
This class provides a basis for smart pointer classes using COM-based memory routines.
template <class T>
class CComPtrBase
T
The object type to be referenced by the smart pointer.
Name | Description |
---|---|
CComPtrBase::~CComPtrBase |
The destructor. |
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. |
Name | Description |
---|---|
CComPtrBase::operator T* |
The cast operator. |
CComPtrBase::operator ! |
The NOT operator. |
CComPtrBase::operator & |
The address-of & operator. |
CComPtrBase::operator * |
The pointer-to * operator. |
CComPtrBase::operator < |
The less-than operator. |
CComPtrBase::operator == |
The equality operator. |
CComPtrBase::operator -> |
The pointer-to-members operator. |
Name | Description |
---|---|
CComPtrBase::p |
The pointer data member variable. |
This class provides the basis for other smart pointers that 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
.
Header: atlcomcli.h
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();
pUnk
A pointer to the client's IUnknown
.
iid
The GUID of the connection point. Typically, this GUID is the same as the outgoing interface managed by the connection point.
pdw
A pointer to the cookie that uniquely identifies the connection.
Returns S_OK
on success, or an error HRESULT
on failure.
For more information, see AtlAdvise
.
Call this method to take ownership of an existing pointer.
void Attach(T* p2) throw();
p2
The CComPtrBase
object will take ownership of this pointer.
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 deletes the pointer and any allocated data if the reference count on the object goes to 0.
The destructor.
~CComPtrBase() throw();
Releases the interface pointed to by CComPtrBase
.
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();
szProgID
Pointer to a ProgID, used to recover the CLSID.
pUnkOuter
If NULL, indicates that the object isn't 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.
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.
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
isn't equal to NULL.
Call this method to copy the CComPtrBase
pointer to another pointer variable.
HRESULT CopyTo(T** ppT) throw();
ppT
Address of the variable to receive the CComPtrBase
pointer.
Returns S_OK
on success, E_POINTER
on failure.
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.
Call this method to release ownership of a pointer.
T* Detach() throw();
Returns a copy of the pointer.
Releases ownership of a pointer, sets the CComPtrBase::p
data member variable to NULL, and returns a copy of the pointer.
Call this method to check if the specified IUnknown
points to the same object associated with the CComPtrBase
object.
bool IsEqualObject(IUnknown* pOther) throw();
pOther
The IUnknown *
to compare.
Returns true if the objects are identical, false otherwise.
The NOT operator.
bool operator!() const throw();
Returns true if the CComHeapPtr
pointer is equal to NULL, false otherwise.
The address-of &
operator.
T** operator&() throw();
Returns the address of the object pointed to by the CComPtrBase
object.
The pointer-to *
operator.
T& operator*() const throw();
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
isn't equal to NULL.
The equality operator.
bool operator== (T* pT) const throw();
pT
A pointer to an object.
Returns true if CComPtrBase
and pT
point to the same object, false otherwise.
The pointer-to-member operator.
_NoAddRefReleaseOnCComPtr<T>* operator->() const throw();
Returns the value of the CComPtrBase::p
data member variable.
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.
The less-than operator.
bool operator<(T* pT) const throw();
pT
A pointer to an object.
Returns true if the pointer managed by current object is less than the pointer to which it's being compared.
The cast operator.
operator T*() const throw();
Returns a pointer to the object data type defined in the class template.
The pointer data member variable.
T* p;
This member variable holds the pointer information.
Call this method to return a pointer to a specified interface.
template <class Q> HRESULT QueryInterface(Q
** pp) const throw();
Q
The object type whose interface pointer is required.
pp
Address of output variable that receives the requested interface pointer.
Returns S_OK
on success, or E_NOINTERFACE
on failure.
This method calls IUnknown::QueryInterface
.
In debug builds, an assertion error will occur if pp
isn't equal to NULL.
Call this method to release the interface.
void Release() throw();
The interface is released, and CComPtrBase::p
is set to NULL.
Call this method to set the site of the CComPtrBase
object to the IUnknown
of the parent object.
HRESULT SetSite(IUnknown* punkParent) throw();
punkParent
A pointer to the IUnknown
interface of the parent.
Returns S_OK
on success, or an error HRESULT
on failure.
This method calls AtlSetChildSite
.