Cómo: Activar y usar un componente de Windows Runtime mediante WRL

Artículo
04/03/2023

En este documento se muestra cómo usar la biblioteca de plantillas de Windows Runtime C++ para inicializar Windows Runtime y activar y usar un componente de Windows Runtime.

Para usar un componente, debe adquirir un puntero de interfaz al tipo implementado por el componente. Y dado que la tecnología subyacente del Windows Runtime es el Modelo de objetos componentes (COM), debe seguir las reglas COM para mantener una instancia del tipo. Por ejemplo, debe mantener el recuento de referencias que determina cuándo se elimina el tipo de la memoria.

Para simplificar el uso de Windows Runtime, la biblioteca de plantillas de Windows Runtime C++ proporciona la plantilla de puntero inteligente, ComPtr<T>, que realiza automáticamente el recuento de referencias. Cuando declare una variable, especifique ComPtr<nombre de la interfaz>identificador. Para acceder a un miembro de interfaz, aplique el operador de acceso a miembros de flecha (->) al identificador.

Importante

Al llamar a una función de interfaz, pruebe siempre el valor devuelto HRESULT.

Activación y uso de un componente de Windows Runtime

En los siguientes pasos se utiliza la interfaz Windows::Foundation::IUriRuntimeClass para demostrar cómo crear un generador de activación para un componente de Windows Runtime, crear una instancia de ese componente y recuperar un valor de propiedad. También se muestra cómo inicializar Windows Runtime. A continuación se muestra el ejemplo completo.

Importante

Aunque normalmente se utiliza la biblioteca de plantillas de Windows Runtime C++ en una aplicación de la Plataforma universal de Windows (UWP), este ejemplo utiliza una aplicación de consola a modo de ilustración. Funciones como wprintf_s no están disponibles en una aplicación para UWP. Para más información sobre los tipos y funciones que puede utilizar en una aplicación para UWP, consulte Funciones de CRT no admitidas en aplicaciones de la Plataforma universal de Windows y Win32 y COM para aplicaciones para UWP.

Para activar y usar un componente de Windows Runtime

Incluya (#include) cualquier encabezado requerido de Windows Runtime, la biblioteca de plantillas de Windows Runtime C++ o la Biblioteca estándar de C++.
```
#include <Windows.Foundation.h>
#include <wrl\wrappers\corewrappers.h>
#include <wrl\client.h>
#include <stdio.h>

using namespace ABI::Windows::Foundation;
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;
```
Se recomienda que use la directiva using namespace en el archivo .cpp para que el código sea más legible.
Inicialice el subproceso en el que se ejecuta la aplicación. Cada aplicación debe inicializar su modelo de subprocesos. En este ejemplo se usa la clase Microsoft::WRL::Wrappers::RoInitializeWrapper para inicializar Windows Runtime y se especifica RO_INIT_MULTITHREADED como modelo de subprocesos. La clase RoInitializeWrapper llama a Windows::Foundation::Initialize en la construcción y a Windows::Foundation::Uninitialize cuando se destruye.
```
// Initialize the Windows Runtime.
RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
if (FAILED(initialize))
{
    return PrintError(__LINE__, initialize);
}
```
En la segunda instrucción, el operador RoInitializeWrapper::HRESULT devuelve HRESULT de la llamada a Windows::Foundation::Initialize.
Cree un generador de activación para la interfaz ABI::Windows::Foundation::IUriRuntimeClassFactory.
```
// Get the activation factory for the IUriRuntimeClass interface.
ComPtr<IUriRuntimeClassFactory> uriFactory;
HRESULT hr = GetActivationFactory(HStringReference(RuntimeClass_Windows_Foundation_Uri).Get(), &uriFactory);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}
```
Windows Runtime usa nombres completos para identificar tipos. El parámetro RuntimeClass_Windows_Foundation_Uri es una cadena proporcionada por Windows Runtime y contiene el nombre de clase del entorno de ejecución necesario.
Inicialice una variable Microsoft::WRL::Wrappers::HString que representa el URI "https://www.microsoft.com".
```
// Create a string that represents a URI.
HString uriHString;
hr = uriHString.Set(L"http://www.microsoft.com");
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}
```
En Windows Runtime, no asignas memoria para una cadena que usará Windows Runtime. En su lugar, Windows Runtime crea una copia de la cadena en un búfer que mantiene y usa para las operaciones y, a continuación, devuelve un identificador al búfer que creó.

Use el elemento IUriRuntimeClassFactory::CreateUri de Factory Method para crear un objeto ABI::Windows::Foundation::IUriRuntimeClass.

// Create the IUriRuntimeClass object.
ComPtr<IUriRuntimeClass> uri;
hr = uriFactory->CreateUri(uriHString.Get(), &uri);
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

Llame al método IUriRuntimeClass::get_Domain para recuperar el valor de la propiedad Domain.

// Get the domain part of the URI.
HString domainName;
hr = uri->get_Domain(domainName.GetAddressOf());
if (FAILED(hr))
{
    return PrintError(__LINE__, hr);
}

Imprima el nombre de dominio en la consola y vuelva. Todos los objetos ComPtr y RAII salen del ámbito y se liberan automáticamente.
```
// Print the domain name and return.
wprintf_s(L"Domain name: %s\n", domainName.GetRawBuffer(nullptr));

// All smart pointers and RAII objects go out of scope here.
```
La función WindowsGetStringRawBuffer recupera la forma Unicode subyacente de la cadena de URI.

A continuación se incluye el ejemplo completo:

// wrl-consume-component.cpp
// compile with: runtimeobject.lib
#include <Windows.Foundation.h>
#include <wrl\wrappers\corewrappers.h>
#include <wrl\client.h>
#include <stdio.h>

using namespace ABI::Windows::Foundation;
using namespace Microsoft::WRL;
using namespace Microsoft::WRL::Wrappers;

// Prints an error string for the provided source code line and HRESULT
// value and returns the HRESULT value as an int.
int PrintError(unsigned int line, HRESULT hr)
{
    wprintf_s(L"ERROR: Line:%d HRESULT: 0x%X\n", line, hr);
    return hr;
}

int wmain()
{
    // Initialize the Windows Runtime.
    RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
    if (FAILED(initialize))
    {
        return PrintError(__LINE__, initialize);
    }

    // Get the activation factory for the IUriRuntimeClass interface.
    ComPtr<IUriRuntimeClassFactory> uriFactory;
    HRESULT hr = GetActivationFactory(HStringReference(RuntimeClass_Windows_Foundation_Uri).Get(), &uriFactory);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Create a string that represents a URI.
    HString uriHString;
    hr = uriHString.Set(L"http://www.microsoft.com");
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Create the IUriRuntimeClass object.
    ComPtr<IUriRuntimeClass> uri;
    hr = uriFactory->CreateUri(uriHString.Get(), &uri);
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Get the domain part of the URI.
    HString domainName;
    hr = uri->get_Domain(domainName.GetAddressOf());
    if (FAILED(hr))
    {
        return PrintError(__LINE__, hr);
    }

    // Print the domain name and return.
    wprintf_s(L"Domain name: %s\n", domainName.GetRawBuffer(nullptr));

    // All smart pointers and RAII objects go out of scope here.
}
/*
Output:
Domain name: microsoft.com
*/

Compilar el código

Para compilar el código, cópielo y péguelo en un proyecto de Visual Studio, o en un archivo denominado wrl-consume-component.cpp. Después, ejecute el comando siguiente en una ventana del símbolo del sistema de Visual Studio.

cl.exe wrl-consume-component.cpp runtimeobject.lib

Consulte también

Biblioteca de plantillas C++ de Windows en tiempo de ejecución (WRL)