winrt::com_ptr struct template (C++/WinRT)
A reference-counted COM smart pointer template. com_ptr represents a pointer to the interface or runtime class implementation type specified by the template parameter. It automatically manages the reference count for its target through a private raw pointer.
template <typename T>
struct com_ptr
typename T
The interface, or runtime class implementation type, a pointer to which is represented by the com_ptr. This is the type of the smart pointer's target.
Minimum supported SDK: Windows SDK version 10.0.17134.0 (Windows 10, version 1803)
Namespace: winrt
Header: %WindowsSdkDir%Include<WindowsTargetPlatformVersion>\cppwinrt\winrt\base.h (included by default)
Alias name | Type |
---|---|
com_ptr::type | A synonym for an implementation-defined representation of the typename T template parameter. |
Constructor | Description |
---|---|
com_ptr::com_ptr constructor | Initializes a new instance of the com_ptr struct, optionally with a copy or move of the input data. |
Function | Description |
---|---|
com_ptr::as function | Returns the requested interface, if it is supported. Throws if it is not. |
com_ptr::attach function | Attaches to a raw pointer that owns a reference to its target; an additional reference is not added. |
com_ptr::capture function | Calls a specified function or method (automatically calling winrt::check_hresult on it), and captures the interface pointer that's output from the function or method as a void** . |
com_ptr::copy_from function | Copies from another pointer. Decrements the reference count on any currently referenced interface or object, copies the raw pointer parameter, and begins managing the lifetime of the interface or object pointed to by it. |
com_ptr::copy_to function | Copies to another pointer from the com_ptr object. Increments the reference count on any currently referenced interface or object, and copies that interface or object's memory address into the parameter. |
com_ptr::detach function | Detaches from the referenced interface or object without decrementing the reference count, perhaps to return it to a caller. |
com_ptr::get function | Returns the underlying raw pointer should you need to pass it to a function. |
com_ptr::put function | Returns the address of the underlying raw pointer; this function helps you call methods (such as COM methods) that return references as out parameters via a pointer to a pointer. |
com_ptr::put_void function | Returns the address of the underlying raw pointer as a pointer to a pointer to void; this function helps you call methods (such as COM methods) that return references as out parameters via a pointer to a pointer to void. |
com_ptr::try_as function | Returns the requested interface, if it is supported. Returns nullptr , or false , if it is not. |
com_ptr::try_capture function | A version of com_ptr::capture that doesn't throw on failure but instead returns returns true if successful or false if not. |
Operator | Description |
---|---|
com_ptr::operator bool | Checks whether or not the smart pointer is referencing an interface or object. |
com_ptr::operator* (indirection operator) | Returns a reference to the com_ptr's target so that you can pass it to a function that expects a reference to the target type T. |
com_ptr::operator= (assignment operator) | Assigns a value to the com_ptr object. |
com_ptr::operator-> (arrow operator) | To afford access to the referenced interface or object's methods, returns the underlying raw pointer. |
Function | Description |
---|---|
attach_abi function | Attaches a com_ptr object to a raw pointer that owns a reference to its target; an additional reference is not added. |
detach_abi function | Detaches a com_ptr object from its raw interface without decrementing the reference count, perhaps to return it to a caller. |
swap function | Swaps the contents of the two com_ptr parameters so that they point at one another's target. |
Function | Description |
---|---|
operator!= (inequality operator) | Returns a value indicating whether the two parameters refer to different targets. |
operator< (less-than operator) | Returns a value indicating whether the first parameter's target occurs earlier in memory than that of the second parameter. |
operator<= (less-than-or-equal-to operator) | Returns a value indicating whether the first parameter's target occurs earlier in memory than, or at the same location as, that of the second parameter. |
operator== (equality operator) | Returns a value indicating whether the two parameters refer to the same interface and/or object. |
operator> (greater-than operator) | Returns a value indicating whether the first parameter's target occurs later in memory than that of the second parameter. |
operator>= (greater-than-or-equal-to operator) | Returns a value indicating whether the first parameter's target occurs later in memory than, or at the same location as, that of the second parameter. |
Initializes a new instance of the com_ptr struct, optionally with a copy or move of the input data.
The void*
constructor takes a T*, and assumes ownership. winrt::take_ownership_from_abi_t is a marker type that makes explicit the responsibility to release this pointer is now being transferred to the com_ptr. The refcount doesn't have to be exactly 1; it's just saying that responsibility is being transferred.
com_ptr(winrt::com_ptr const& other) noexcept;
com_ptr(std::nullptr_t = nullptr) noexcept;
com_ptr(void* ptr, winrt::take_ownership_from_abi_t) noexcept;
template <typename U> com_ptr(winrt::com_ptr<U> const& other) noexcept;
template <typename U> com_ptr(winrt::com_ptr<U>&& other) noexcept;
typename U
The target type pointed to by the input smart pointer.
other
Another com_ptr that initializes the com_ptr object. The parameter's T must be convertible to the com_ptr object's T.
Returns the requested interface, if it is supported. Throws if it is not. This function is useful if you want to query for an interface that you don't need to pass back to your caller.
For code examples, see the section Instantiating and returning projected types and interfaces, and other sections in that topic.
template <typename To> auto as() const;
template <typename To> void as(To& to) const;
typename To
The type of the requested interface.
to
A reference to a value to receive the requested interface.
A com_ptr referencing the requested interface, or a strongly-typed smart pointer for the requested interface (either declared by C++/WinRT or by a third party).
Attaches to a raw pointer that owns a reference to its target; an additional reference is not added. If needed, you can use this function to coalesce references.
void attach(T* value) noexcept;
value
A raw pointer that owns a reference to its target.
Calls a specified function or method (automatically calling winrt::check_hresult on it), and captures the interface pointer that's output from the function or method as a void**
.
Also see the winrt::capture function template.
template <typename F, typename...Args>
void capture(F function, Args&&...args);
template <typename O, typename M, typename...Args>
void capture(O* p, M method, Args&& ...args);
template <typename O, typename M, typename...Args>
void capture(winrt::com_ptr<O> const& object, M method, Args&&...args);
typename F
A function object type, such as a free function, or std::function.
typename O
An interface type.
typename M
A method type.
typename Args
Zero or more argument types.
function
A function object of type F
.
p
A pointer to an object of type O
.
object
A winrt::com_ptr of type O
.
method
A method (implemented by O
) of type M
.
args
Zero or more arguments of type Args
.
- The
capture(F function, Args&&...args)
overload invokes the function object. - The
capture(O* p, M method, Args&& ...args)
overload invokes the method on the pointer. - The
capture(winrt::com_ptr<O> const& object, M method, Args&&...args)
overload invokes the method on the object.
All overloads pass through (to the invokee) any additional arguments that you provide. All overloads also pass the two additional arguments that such invokees require—specifically, a REFIID (the ID of the target of the winrt::com_ptr), and a void** (The address of a pointer to the target of the winrt::com_ptr).
winrt::com_ptr<IDXGIAdapter> adapter
...
winrt::com_ptr<IDXGIFactory2> factory;
factory.capture(adapter, &IDXGIAdapter::GetParent);
Copies from another pointer. Decrements the reference count on any currently referenced interface or object, copies the raw pointer parameter, and begins managing the lifetime of the interface or object pointed to by it.
void copy_from(T* other) noexcept;
other
A raw pointer to a target whose lifetime should be managed by the com_ptr object.
Copies to another pointer from the com_ptr object. Increments the reference count on any currently referenced interface or object, and copies that interface or object's memory address into the parameter. This function lets you hand out a reference to the same interface without calling QueryInterface.
void copy_to(T** other) const noexcept;
other
A raw pointer's address; into which to copy the pointer to the com_ptr object's target.
Detaches from the referenced interface or object without decrementing the reference count, perhaps to return it to a caller.
T* detach() noexcept;
A pointer to the interface or object referenced by the com_ptr object.
Returns the underlying raw pointer should you need to pass it to a function. You may call AddRef, Release, or QueryInterface on the returned pointer.
T* get() const noexcept;
A pointer to the interface or object referenced by the com_ptr object.
Returns the address of the underlying raw pointer; this function helps you call methods (such as COM methods) that return references as out parameters via a pointer to a pointer. If the com_ptr object already has a target, then assign nullptr
to the com_ptr object before calling this function, otherwise the function will assert.
T** put() noexcept;
The address of the underlying raw pointer.
Returns the address of the underlying raw pointer as a pointer to a pointer to void; this function helps you call methods (such as COM methods) that return references as out parameters via a pointer to a pointer to void. If the com_ptr object already has a target, then assign nullptr
to the com_ptr object before calling this function, otherwise the function will assert.
void** put_void() noexcept;
The address of the underlying raw pointer as a pointer to a pointer to void.
Returns the requested interface, if it is supported. Returns nullptr
(the auto
-returning overload), or false
(the bool
-returning overload), if it is not. This function is useful if you want to query for an interface that you don't need to pass back to your caller.
template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;
typename To
The type of the requested interface.
to
A reference to a value to receive the requested interface.
A com_ptr referencing the requested interface, or a strongly-typed smart pointer for the requested interface (either declared by C++/WinRT or by a third party), if the requested interface is supported, otherwise nullptr
(the auto
-returning overload), or false
(the bool
-returning overload).
A version of com_ptr::capture that doesn't throw on failure but instead returns returns true
if successful or false
if not.
Also see the winrt::try_capture function template.
Checks whether or not the smart pointer is referencing an interface or object. If the smart pointer is not referencing an interface or object, then it is logically null; otherwise it is logically not null.
explicit operator bool() const noexcept;
true
if the smart pointer is referencing an interface or object (logically not null), otherwise false
(logically null).
Returns a reference to the com_ptr's target so that you can pass it to a function that expects a reference to the target type T.
T& operator*() const noexcept;
A reference to the com_ptr's target.
Assigns a value to the com_ptr object.
winrt::com_ptr& operator=(winrt::com_ptr const& other) noexcept;
template <typename U> winrt::com_ptr& operator=(winrt::com_ptr<U> const& other) noexcept;
template <typename U> winrt::com_ptr& operator=(winrt::com_ptr<U>&& other) noexcept;
typename U
The type pointed to by the value being assigned.
other
A com_ptr value to assign to the com_ptr object. The parameter's T must be convertible to the com_ptr object's T.
A reference to the com_ptr object.
To afford access to the referenced interface or object's methods, returns the underlying raw pointer. You may not call AddRef nor Release on the returned pointer, but you may call QueryInterface.
auto operator->() const noexcept;
A pointer to the interface or object referenced by the com_ptr object.
Attaches a com_ptr object to a raw pointer that owns a reference to its target; an additional reference is not added. If needed, you can use this function to coalesce references.
void attach_abi(winrt::com_ptr<T>& object, T* value) noexcept;
object
A com_ptr object to operate on.
value
A raw pointer that owns a reference to its target.
Detaches a com_ptr object from its raw interface without decrementing the reference count, perhaps to return it to a caller.
auto detach_abi(winrt::com_ptr<T>& object) noexcept;
object
A com_ptr object to operate on.
A pointer to the raw interface referenced by the com_ptr object.
Returns a value indicating whether the two parameters refer to different targets.
template <typename T> bool operator!=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
template <typename T> bool operator!=(winrt::com_ptr<T> const& left, std::nullptr_t) noexcept;
template <typename T> bool operator!=(std::nullptr_t, winrt::com_ptr<T> const& right) noexcept;
left
right
A com_ptr value whose target's memory address to compare with that of the other parameter.
true
if the two parameters point to different targets, otherwise false
.
Returns a value indicating whether the first parameter's target occurs earlier in memory than that of the second parameter.
template <typename T> bool operator<(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
left
right
A com_ptr value whose target's memory address to compare with that of the other parameter.
true
if the first parameter's target's memory address is less than that of the second parameter, otherwise false
.
Returns a value indicating whether the first parameter's target occurs earlier in memory than, or at the same location as, that of the second parameter.
template <typename T> bool operator<=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
left
right
A com_ptr value whose target's memory address to compare with that of the other parameter.
true
if the first parameter's target's memory address is less than or equal to that of the second parameter, otherwise false
.
Returns a value indicating whether the two parameters refer to the same interface and/or object.
template <typename T> bool operator==(winrt::com_ptr<T> const& left, std::nullptr_t) noexcept;
template <typename T> bool operator==(std::nullptr_t, winrt::com_ptr<T> const& right) noexcept;
left
right
A com_ptr value whose target's memory address to compare with that of the other parameter.
true
if the two parameters point to the same target, otherwise false
.
Returns a value indicating whether the first parameter's target occurs later in memory than that of the second parameter.
template <typename T> bool operator>(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
left
right
A com_ptr value whose target's memory address to compare with that of the other parameter.
true
if the first parameter's target's memory address is greater than that of the second parameter, otherwise false
.
Returns a value indicating whether the first parameter's target occurs later in memory than, or at the same location as, that of the second parameter.
template <typename T> bool operator>=(winrt::com_ptr<T> const& left, winrt::com_ptr<T> const& right) noexcept;
left
right
A com_ptr value whose target's memory address to compare with that of the other parameter.
true
if the first parameter's target's memory address is greater than or equal to that of the second parameter, otherwise false
.
Swaps the contents of the two com_ptr parameters so that they point at one another's target.
void swap(winrt::com_ptr& left, winrt::com_ptr& right) noexcept;
left
right
A com_ptr value whose pointer to mutually swap with that of the other parameter.