winrt namespace (C++/WinRT)
The winrt namespace provides custom data types belonging to C++/WinRT—the standard, modern C++17 language projection for Windows Runtime (WinRT) APIs. These custom types provide appropriate conversions to and from standard types so that, much of the time, you can continue to use the standard C++ language features that you're accustomed to using, and the source code that you already have.
Also provided in the winrt namespace are functions (for creating runtime class instances, boxing and unboxing, etc.), smart pointers, and other facilities.
Types in the winrt namespace
| Type | Description |
|---|---|
| agile_ref struct template | A type representing an agile reference to a C++/WinRT object or interface. |
| apartment_context struct | Captures the thread context within a coroutine so that it can be restored later. |
| array_view struct template | A view, or span, of a contiguous series of values. |
| auto_revoke_t marker struct | A marker type used to request an event revoker when registering a delegate to handle an event. |
| cloaked marker struct template | A marker type used to indicate that an implemented interface should not be reported by IInspectable::GetIids |
| clock struct | A type containing static helper functions for converting a Windows::Foundation::DateTime (that is, a std::chrono::time_point) to and from winrt::file_time, and to and from time_t. |
| com_array struct template | A view, or span, of a contiguous series of values for passing to and from Windows Runtime APIs. |
| com_ptr struct template | A reference-counted COM smart pointer template. |
| composable marker struct | A marker type used to indicate that the type can be the inner class of a composable class. |
| composing marker struct | A marker type used to indicate that the type is the outer class of a composable class. |
| deferrable_event_args | A type that you can use to implement (produce) the deferrable event pattern. |
| delegate struct template | A type that you can use to declare a custom delegate type for your own events. |
| event struct template | A type that you can use to declare and implement an event of a specified delegate type. |
| event_revoker struct template | When you register a delegate, you can request an event revoker, which you can use to automatically or manually revoke your delegate. |
| event_token struct | A token returned when registering an event-handling delegate with an event; can be used to revoke the registration of the same delegate. |
| file_handle struct | Represents a Windows file handle object. |
| fire_and_forget struct | Use this return type to make your coroutine a fire-and-forget one. |
| guid struct | Represents a globally-unique identifier (GUID). |
| handle struct | Represents a Windows handle object. |
| handle_type struct template | The template for the winrt::handle and winrt::file_handle structs. |
| hstring struct | A sequential collection of UTF-16 Unicode characters representing a text string. |
| hresult_access_denied struct | A type derived from winrt::hresult_error, representing an E_ACCESSDENIED HRESULT error code. |
| hresult_canceled struct | A type derived from winrt::hresult_error, representing an ERROR_CANCELLED HRESULT error code. |
| hresult_changed_state struct | A type derived from winrt::hresult_error, representing an E_CHANGED_STATE HRESULT error code. |
| hresult_class_not_available struct | A type derived from winrt::hresult_error, representing an CLASS_E_CLASSNOTAVAILABLE HRESULT error code. |
| hresult_error struct | A type representing an HRESULT error code. |
| hresult_illegal_delegate_assignment struct | A type derived from winrt::hresult_error, representing an E_ILLEGAL_DELEGATE_ASSIGNMENT HRESULT error code. |
| hresult_illegal_method_call struct | A type derived from winrt::hresult_error, representing an E_ILLEGAL_METHOD_CALL HRESULT error code. |
| hresult_illegal_state_change struct | A type derived from winrt::hresult_error, representing an E_ILLEGAL_STATE_CHANGE HRESULT error code. |
| hresult_invalid_argument struct | A type derived from winrt::hresult_error, representing an E_INVALIDARG HRESULT error code. |
| hresult_no_interface struct | A type derived from winrt::hresult_error, representing an E_NOINTERFACE HRESULT error code. |
| hresult_not_implemented struct | A type derived from winrt::hresult_error, representing an E_NOTIMPL HRESULT error code. |
| hresult_out_of_bounds struct | A type derived from winrt::hresult_error, representing an E_BOUNDS HRESULT error code. |
| hresult_wrong_thread struct | A type derived from winrt::hresult_error, representing an RPC_E_WRONG_THREAD HRESULT error code. |
| implements struct template | A base struct template that implements one or more Windows Runtime interfaces on behalf of a derived type. |
| map_base struct template | A base class, for you to derive from, that represents a non-observable associative collection. |
| map_view_base struct template | A base class, for you to derive from, that represents a view of a contiguous sequence of elements in an associative collection. |
| no_module_lock marker struct | A marker type used to indicate that instances of a type do not count toward the module object count. |
| no_weak_ref marker struct | A marker type used to opt out of weak reference support. |
| non_agile marker struct | A marker type used to indicate that your type is not agile, and consequently does not implement the IAgileObject interface. |
| observable_map_base struct template | A base class, for you to derive from, that represents an observable associative collection. |
| observable_vector_base struct template | A base class, for you to derive from, that represents an observable vector. |
| static_lifetime marker struct | A marker type used to opt an activation factory in to static lifetime. |
| vector_base struct template | A base class, for you to derive from, that represents a non-observable general-purpose collection known as a vector. |
| vector_view_base struct template | A base class from which you can derive to implement your own custom view, or span, of a contiguous sequence of elements in a general-purpose collection. |
| weak_ref struct template | A type representing a weak reference to a C++/WinRT object or interface. |
| Windows::Foundation::IUnknown struct | Every C++/WinRT runtime class (whether a Windows or a third party runtime class) derives from winrt::Windows::Foundation::IUnknown. |
Functions in the winrt namespace
| Function | Description |
|---|---|
| attach_abi function | A helper function that attaches a C++/WinRT object to a handle, or to a raw pointer that owns a reference to its target. |
| box_value function template | A function template that wraps (or boxes) a scalar or array value inside a reference class object so that it can be passed to a function that expects IInspectable. |
| capture function template | A function template that calls a specified function or method, captures the resulting interface pointer, and returns it as a winrt::com_ptr. |
| check_bool function template | A helper function that checks whether a value is false and, if so, retrieves the calling thread's last-error code value, and throws an exception using a C++/WinRT object that represents that error code. |
| check_hresult function | A helper function that checks whether an HRESULT code represents an error and, if so, throws an exception using a C++/WinRT object that represents the error code. |
| check_nt function template | A helper function that checks whether a code represents an error and, if so, maps the NT status value of the error code to an HRESULT value and throws an exception using a C++/WinRT object that represents the error code. |
| check_pointer function template | A helper function that checks whether a pointer is null and, if so, retrieves the calling thread's last-error code value, and throws an exception using a C++/WinRT object that represents that error code. |
| check_win32 function template | A helper function that checks whether a code represents an error and, if so, maps the system error code of the value to an HRESULT value and throws an exception using a C++/WinRT object that represents the error code. |
| copy_from_abi function | A helper function that copies to a C++/WinRT object from a handle, or from a raw pointer. |
| copy_to_abi function | A helper function that copies to a handle, or to a pointer from a C++/WinRT object. |
| create_instance function template | A function template that creates a single uninitialized object of the class associated with a specified CLSID, and returns it as a winrt::com_ptr or throws if not successful. |
| detach_abi function | A helper function that detaches a C++/WinRT object from its referenced handle, or from its referenced interface. |
| from_abi function template | A helper function which, given an object of a projected type, retrieves a pointer to the implementation. |
| get_abi function | A helper function that retrieves a pointer to a C++/WinRT object's underlying IUnknown interface. |
| get_activation_factory function template | A helper function that retrieves the activation factory for a specified Windows Runtime class type. |
| get_cancellation_token function | In a coroutine, use the object returned by winrt::get_cancellation_token to poll for, or to respond to, cancellation. |
| get_class_name function | A helper function that retrieves a string containing the fully-qualified type name of a specified Windows Runtime class. |
| get_interfaces function | A helper function that retrieves an array containing the identifiers of the interfaces that are implemented by a C++/WinRT object. |
| get_progress_token function | In a coroutine, use the object returned by winrt::get_progress_token to report progress back to a progress handler. |
| get_self function template | A helper function which, given an object of a projected type, retrieves a pointer to the implementation. |
| get_trust_level function | A helper function that retrieves the trust level of a C++/WinRT object. |
| get_unknown function | A helper function that returns the address of the underlying raw IUnknown interface of an object of a projected type. |
| guid_of function template | A helper function template that retrieves the GUID of a runtime class, coclass, or interface. |
| is_guid_of function template | A helper function template that determines whether or not the provided GUID is that of one of the specified runtime classes, coclasses, or interfaces. |
| make function template | A factory method that returns an instance of a projected type or interface when parameterized with the corresponding implementation type. |
| make_agile function template | A helper function that returns an agile_ref object, representing an agile reference to a C++/WinRT object or interface. |
| make_self function template | A factory method that returns a com_ptr to an instance of the implementation type for a runtime class. |
| make_weak function template | A helper function that returns a weak_ref object, representing a weak reference to a C++/WinRT object or interface. |
| name_of function template | A helper function that retrieves a string view containing the fully-qualified type name of a particular Windows Runtime class. |
| put_abi function | A helper function that retrieves the address of a C++/WinRT object's underlying IUnknown interface pointer so that it can be set to another value. |
| resume_after function | A helper function that returns control to the caller, and then resumes execution on a thread pool thread after a delay. |
| resume_background function | A helper function that returns control to the caller, and resumes execution on a thread pool thread. |
| resume_foreground function | A helper function—for use within a coroutine—that you can co_await to switch execution to a specific foreground thread. |
| resume_on_signal | A function that you can use to suspend until a kernel event is signaled. |
| single_threaded_map function template | A function template that creates and returns an object of a type that implements a non-observable associative collection (map). The object is returned as an IMap. |
| single_threaded_observable_map function template | A function template that creates and returns an object of a type that implements an observable associative collection (map). The object is returned as an IObservableMap. |
| single_threaded_observable_vector function template | A function template that creates and returns an object of a type that implements an observable collection. The object is returned as an IObservableVector. |
| single_threaded_vector function template | A function template that creates and returns an object of a type that implements a general-purpose collection. The object is returned as an IVector. |
| swap function | A helper function that swaps the contents of two values. |
| throw_hresult function | A helper function that takes a HRESULT error code, and throws an exception using a C++/WinRT object that represents that error code. |
| throw_last_error function | A helper function that retrieves the calling thread's last-error code value, and throws an exception using a C++/WinRT object that represents that error code. |
| to_hresult function | A helper function, for use in a catch block, that turns the last exception thrown into a HRESULT error code. |
| to_hstring function | A helper function that converts an input value to a winrt::hstring containing the value's string representation. |
| to_string function | A helper function that converts an input wide string to a std::string containing a UTF-8 narrow string. |
| try_capture function template | A function template that calls a specified function or method, captures the interface pointer that's output from the function or method, and returns it as a winrt::com_ptr or an empty com_ptr if not successful. |
| try_create_instance function template | A function template that creates a single uninitialized object of the class associated with a specified CLSID, and returns it as a winrt::com_ptr or an empty com_ptr if not successful. |
| try_get_activation_factory function template | A helper function that retrieves the activation factory for a specified Windows Runtime class type or an empty com_ptr if not successful. |
| unbox_value function template | A function template that unwraps (or unboxes) a scalar or array value from inside a reference class object so that it can be processed in a function that expects IInspectable. |
| unbox_value_or function template | A function template that unwraps (or unboxes) a scalar value from inside a reference class object, with a fallback value, so that it can be processed in a function that expects IInspectable. |
| xaml_typename function template | A helper function that returns the type name of a Windows Runtime type, in the form of a Windows::UI::Xaml::Interop::TypeName object. |
C++/WinRT functions that extend Windows Runtime APIs
Extension functions exist on the C++/WinRT projection types for certain Windows Runtime APIs. For example, winrt::Windows::Foundation::IAsyncAction is the C++/WinRT projection type for IAsyncAction. The extension functions aren't part of the application binary interface (ABI) surface of the actual Windows Runtime types, so they're not listed as members of the Windows Runtime APIs. But you can call them from within any C++/WinRT project.
Other functions
| Function | Description |
|---|---|
| GetRuntimeClassName function | A member function (of a generated implementation type) that returns a string containing the fully-qualified type name of the Windows Runtime class being implemented. |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for