winrt::implements struct template (C++/WinRT)
This is the base from which your own C++/WinRT implementations (of runtime classes and activation factories) directly or indirectly derive. It implements one or more Windows Runtime interfaces (which you specify to it as type parameters), and it also provides efficient implementations of IUnknown, IInspectable, IAgileObject, IWeakReferenceSource, and others.
Note
For more info about deriving from this type, and examples, see Author APIs with C++/WinRT.
Extension points on winrt::implements
winrt::implements has extension points that allow you to defer destruction of your implementation types, to safely query during destruction, and to hook the entry into and exit from your projected methods. Here are the names of the extension points, together with links to details and code examples.
- final_release. See Deferred destruction and Safe queries during destruction.
- abi_enter, abi_exit, and abi_guard. See Method entry and exit hooks.
Marker types
The implements struct template supports several marker types which are used to override default behavior. We expect that these will be only rarely used; the defaults are sufficient for almost all cases. A marker type can appear anywhere in the interface list, which is the variadic parameter pack.
The following marker types are supported by implements:
- cloaked<I>
- composable
- composing
- non_agile
- no_weak_ref
- no_module_lock
- static_lifetime (for factories)
This first example applies when you derive directly from implements.
struct MyImplementation: implements<MyImplementation, IFrameworkViewSource, no_weak_ref>
{
...
}
This next example is for when you're authoring a runtime class.
struct BookSku : BookSkuT<BookSku, no_weak_ref>
{
...
}
Syntax
template <typename D, typename... I>
struct implements
Template parameters
typename D
Your derived type name.
typename... I
Any number of interfaces to implement, plus any desired marker types.
By default, interfaces that derive from IInspectable are reported by the implementation of the IInspectable::GetIids method. Use the cloaked marker template to suppress that.
Example
// App.cpp
...
struct App : implements<App, IFrameworkViewSource>
{
IFrameworkView CreateView()
{
return ...
}
}
...
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)
Member functions
| Function | Description |
|---|---|
| implements::AddRef function | Increments the reference count for the default interface of the implements object. |
| implements::find_inspectable function | TBD |
| implements::find_interface function | The pointer to the interface implemented by the implements object, identified by the specified identifier; doesn't call AddRef. |
| implements::get_local_iids function | Retrieves a two-element tuple containing the identifiers of the interfaces that are implemented by the implements object. |
| implements::get_strong function | Retrieves a strong reference to the implements object's this pointer. |
| implements::get_weak function | Retrieves a weak reference to the implements object's this pointer. |
| implements::QueryInterface function | Retrieves the pointer to the interface implemented by the implements object, identified by the specified identifier; calls AddRef. |
| implements::Release function | Decrements the reference count for the default interface of the implements object. |
Member operators
| Operator | Description |
|---|---|
| implements::operator Windows::Foundation::IInspectable | Converts the implements object to a Windows::Foundation::IInspectable. |
Data members
| Data member | Description |
|---|---|
| m_inner | Accesses the composed object, where applicable. For more info, see Runtime class derivation. |
implements::AddRef function
Increments the reference count for the default interface of the implements object.
Syntax
unsigned long __stdcall AddRef() noexcept;
Return value
The new reference count. This value is intended to be used only for test purposes.
implements::find_inspectable function
Retrieves the pointer to the IInspectable interface implemented by the implements object. Does not call AddRef on the pointer that it returns. This function allows you to pass the implements object to a function that expects an IInspectable.
Syntax
::IInspectable* find_inspectable() const noexcept override;
Return value
The pointer to the IInspectable interface implemented by the implements object.
implements::find_interface function
Retrieves the pointer to the interface implemented by the implements object, identified by the specified identifier. Does not call AddRef on the pointer that it returns.
Syntax
void* find_interface(winrt::guid const& id) const noexcept override;
Return value
The pointer to the interface implemented by the implements object, identified by the specified identifier.
implements::get_local_iids function
Retrieves a two-element tuple containing the identifiers of the interfaces that are implemented by the implements object. "Cloaked" interfaces aren't included.
Syntax
std::pair<uint32_t, const winrt::guid*> get_local_iids() const noexcept override;
Return value
A two-element tuple containing the number and identifiers of the interfaces that are implemented by the implements object.
implements::get_strong function
Retrieves a strong reference to the winrt::implements object's this pointer. See Strong and weak references in C++/WinRT. Because get_strong is a member function of the winrt::implements struct template, you can call it only from an object that directly or indirectly derives from winrt::implements, such as a C++/WinRT object. For more info about deriving from winrt::implements, and examples, see Author APIs with C++/WinRT.
Syntax
protected:
winrt::com_ptr<D> get_strong() noexcept;
Return value
A strong reference to the implements object's this pointer.
implements::get_weak function
Retrieves a weak reference to the winrt::implements object's this pointer. See Strong and weak references in C++/WinRT. Because get_weak is a member function of the winrt::implements struct template, you can call it only from an object that directly or indirectly derives from winrt::implements, such as a C++/WinRT object. For more info about deriving from winrt::implements, and examples, see Author APIs with C++/WinRT.
Syntax
protected:
winrt::weak_ref<D> get_weak() noexcept;
Return value
A weak_ref object representing a weak reference to the implements object's this pointer.
implements::QueryInterface function
Retrieves the pointer to the interface implemented by the implements object, identified by the specified identifier. Calls AddRef on the pointer that it returns.
Syntax
HRESULT __stdcall QueryInterface(winrt::guid const& id, void** object) noexcept;
Return value
The new reference count. This value is intended to be used only for test purposes.
implements::Release function
Decrements the reference count for the default interface of the implements object.
Syntax
unsigned long __stdcall Release() noexcept;
Return value
The new reference count. This value is intended to be used only for test purposes.
implements::operator Windows::Foundation::IInspectable
Converts the implements object to a Windows::Foundation::IInspectable. This operator allows you to pass the implements object to a function that expects an IInspectable.
Syntax
operator winrt::Windows::Foundation::IInspectable() const noexcept;
Return value
The implements object converted to a Windows::Foundation::IInspectable.