description | title | ms.date | ms.topic | ms.assetid |
---|---|---|---|---|
Learn more about: How to: Activate and Use a Windows Runtime Component Using WRL |
How to: Activate and Use a Windows Runtime Component Using WRL |
11/04/2016 |
reference |
54828f02-6af3-45d1-b965-d0104442f8d5 |
This document shows how to use the Windows Runtime C++ Template Library (WRL)to initialize the Windows Runtime and how to activate and use a Windows Runtime component.
To use a component, you must acquire an interface pointer to the type that is implemented by the component. And because the underlying technology of the Windows Runtime is the Component Object Model (COM), you must follow COM rules to maintain an instance of the type. For example, you must maintain the reference count that determines when the type is deleted from memory.
To simplify the use of the Windows Runtime, Windows Runtime C++ Template Library provides the smart pointer template, ComPtr<T>, that automatically performs reference counting. When you declare a variable, specify ComPtr<
interface-name>
identifier. To access an interface member, apply the arrow member-access operator (->
) to the identifier.
Important
When you call an interface function, always test the HRESULT return value.
The following steps use the Windows::Foundation::IUriRuntimeClass
interface to demonstrate how to create an activation factory for a Windows Runtime component, create an instance of that component, and retrieve a property value. They also show how to initialize the Windows Runtime. The complete example follows.
Important
Although you typically use the Windows Runtime C++ Template Library in a Universal Windows Platform (UWP) app, this example uses a console app for illustration. Functions such as wprintf_s
are not available from a UWP app. For more information about the types and functions that you can use in a UWP app, see CRT functions not supported in Universal Windows Platform apps and Win32 and COM for UWP apps.
-
Include (
#include
) any required Windows Runtime, Windows Runtime C++ Template Library, or C++ Standard Library headers.[!code-cppwrl-consume-component#2]
We recommend that you utilize the
using namespace
directive in your .cpp file to make the code more readable. -
Initialize the thread in which the app executes. Every app must initialize its thread and threading model. This example uses the Microsoft::WRL::Wrappers::RoInitializeWrapper class to initialize the Windows Runtime and specifies RO_INIT_MULTITHREADED as the threading model. The
RoInitializeWrapper
class callsWindows::Foundation::Initialize
at construction, andWindows::Foundation::Uninitialize
when it is destroyed.[!code-cppwrl-consume-component#3]
In the second statement, the RoInitializeWrapper::HRESULT operator returns the
HRESULT
from the call toWindows::Foundation::Initialize
. -
Create an activation factory for the
ABI::Windows::Foundation::IUriRuntimeClassFactory
interface.[!code-cppwrl-consume-component#4]
The Windows Runtime uses fully-qualified names to identify types. The
RuntimeClass_Windows_Foundation_Uri
parameter is a string that's provided by the Windows Runtime and contains the required runtime class name. -
Initialize a Microsoft::WRL::Wrappers::HString variable that represents the URI
"https://www.microsoft.com"
.[!code-cppwrl-consume-component#6]
In the Windows Runtime, you don't allocate memory for a string that the Windows Runtime will use. Instead, the Windows Runtime creates a copy of your string in a buffer that it maintains and uses for operations, and then returns a handle to the buffer that it created.
-
Use the
IUriRuntimeClassFactory::CreateUri
factory method to create aABI::Windows::Foundation::IUriRuntimeClass
object.[!code-cppwrl-consume-component#7]
-
Call the
IUriRuntimeClass::get_Domain
method to retrieve the value of theDomain
property.[!code-cppwrl-consume-component#8]
-
Print the domain name to the console and return. All
ComPtr
and RAII objects leave scope and are released automatically.[!code-cppwrl-consume-component#9]
The WindowsGetStringRawBuffer function retrieves the underlying Unicode form of the URI string.
Here's the complete example:
[!code-cppwrl-consume-component#1]
To compile the code, copy it and then paste it in a Visual Studio project, or paste it in a file that is named wrl-consume-component.cpp
and then run the following command in a Visual Studio Command Prompt window.
cl.exe wrl-consume-component.cpp runtimeobject.lib