ComPtr Class

Article
05/10/2022

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.

Share via

ComPtr Class

Syntax

Parameters

Remarks

Members

Public Typedefs

Public Constructors

Public Methods

Protected Methods

Public Operators

Protected Data Members

Inheritance Hierarchy

Requirements

ComPtr::~ComPtr

ComPtr::As

Parameters

Remarks

Return Value

ComPtr::AsIID

Parameters

Return Value

ComPtr::AsWeak

Parameters

Return Value

ComPtr::Attach

Parameters

ComPtr::ComPtr

Parameters

Return Value

Remarks

ComPtr::CopyTo

Parameters

Return Value

Remarks

ComPtr::Detach

Return Value

ComPtr::Get

Return Value

ComPtr::GetAddressOf

Return Value

ComPtr::InternalAddRef

Remarks

ComPtr::InternalRelease

Remarks

ComPtr::operator&

Return Value

Remarks

ComPtr::operator->

Return Value

Remarks

ComPtr::operator=

Parameters

Return Value

Remarks

ComPtr::operator==

Parameters

Return Value

ComPtr::operator!=

Parameters

Return Value

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

Return Value

ComPtr::ptr_

Remarks

ComPtr::ReleaseAndGetAddressOf

Return Value

ComPtr::Reset

Return Value

ComPtr::Swap

Parameters

Feedback

Additional resources

`ComPtr::~ComPtr`

`ComPtr::As`

`ComPtr::AsIID`

`ComPtr::AsWeak`

`ComPtr::Attach`

`ComPtr::ComPtr`

`ComPtr::CopyTo`

`ComPtr::Detach`

`ComPtr::Get`

`ComPtr::GetAddressOf`

`ComPtr::InternalAddRef`

`ComPtr::InternalRelease`

`ComPtr::operator&`

`ComPtr::operator->`

`ComPtr::operator=`

`ComPtr::operator==`

`ComPtr::operator!=`

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

`ComPtr::ptr_`

`ComPtr::ReleaseAndGetAddressOf`

`ComPtr::Reset`

`ComPtr::Swap`