Como ativar e usar um componente do Windows Runtime usando a WRL

Artigo
10/12/2023

Este documento mostra como usar a WRL (Biblioteca de Modelos de Windows Runtime C++) para inicializar o Windows Runtime e como ativar e usar um componente Windows Runtime.

Para usar um componente, você deve adquirir um ponteiro de interface para o tipo implementado pelo componente. E como a tecnologia subjacente do Windows Runtime é o COM (Component Object Model), você deve seguir as regras COM para manter uma instância do tipo. Por exemplo, você deve manter a contagem de referência que determina quando o tipo é excluído da memória.

Para simplificar o uso do Windows Runtime, Windows Runtime Biblioteca de Modelos C++ fornece o modelo de ponteiro inteligente, ComPtr<T>, que executa automaticamente a contagem de referências. Ao declarar uma variável, especifique ComPtr<o identificador de nome> de interface. Para acessar um membro de interface, aplique o operador de acesso de membro de seta (->) ao identificador.

Importante

Sempre que chamar uma função de interface, sempre teste o valor de retorno HRESULT.

Ativando e usando um componente Windows Runtime

As etapas a seguir usam a interface Windows::Foundation::IUriRuntimeClass para demonstrar como criar uma fábrica de ativação para um componente Windows Runtime, criar uma instância desse componente e recuperar um valor de propriedade. Elas também mostram como inicializar o Windows Runtime. O exemplo completo é mostrado a seguir.

Importante

Embora você normalmente use a Biblioteca de Modelos C++ do Windows Runtime em um aplicativo da Plataforma Universal do Windows (UWP), este exemplo usa um aplicativo de console para ilustração. Funções como wprintf_s não estão disponíveis em um aplicativo UWP. Para obter mais informações sobre os tipos e funções que você pode usar em um aplicativo UWP, confira Funções de CRT sem suporte em aplicativos da Plataforma Universal do Windows e Win32 e COM para aplicativos UWP.

Para ativar e usar um componente Windows Runtime

Inclua (#include) qualquer Windows Runtime, Biblioteca de Modelos C++ do Windows Runtime ou cabeçalhos da Biblioteca Padrão C++ exigido.
```
#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;
```
Recomendamos que você utilize a diretiva using namespace em seu arquivo .cpp para tornar o código mais legível.
Inicialize o thread no qual o aplicativo é executado. Cada aplicativo deve inicializar seu thread e modelo de threading. Este exemplo usa a classe Microsoft::WRL::Wrappers::RoInitializeWrapper para inicializar o Windows Runtime e especifica RO_INIT_MULTITHREADED como o modelo de threading. A classe RoInitializeWrapper chama Windows::Foundation::Initialize na construção e Windows::Foundation::Uninitialize quando é destruída.
```
// Initialize the Windows Runtime.
RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
if (FAILED(initialize))
{
    return PrintError(__LINE__, initialize);
}
```
Na segunda instrução, o operador RoInitializeWrapper::HRESULT retorna a HRESULT da chamada para Windows::Foundation::Initialize.
Crie uma fábrica de ativação para a interface 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);
}
```
O Windows Runtime usa nomes totalmente qualificados para identificar tipos. O parâmetro RuntimeClass_Windows_Foundation_Uri é uma cadeia de caracteres fornecida pelo Windows Runtime e contém o nome da classe de runtime necessário.
Inicialize uma variável Microsoft::WRL::Wrappers::HString que representa o 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);
}
```
No Tempo de Execução do Windows, você não aloca memória para uma cadeia de caracteres que o Tempo de Execução do Windows usará. Em vez disso, o Windows Runtime cria uma cópia da cadeia de caracteres em um buffer que ele mantém e usa para operações e, em seguida, retorna um identificador para o buffer que ele criou.

Use o método de fábrica IUriRuntimeClassFactory::CreateUri para criar um 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);
}

Chame o método IUriRuntimeClass::get_Domain para recuperar o valor da propriedade Domain.

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

Imprima o nome de domínio no console e retorne. Todos os ComPtr e objetos RAII deixam o escopo e são liberados automaticamente.
```
// 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.
```
A função WindowsGetStringRawBuffer recupera a forma Unicode subjacente da cadeia de caracteres URI.

Veja o exemplo 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
*/

Compilando o código

Para compilar o código, copie-o e cole-o em um projeto do Visual Studio, ou cole-o em um arquivo chamado wrl-consume-component.cpp e execute o seguinte comando em uma janela do Prompt de comando do Visual Studio.

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

Confira também

WRL (Biblioteca de Modelos C++ do Tempo de Execução do Windows)

Partilhar via

Como ativar e usar um componente do Windows Runtime usando a WRL

Ativando e usando um componente Windows Runtime

Para ativar e usar um componente Windows Runtime

Compilando o código

Confira também

Comentários

Recursos adicionais