ComPtr Class

Creates a smart pointer type that represents the interface specified by the template parameter. ComPtr automatically maintains a reference count for the underlying interface pointer and releases the interface when the reference count goes to zero.

Syntax

template <typename T>
class ComPtr;

template<class U>
friend class ComPtr;

Parameters

T
The interface that the ComPtr represents.

U
A class to which the current ComPtr is a friend. (The template that uses this parameter is protected.)

Remarks

ComPtr<> declares a type that represents the underlying interface pointer. Use ComPtr<> to declare a variable and then use the arrow member-access operator (->) to access an interface member function.

For more information about smart pointers, see the "COM Smart Pointers" subsection of the COM Coding Practices article.

Members

Public Typedefs

Name	Description
InterfaceType	A synonym for the type specified by the T template parameter.

Public Constructors

Name	Description
ComPtr::ComPtr	Initializes a new instance of the ComPtr class. Overloads provide default, copy, move, and conversion constructors.
ComPtr::~ComPtr	Deinitializes an instance of ComPtr.

Public Methods

Name	Description
ComPtr::As	Returns a ComPtr object that represents the interface identified by the specified template parameter.
ComPtr::AsIID	Returns a ComPtr object that represents the interface identified by the specified interface ID.
ComPtr::AsWeak	Retrieves a weak reference to the current object.
ComPtr::Attach	Associates this ComPtr with the interface type specified by the current template type parameter.
ComPtr::CopyTo	Copies the current or specified interface associated with this ComPtr to the specified output pointer.
ComPtr::Detach	Disassociates this ComPtr from the interface that it represents.
ComPtr::Get	Retrieves a pointer to the interface that is associated with this ComPtr.
ComPtr::GetAddressOf	Retrieves the address of the ptr_ data member, which contains a pointer to the interface represented by this ComPtr.
ComPtr::ReleaseAndGetAddressOf	Releases the interface associated with this ComPtr and then retrieves the address of the ptr_ data member, which contains a pointer to the interface that was released.
ComPtr::Reset	Releases the interface associated with this ComPtr and returns the new reference count.
ComPtr::Swap	Exchanges the interface managed by the current ComPtr with the interface managed by the specified ComPtr.

Protected Methods

Name	Description
ComPtr::InternalAddRef	Increments the reference count of the interface associated with this ComPtr.
ComPtr::InternalRelease	Performs a COM Release operation on the interface associated with this ComPtr.

Public Operators

Name	Description
ComPtr::operator&	Retrieves the address of the current ComPtr.
ComPtr::operator->	Retrieves a pointer to the type specified by the current template parameter.
ComPtr::operator=	Assigns a value to the current ComPtr.
ComPtr::operator==	Indicates whether two ComPtr objects are equal.
ComPtr::operator!=	Indicates whether two ComPtr objects aren't equal.
ComPtr::operator Microsoft::WRL::Details::BoolType	Indicates whether a ComPtr is managing the object lifetime of an interface.

Protected Data Members

Name	Description
ComPtr::ptr_	Contains a pointer to the interface that is associated with, and managed by this ComPtr.

Inheritance Hierarchy

ComPtr

Requirements

Header: client.h

Namespace: Microsoft::WRL

ComPtr::~ComPtr

Deinitializes an instance of ComPtr.

WRL_NOTHROW ~ComPtr();

ComPtr::As

Returns a ComPtr object that represents the interface identified by the specified template parameter.

template<typename U>
HRESULT As(
   _Out_ ComPtr<U>* p
) const;

template<typename U>
HRESULT As(
   _Out_ Details::ComPtrRef<ComPtr<U>> p
) const;

Parameters

U
The interface to be represented by parameter p.

p
A ComPtr object that represents the interface specified by parameter U. Parameter p must not refer to the current ComPtr object.

Remarks

The first template is the form that you should use in your code. The second template is an internal, helper specialization. It supports C++ language features such as the auto type deduction keyword.

Return Value

S_OK if successful; otherwise, an HRESULT that indicates the error.

ComPtr::AsIID

Returns a ComPtr object that represents the interface identified by the specified interface ID.

WRL_NOTHROW HRESULT AsIID(
   REFIID riid,
   _Out_ ComPtr<IUnknown>* p
) const;

Parameters

riid
An interface ID.

p
If the object has an interface whose ID equals riid, a doubly indirect pointer to the interface specified by the riid parameter. Otherwise, a pointer to IUnknown.

Return Value

S_OK if successful; otherwise, an HRESULT that indicates the error.

ComPtr::AsWeak

Retrieves a weak reference to the current object.

HRESULT AsWeak(
   _Out_ WeakRef* pWeakRef
);

Parameters

pWeakRef
When this operation completes, a pointer to a weak reference object.

Return Value

S_OK if successful; otherwise, an HRESULT that indicates the error.

ComPtr::Attach

Associates this ComPtr with the interface type specified by the current template type parameter.

void Attach(
   _In_opt_ InterfaceType* other
);

Parameters

other
An interface type.

ComPtr::ComPtr

Initializes a new instance of the ComPtr class. Overloads provide default, copy, move, and conversion constructors.

WRL_NOTHROW ComPtr();

WRL_NOTHROW ComPtr(
   decltype(__nullptr)
);

template<class U>
WRL_NOTHROW ComPtr(
   _In_opt_ U *other
);

WRL_NOTHROW ComPtr(
   const ComPtr& other
);

template<class U>
WRL_NOTHROW ComPtr(
   const ComPtr<U> &other,
   typename ENABLE_IF<__is_convertible_to(U*, T*), void *>
);

WRL_NOTHROW ComPtr(
   _Inout_ ComPtr &&other
);

template<class U>
WRL_NOTHROW ComPtr(
   _Inout_ ComPtr<U>&& other, typename ENABLE_IF<__is_convertible_to(U*, T*), void *>
);

Parameters

U
The type of the other parameter.

other
An object of type U.

Return Value

Remarks

The first constructor is the default constructor, which implicitly creates an empty object. The second constructor specifies __nullptr, which explicitly creates an empty object.

The third constructor creates an object from the object specified by a pointer. The ComPtr now owns the pointed-to memory and maintains a reference count to it.

The fourth and fifth constructors are copy constructors. The fifth constructor copies an object if it's convertible to the current type.

The sixth and seventh constructors are move constructors. The seventh constructor moves an object if it's convertible to the current type.

ComPtr::CopyTo

Copies the current or specified interface associated with this ComPtr to the specified pointer.

HRESULT CopyTo(
   _Deref_out_ InterfaceType** ptr
);

HRESULT CopyTo(
   REFIID riid,
   _Deref_out_ void** ptr
) const;

template<typename U>
HRESULT CopyTo(
   _Deref_out_ U** ptr
) const;

Parameters

U
A type name.

ptr
When this operation completes, a pointer to the requested interface.

riid
An interface ID.

Return Value

S_OK if successful; otherwise, an HRESULT that indicates why the implicit QueryInterface operation failed.

Remarks

The first function returns a copy of a pointer to the interface associated with this ComPtr. This function always returns S_OK.

The second function performs a QueryInterface operation on the interface associated with this ComPtr for the interface specified by the riid parameter.

The third function performs a QueryInterface operation on the interface associated with this ComPtr for the underlying interface of the U parameter.

ComPtr::Detach

Disassociates this ComPtr object from the interface that it represents.

T* Detach();

Return Value

A pointer to the interface that was represented by this ComPtr object.

ComPtr::Get

Retrieves a pointer to the interface that is associated with this ComPtr.

T* Get() const;

Return Value

Pointer to the interface that is associated with this ComPtr.

ComPtr::GetAddressOf

Retrieves the address of the ptr_ data member, which contains a pointer to the interface represented by this ComPtr.

T* const* GetAddressOf() const;
T** GetAddressOf();

Return Value

The address of a variable.

ComPtr::InternalAddRef

Increments the reference count of the interface associated with this ComPtr.

void InternalAddRef() const;

Remarks

This method is protected.

ComPtr::InternalRelease

Performs a COM Release operation on the interface associated with this ComPtr.

unsigned long InternalRelease();

Remarks

This method is protected.

ComPtr::operator&

Releases the interface associated with this ComPtr object and then retrieves the address of the ComPtr object.

Details::ComPtrRef<WeakRef> operator&()

const Details::ComPtrRef<const WeakRef> operator&() const

Return Value

A weak reference to the current ComPtr.

Remarks

This method differs from ComPtr::GetAddressOf in that this method releases a reference to the interface pointer. Use ComPtr::GetAddressOf when you require the address of the interface pointer but don't want to release that interface.

ComPtr::operator->

Retrieves a pointer to the type specified by the current template parameter.

WRL_NOTHROW Microsoft::WRL::Details::RemoveIUnknown<InterfaceType>* operator->() const;

Return Value

Pointer to the type specified by the current template type name.

Remarks

This helper function removes unnecessary overhead caused by using the STDMETHOD macro. This function makes IUnknown types private instead of virtual.

ComPtr::operator=

Assigns a value to the current ComPtr.

WRL_NOTHROW ComPtr& operator=(
   decltype(__nullptr)
);
WRL_NOTHROW ComPtr& operator=(
   _In_opt_ T *other
);
template <typename U>
WRL_NOTHROW ComPtr& operator=(
   _In_opt_ U *other
);
WRL_NOTHROW ComPtr& operator=(
   const ComPtr &other
);
template<class U>
WRL_NOTHROW ComPtr& operator=(
   const ComPtr<U>& other
);
WRL_NOTHROW ComPtr& operator=(
   _Inout_ ComPtr &&other
);
template<class U>
WRL_NOTHROW ComPtr& operator=(
   _Inout_ ComPtr<U>&& other
);

Parameters

U
A class.

other
A pointer, reference, or rvalue reference to a type or another ComPtr.

Return Value

A reference to the current ComPtr.

Remarks

The first version of this operator assigns an empty value to the current ComPtr.

In the second version, if the assigning interface pointer isn't the same as the current ComPtr interface pointer, the second interface pointer is assigned to the current ComPtr.

In the third version, the assigning interface pointer is assigned to the current ComPtr.

In the fourth version, if the interface pointer of the assigning value isn't the same as the current ComPtr interface pointer, the second interface pointer is assigned to the current ComPtr.

The fifth version is a copy operator; a reference to a ComPtr is assigned to the current ComPtr.

The sixth version is a copy operator that uses move semantics; an rvalue reference to a ComPtr if any type is static cast and then assigned to the current ComPtr.

The seventh version is a copy operator that uses move semantics; an rvalue reference to a ComPtr of type U is static cast then and assigned to the current ComPtr.

ComPtr::operator==

Indicates whether two ComPtr objects are equal.

bool operator==(
   const ComPtr<T>& a,
   const ComPtr<U>& b
);

bool operator==(
   const ComPtr<T>& a,
   decltype(__nullptr)
);

bool operator==(
   decltype(__nullptr),
   const ComPtr<T>& a
);

Parameters

a
A reference to a ComPtr object.

b
A reference to another ComPtr object.

Return Value

The first operator yields true if object a is equal to object b; otherwise, false.

The second and third operators yield true if object a is equal to nullptr; otherwise, false.

ComPtr::operator!=

Indicates whether two ComPtr objects aren't equal.

bool operator!=(
   const ComPtr<T>& a,
   const ComPtr<U>& b
);

bool operator!=(
   const ComPtr<T>& a,
   decltype(__nullptr)
);

bool operator!=(
   decltype(__nullptr),
   const ComPtr<T>& a
);

Parameters

a
A reference to a ComPtr object.

b
A reference to another ComPtr object.

Return Value

The first operator yields true if object a isn't equal to object b; otherwise, false.

The second and third operators yield true if object a isn't equal to nullptr; otherwise, false.

ComPtr::operator Microsoft::WRL::Details::BoolType

Indicates whether a ComPtr is managing the object lifetime of an interface.

WRL_NOTHROW operator Microsoft::WRL::Details::BoolType() const;

Return Value

If an interface is associated with this ComPtr, the address of the BoolStruct::Member data member; otherwise, nullptr.

ComPtr::ptr_

Contains a pointer to the interface that is associated with, and managed by this ComPtr.

InterfaceType *ptr_;

Remarks

ptr_ is an internal, protected data member.

ComPtr::ReleaseAndGetAddressOf

Releases the interface associated with this ComPtr and then retrieves the address of the ptr_ data member, which contains a pointer to the interface that was released.

T** ReleaseAndGetAddressOf();

Return Value

The address of the ptr_ data member of this ComPtr.

ComPtr::Reset

Releases the interface associated with this ComPtr and returns the new reference count.

unsigned long Reset();

Return Value

The number of references remaining to the underlying interface, if any.

ComPtr::Swap

Exchanges the interface managed by the current ComPtr with the interface managed by the specified ComPtr.

void Swap(
   _Inout_ ComPtr&& r
);

void Swap(
   _Inout_ ComPtr& r
);

Parameters

r
A ComPtr.