Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Every C++/WinRT runtime class (whether a Windows or a third party runtime class) derives from winrt::Windows::Foundation::IUnknown. It represents the COM IUnknown interface, and it provides facilities such as querying for a different interface, abi functions, and comparison operators.
Syntax
struct IUnknown
Requirements
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)
Constructors
| Constructor | Description |
|---|---|
| IUnknown::IUnknown constructor | Initializes a new instance of the IUnknown struct, optionally with a copy or move of the input data. |
Member functions
| Function | Description |
|---|---|
| IUnknown::as function | Requests an interface, throwing if it is not supported. |
| IUnknown::try_as function | Requests an interface, producing null if it is not supported. |
| IUnknown::try_as_with_reason function | Requests an interface, reporting the reason if it is not supported. |
Member operators
| Operator | Description |
|---|---|
| IUnknown::operator bool | Checks whether or not the IUnknown object is referencing an interface. |
| IUnknown::operator= (assignment operator) | Assigns a value to the IUnknown object. |
Free functions
| Function | Description |
|---|---|
| attach_abi function | Attaches an IUnknown object to a raw pointer that owns a reference to its target; an additional reference is not added. |
| copy_from_abi function | Copies to an IUnknown object 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. |
| copy_to_abi function | Copies to another pointer from an IUnknown object. Increments the reference count on any currently referenced interface or object, and copies that interface or object's memory address into the parameter. |
| detach_abi function | Detaches from the raw IUnknown interface without decrementing the reference count, perhaps to return it to a caller. |
| get_abi function | Returns the underlying raw IUnknown interface pointer should you need to pass it to a function. |
| get_unknown function | A helper function that returns the address of the underlying raw IUnknown interface of an object of a projected type. |
| put_abi function | Returns the address of the underlying raw IUnknown interface 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. |
| swap function | Swaps the contents of the two IUnknown parameters so that they point at one another's target. |
Free operators
| 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. |
IUnknown::IUnknown constructor
Initializes a new instance of the IUnknown struct, optionally with a copy or move of the input data.
Syntax
IUnknown() noexcept;
IUnknown(std::nullptr_t) noexcept;
IUnknown(winrt::Windows::Foundation::IUnknown const& other) noexcept;
IUnknown(winrt::Windows::Foundation::IUnknown&& other) noexcept;
Parameters
other
Another IUnknown that initializes the IUnknown object.
IUnknown::as function
Requests the specified interface from the IUnknown. Throws if the interface is not supported. Use this method if you expect the interface to be supported.
Syntax
template <typename To> auto as() const;
template <typename To> void as(To& to) const;
Template parameters
typename To
A type that describes the requested interface.
This type can be a C++/WinRT interface name or a C++/WinRT runtime class name.
For the auto-returning overload, the type can also be a classic COM interface.
For the void-returning overload, the type can also be com_ptr<I> where I is a classic COM interface.
Parameters
to
A reference to a value to receive the requested interface.
Return value
The auto-returning overload returns the requested interface, in the form of To if it is a C++/WinRT interface or runtime class name, or in the form of com_ptr<To> if To is a classic COM interface.
If the IUnknown is null, then the auto-returning overload returns null, and the void-returning overload sets to to null.
If the IUnknown is non-null but the interface cannot be obtained, the method throws.
IUnknown::try_as function
Requests the specified interface from the IUnknown. Produces null if the interface is not supported.
Syntax
template <typename To> auto try_as() const noexcept;
template <typename To> bool try_as(To& to) const noexcept;
Template parameters
typename To
A type that describes the requested interface.
This type can be a C++/WinRT interface name or a C++/WinRT runtime class name.
For the auto-returning overload, the type can also be a classic COM interface.
For the bool-returning overload, the type can also be com_ptr<I> where I is a classic COM interface.
Parameters
to
A reference to a value to receive the requested interface.
Return value
The auto-returning overload returns the requested interface, in the form of To if it is a C++/WinRT interface or runtime class name, or in the form of com_ptr<To> if To is a classic COM interface.
If the IUnknown is null or if the interface cannot be obtained, then the auto-returning overload returns null, and the bool-returning overload sets to to null.
The bool returning overload returns true if the value returned in to is non-null and false if it is null.
IUnknown::try_as_with_reason function
Returns the requested interface, if it is supported, and reports the reason if it is not supported.
Syntax
template <typename To> auto try_as_with_reason(winrt::hresult& reason) const noexcept;
Template parameters
typename To
A type that describes the requested interface.
This type can be a C++/WinRT interface name, a C++/WinRT runtime class name, or a classic COM interface.
Parameters
reason
Receives the winrt::hresult which describes the result of the query.
Return value
Returns the requested interface, in the form of To if it is a C++/WinRT interface or runtime class name, or in the form of com_ptr<To> if To is a classic COM interface.
If the IUnknown is null or if the interface cannot be obtained, then the method returns null.
Remarks
This method is available starting in C++/WinRT version 2.0.250303.1.
If the IUnknown is null, then the method returns null and sets the reason to S_OK.
If the IUnknown is non-null, then the method returns the result of the query, and the reason receives the winrt::hresult produced by the query.
IUnknown::operator bool
Checks whether or not the IUnknown object is referencing an interface. If the IUnknown object is not referencing an interface, then it is logically null; otherwise it is logically not null.
Syntax
explicit operator bool() const noexcept;
Return value
true if the IUnknown object is referencing an interface (logically not null), otherwise false (logically null).
IUnknown::operator= (assignment operator)
Assigns a value to the IUnknown object.
Syntax
winrt::Windows::Foundation::IUnknown& operator=(winrt::Windows::Foundation::IUnknown const& other) noexcept;
winrt::Windows::Foundation::IUnknown& operator=(winrt::Windows::Foundation::IUnknown&& other) noexcept;
winrt::Windows::Foundation::IUnknown& operator=(std::nullptr_t) noexcept;
Parameters
other
An IUnknown value to assign to the IUnknown object, either by copy or by move.
Return value
A reference to the IUnknown object.
attach_abi function
Attaches an IUnknown 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.
Syntax
void attach_abi(winrt::Windows::Foundation::IUnknown& object, void* value) noexcept;
Parameters
object
An IUnknown value to operate on.
value
A raw pointer that owns a reference to its target.
copy_from_abi function
Copies to an IUnknown object 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.
Syntax
void copy_from_abi(winrt::Windows::Foundation::IUnknown& object, void* value) noexcept;
Parameters
object
An IUnknown value to operate on.
value
A raw pointer to a target whose lifetime should be managed by the IUnknown object.
copy_to_abi function
Copies to another pointer from an IUnknown 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.
Syntax
void copy_to_abi(winrt::Windows::Foundation::IUnknown const& object, void*& value) noexcept;
Parameters
object
An IUnknown value to operate on.
value
A raw pointer reference; via which to copy the pointer to the IUnknown object's target.
detach_abi function
Detaches an IUnknown object from its raw IUnknown interface without decrementing the reference count, perhaps to return it to a caller.
Syntax
void* detach_abi(winrt::Windows::Foundation::IUnknown& object) noexcept;
void* detach_abi(winrt::Windows::Foundation::IUnknown&& object) noexcept;
Parameters
object
An IUnknown value to operate on.
Return value
A pointer to the raw IUnknown interface referenced by the IUnknown object.
get_abi function
Returns the underlying raw IUnknown interface pointer should you need to pass it to a function. You may call AddRef, Release, or QueryInterface on the returned pointer.
Syntax
void* get_abi(winrt::Windows::Foundation::IUnknown const& object) noexcept;
Parameters
object
An IUnknown value to operate on.
Return value
A pointer to the raw IUnknown interface referenced by the IUnknown object.
operator!= (inequality operator)
Returns a value indicating whether the two parameters refer to different targets.
Syntax
bool operator!=(winrt::Windows::Foundation::IUnknown const& left, winrt::Windows::Foundation::IUnknown const& right) noexcept;
Parameters
left right
An IUnknown value whose target's memory address to compare with that of the other parameter.
Return value
true if the two parameters point to different targets, otherwise false.
operator< (less-than operator)
Returns a value indicating whether the first parameter's target occurs earlier in memory than that of the second parameter.
Syntax
bool operator<(winrt::Windows::Foundation::IUnknown const& left, winrt::Windows::Foundation::IUnknown const& right) noexcept;
Parameters
left right
An IUnknown value whose target's memory address to compare with that of the other parameter.
Return value
true if the first parameter's target's memory address is less than that of the second parameter, otherwise false.
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.
Syntax
bool operator<=(winrt::Windows::Foundation::IUnknown const& left, winrt::Windows::Foundation::IUnknown const& right) noexcept;
Parameters
left right
An IUnknown value whose target's memory address to compare with that of the other parameter.
Return value
true if the first parameter's target's memory address is less than or equal to that of the second parameter, otherwise false.
operator== (equality operator)
Returns a value indicating whether the two parameters refer to the same interface and/or object.
Syntax
bool operator==(winrt::Windows::Foundation::IUnknown const& left, winrt::Windows::Foundation::IUnknown const& right) noexcept;
Parameters
left right
An IUnknown value whose target's memory address to compare with that of the other parameter.
Return value
true if the two parameters point to the same target, otherwise false.
operator> (greater-than operator)
Returns a value indicating whether the first parameter's target occurs later in memory than that of the second parameter.
Syntax
bool operator>(winrt::Windows::Foundation::IUnknown const& left, winrt::Windows::Foundation::IUnknown const& right) noexcept;
Parameters
left right
An IUnknown value whose target's memory address to compare with that of the other parameter.
Return value
true if the first parameter's target's memory address is greater than that of the second parameter, otherwise false.
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.
Syntax
bool operator>=(winrt::Windows::Foundation::IUnknown const& left, winrt::Windows::Foundation::IUnknown const& right) noexcept;
Parameters
left right
An IUnknown value whose target's memory address to compare with that of the other parameter.
Return value
true if the first parameter's target's memory address is greater than or equal to that of the second parameter, otherwise false.
put_abi function
Returns the address of the underlying raw IUnknown interface 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.
Syntax
void** put_abi(winrt::Windows::Foundation::IUnknown& object) noexcept;
Parameters
object
An IUnknown value to operate on.
Return value
The address of the underlying raw IUnknown interface pointer.
swap function
Swaps the contents of the two IUnknown parameters so that they point at one another's target.
Syntax
void swap(winrt::Windows::Foundation::IUnknown& left, winrt::Windows::Foundation::IUnknown& right) noexcept;
Parameters
left right
An IUnknown value whose pointer to mutually swap with that of the other parameter.