Edit

winrt::implements struct template (C++/WinRT)

  • Article

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.

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:

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.

See also