Função RoGetMetaDataFile (rometadataresolution.h)

Localiza e recupera o arquivo de metadados que descreve a ABI (Interface Binária de Aplicativo) para o nome de tipo especificado.

Sintaxe

HRESULT RoGetMetaDataFile(
  [in]            const HSTRING        name,
  [in, optional]  IMetaDataDispenserEx *metaDataDispenser,
  [out, optional] HSTRING              *metaDataFilePath,
  [out, optional] IMetaDataImport2     **metaDataImport,
  [out, optional] mdTypeDef            *typeDefToken
);

Parâmetros

[in] name

Tipo: const HSTRING

O nome a resolve, um nome de tipo ou um namespace. A cadeia de caracteres de entrada de nome deve ser não vazia e não deve conter caracteres NUL inseridos. Se o nome for uma cadeia de caracteres separada por ponto, a subcadeia de caracteres à esquerda do último ponto e a subcadeia de caracteres à direita do último ponto deverão não estar vazias.

[in, optional] metaDataDispenser

Tipo: IMetaDataDispenserEx*

Um distribuidor de metadados que o chamador pode, opcionalmente, passar para a função RoGetMetaDataFile para poder abrir os arquivos de metadados por meio do método IMetaDataDispenserEx::OpenScope fornecido. Se o parâmetro do distribuidor de metadados for definido como nullptr, a função criará uma instância interna do leitor de metadados refatorado (RoMetadata.dll) e usará seu método IMetaDataDispenserEx::OpenScope . Você pode criar um distribuidor de metadados usando a função MetaDataGetDispenser .

[out, optional] metaDataFilePath

Tipo: HSTRING*

O caminho absoluto do arquivo de metadados (.winmd) que descreve a ABI, a menos que definido como nullptr. O chamador é responsável por liberar o HSTRING chamando o método WindowsDeleteString .

[out, optional] metaDataImport

Tipo: IMetaDataImport2**

Um ponteiro para o objeto de leitor de arquivo de metadados. Se o chamador passar em um nullptr , a função liberará a referência IMetaDataImport2 , caso contrário, o chamador deverá liberar a referência. O valor é definido como nullptr em caso de falha.

[out, optional] typeDefToken

Tipo: mdTypeDef*

Se a cadeia de caracteres de entrada de nome for resolvida com êxito como um typename, esse parâmetro será definido como o token do typename.

Em caso de falha, esse parâmetro é definido como mdTypeDefNil.

Retornar valor

Tipo: HRESULT

Essa função pode retornar um desses valores.

Código de retorno	Descrição
S_OK	A resolução foi bem-sucedida, o que significa que a cadeia de caracteres de entrada representa um tipo definido em um arquivo .winmd.
E_INVALIDARG	Pelo menos uma das seguintes propriedades da cadeia de caracteres de nome de entrada não contém: Não nulo, não vazio Não contém caracteres nulos inseridos. Se uma cadeia de caracteres separada por ponto, a subcadeia de caracteres à esquerda do último ponto e a subcadeia de caracteres à direita do último ponto deverão não estar vazias.
RO_E_METADATA_NAME_NOT_FOUND	A cadeia de caracteres de entrada não é um tipo definido em nenhum arquivo .winmd examinado.
RO_E_METADATA_NAME_IS_NAMESPACE	A cadeia de caracteres de entrada é um namespace existente em vez de um typename.

Comentários

Opcionalmente, o chamador pode passar um distribuidor de metadados para a função RoGetMetaDataFile para abrir os arquivos de metadados por meio do método IMetaDataDispenserEx::OpenScope .

Se o parâmetro do distribuidor de metadados for definido como nullptr, a função criará uma instância interna do leitor de metadados refatorado e usará o método IMetaDataDispenserEx::OpenScope desse leitor.

A função RoGetMetaDataFile tem a garantia de ser thread-safe se você passar nullptr para o parâmetro de distribuidor de metadados, pois a função cria um leitor de metadados somente leitura interno. Essa garantia também será mantida se você passar o leitor de metadados somente leitura, como RoMetadata para a função.

Todos os três parâmetros de saída são opcionais e nenhum deles precisa ser especificado. Chamar a função RoGetMetaDataFile com nullptr para todos os parâmetros de saída é equivalente a perguntar se o typename ou o namespace de entrada está definido.

A referência do objeto leitor de metadados e os parâmetros de token TypeDef emparelhados, portanto, ambos devem ser definidos juntos ou definidos como nullptr.

Há três cenários de resolução de tipos possíveis:

Cenário 1	A cadeia de caracteres de entrada typename é um tipo definido em um arquivo WinMD. Valor Retornado S_OK Parâmetro de saída do caminho do arquivo de metadados Esse é um parâmetro de saída opcional. Se não for definido como nullptr pelo chamador , ele conterá o caminho absoluto do arquivo .winmd que descreve a ABI do tipo fornecido. O chamador é responsável por liberar o HSTRING chamando WindowsDeleteString. Referência ao parâmetro de saída do objeto leitor de metadados Esse é um parâmetro de saída opcional. Se não for nullptr, ele conterá uma referência ao objeto de leitor de metadados (IMetaDataImport2) e o chamador será responsável por liberá-lo. Se o chamador passar nullptr para esse parâmetro, isso significa que o chamador não deseja o objeto de leitor de metadados, portanto, a função libera a referência interna. Parâmetro de saída do token Typedef Esse é um parâmetro de saída opcional. Se não for definido como nullptr pelo chamador , ele será definido como o token da entrada typedef do tipo. As projeções de linguagem podem usar esse token para chamar IMetaDataImport::GetTypeDefProps para obter metadados sobre o tipo.
Cenário 2	A cadeia de caracteres de entrada typename é, na verdade, um namespace existente em vez de um nome de tipo. Retornar valor RO_E_METADATA_NAME_IS_NAMESPACE Parâmetro de saída do caminho do arquivo de metadados Esse é um parâmetro de saída opcional. Se não for definido como nullptr pelo chamador , ele será definido como nullptr. Referência ao parâmetro de saída do objeto leitor de metadados Esse é um parâmetro de saída opcional. Se não for definido como nullptr pelo chamador , ele será definido como nullptr. Parâmetro de saída do token Typedef Esse é um parâmetro de saída opcional. Se não for definido como nullptr pelo chamador , será para mdTypeDefNil.
Cenário 3	A cadeia de caracteres de entrada não é um tipo definido em nenhum arquivo WinMD examinado Retornar valor RO_E_METADATA_NAME_NOT_FOUND Parâmetro de saída do caminho do arquivo de metadados Esse é um parâmetro de saída opcional. Se não estiver definido como nullptr pelo chamador , ele será definido como nullptr Referência ao parâmetro de saída do objeto leitor de metadados Esse é um parâmetro de saída opcional. Se não estiver definido como nullptr pelo chamador , ele será definido como nullptr Parâmetro de saída do token Typedef Esse é um parâmetro de saída opcional. Se não for definido como nullptr pelo chamador , ele será definido como mdTypeDefNil.

 

A função RoGetMetaDataFile resolve um grupo de interfaces, pois o grupo de interfaces também é um nome de tipo qualificado por namespace. O método IInspectable::GetRuntimeClassName retorna a cadeia de caracteres no formato de cadeia de caracteres separada por ponto para uso por RoGetMetaDataFile.

Não há suporte para resolver tipos de terceiros de um processo que não está em um aplicativo da Windows Store. Nesse caso, a função retorna erro HRESULT_FROM_WIN32(ERROR_NO_PACKAGE) e define parâmetros de saída como nullptr. Mas os tipos do Windows são resolvidos em um processo que não está em um aplicativo da Windows Store.

Exemplos

O exemplo C++ a seguir mostra como usar a função RoGetMetaDataFile para localizar o arquivo de metadados para um nome de tipo especificado.

#include <windows.h>
#include <stdio.h>
#include <WinRTString.h>
#include <TypeResolution.h>
#include <atlbase.h>

HRESULT PrintMetaDataFilePathForTypeName(PCWSTR pszTypename);

int ShowUsage()
{
    wprintf(L"Usage: RoGetMetaDataFileSample TypeName\n");
    return -1;
}

int __cdecl wmain(int argc, WCHAR **argv)
{
    if (argc != 2)
    {
        return ShowUsage();
    }

    HRESULT hr = PrintMetaDataFilePathForTypeName(argv[1]);

    if (SUCCEEDED(hr))
    {
        return 0;
    }
    else
    {
        return -1;
    }
}

HRESULT PrintMetaDataFilePathForTypeName(PCWSTR pszTypename)
{
    HRESULT hr;
    HSTRING hstrTypeName = nullptr;
    HSTRING hstrMetaDataFilePath = nullptr;
    CComPtr<IMetaDataImport2> spMetaDataImport;
    mdTypeDef typeDef;

    hr = WindowsCreateString(
        pszTypename,
        static_cast<UINT32>(wcslen(pszTypename)),
        &hstrTypeName);

    if (SUCCEEDED(hr))
    {
        hr = RoGetMetaDataFile(
            hstrTypeName,
            nullptr,
            &hstrMetaDataFilePath,
            &spMetaDataImport,
            &typeDef);
    }

    if (SUCCEEDED(hr))
    {
        wprintf(L"Type %s was found in %s\n", pszTypename,  WindowsGetStringRawBuffer(hstrMetaDataFilePath, nullptr));
    }
    else if (hr == RO_E_METADATA_NAME_NOT_FOUND)
    {
        wprintf(L"Type %s was not found!\n", pszTypename);
    }
    else
    {
        wprintf(L"Error %x occurred while trying to resolve %s!\n", hr, pszTypename);
    }

    // Clean up resources.
    if (hstrTypeName != nullptr)
    {
        WindowsDeleteString(hstrTypeName);
    }

    if (hstrMetaDataFilePath != nullptr)
    {
        WindowsDeleteString(hstrMetaDataFilePath);
    }

    return hr;
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	rometadataresolution.h
Biblioteca	WindowsApp.lib
DLL	WinTypes.dll