Поделиться через

Функция RoGetMetaDataFile (rometadataresolution.h)

  • Статья

Находит и извлекает файл метаданных, описывающий двоичный интерфейс приложения (ABI) для указанного имени типа.

Синтаксис

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

Параметры

[in] name

Тип: const HSTRING

Имя, необходимое для разрешения, имя типа или пространство имен. Входная строка имени должна быть непустой и не должна содержать внедренные символы NUL. Если имя является строкой, разделенной точками, подстрока слева от последней точки и подстрока справа от последней точки должны быть непустой.

[in, optional] metaDataDispenser

Тип: IMetaDataDispenserEx*

Диспенсер метаданных, который вызывающий объект может при необходимости передать для функции RoGetMetaDataFile , чтобы иметь возможность открывать файлы метаданных с помощью предоставленного метода IMetaDataDispenserEx::OpenScope . Если параметру диспенсера метаданных присвоено значение nullptr, функция создает внутренний экземпляр средства чтения метаданных с рефакторингом (RoMetadata.dll) и использует его метод IMetaDataDispenserEx::OpenScope . Вы можете создать диспенсер метаданных с помощью функции MetaDataGetDispenser .

[out, optional] metaDataFilePath

Тип: HSTRING*

Абсолютный путь к файлу метаданных (WINMD), который описывает ABI, если не задано значение nullptr. Вызывающий объект отвечает за освобождение HSTRING путем вызова метода WindowsDeleteString .

[out, optional] metaDataImport

Тип: IMetaDataImport2**

Указатель на объект средства чтения файла метаданных. Если вызывающий объект передает значение nullptr , функция освобождает ссылку IMetaDataImport2 , в противном случае вызывающий объект должен освободить ссылку. При сбое задано значение nullptr .

[out, optional] typeDefToken

Тип: mdTypeDef*

Если входная строка имени успешно разрешается как имя типа, для этого параметра устанавливается токен имени типа.

В случае сбоя этому параметру присваивается значение mdTypeDefNil.

Возвращаемое значение

Тип: HRESULT

Эта функция может возвращать одно из этих значений.

Код возврата Описание
S_OK
 Разрешение выполнено успешно. Это означает, что входная строка представляет тип, определенный в WINMD-файле.
E_INVALIDARG
 По крайней мере одно из следующих свойств входной строки имени не содержит:
  • Не нулевая, не пустая
  • Не содержит внедренных символов NULL.
  • Если строка разделена точками, подстрока слева от последней точки и подстрока справа от последней точки должны быть непустой.
RO_E_METADATA_NAME_NOT_FOUND
 Входная строка не является типом, определенным в любом проверенном WINMD-файле.
RO_E_METADATA_NAME_IS_NAMESPACE
 Входная строка — это существующее пространство имен, а не имя типа.

Комментарии

Вызывающий объект может при необходимости передать диспенсер метаданных для функции RoGetMetaDataFile , чтобы открыть файлы метаданных с помощью метода IMetaDataDispenserEx::OpenScope .

Если параметру диспенсера метаданных присвоено значение nullptr, функция создает внутренний экземпляр средства чтения метаданных с рефакторингом и использует метод IMetaDataDispenserEx::OpenScope этого средства чтения.

Функция RoGetMetaDataFile гарантированно будет потокобезопасной, если передать nullptr в параметр диспенсера метаданных, так как функция создает внутреннее средство чтения метаданных только для чтения. Эта гарантия также сохраняется при передаче в функцию средства чтения метаданных только для чтения, например RoMetadata.

Все три выходных параметра являются необязательными, и ни один из них не должен быть указан. Вызов функции RoGetMetaDataFile с nullptr для всех выходных параметров эквивалентен запросу о том, определено ли имя входного типа или пространство имен.

Ссылка на объект средства чтения метаданных и параметры токена TypeDef связаны, поэтому оба объекта должны быть установлены вместе или иметь значение nullptr.

Существует три возможных сценария разрешения типов:

Сценарий 1 Входная строка typename — это тип, определенный в файле WinMD.
  • Возвращаемое значение

    S_OK

  • Выходной параметр пути к файлу метаданных

    Это необязательный выходной параметр. Если вызывающий объект не имеет значение nullptr , он содержит абсолютный путь к WINMD-файлу, который описывает ABI данного типа. Вызывающий объект отвечает за освобождение HSTRING путем вызова WindowsDeleteString.

  • Ссылка на выходной параметр объекта средства чтения метаданных

    Это необязательный выходной параметр. Если значение nullptr не равно nullptr, оно содержит ссылку на объект средства чтения метаданных (IMetaDataImport2), и вызывающий объект отвечает за его освобождение. Если вызывающий объект передает значение nullptr для этого параметра, это означает, что вызывающему объекту не нужен объект чтения метаданных, поэтому функция освобождает внутреннюю ссылку.

  • Выходной параметр токена Typedef

    Это необязательный выходной параметр. Если вызывающий объект не имеет значение nullptr , ему присваивается токен записи typedef типа. Проекции языка могут использовать этот маркер для вызова IMetaDataImport::GetTypeDefProps для получения метаданных о типе.
Сценарий 2 Входная строка typename фактически является существующим пространством имен, а не именем типа.
  • Возвращаемое значение

    RO_E_METADATA_NAME_IS_NAMESPACE

  • Выходной параметр пути к файлу метаданных

    Это необязательный выходной параметр. Если вызывающий объект не имеет значение nullptr , ему присваивается значение nullptr.

  • Ссылка на выходной параметр объекта средства чтения метаданных

    Это необязательный выходной параметр. Если вызывающий объект не имеет значение nullptr , ему присваивается значение nullptr.

  • Выходной параметр токена Typedef

    Это необязательный выходной параметр. Если вызывающий объект не имеет значение nullptr , он будет иметь значение mdTypeDefNil.
Сценарий 3 Входная строка не является типом, определенным в любом проверенном файле WinMD.
  • Возвращаемое значение

    RO_E_METADATA_NAME_NOT_FOUND

  • Выходной параметр пути к файлу метаданных

    Это необязательный выходной параметр. Если вызывающий объект не имеет значение nullptr, ему присваивается значение nullptr.

  • Ссылка на выходной параметр объекта средства чтения метаданных

    Это необязательный выходной параметр. Если вызывающий объект не имеет значение nullptr, ему присваивается значение nullptr.

  • Выходной параметр токена Typedef

    Это необязательный выходной параметр. Если для вызывающего объекта не задано значение nullptr , ему присваивается значение mdTypeDefNil.
 

Функция RoGetMetaDataFile разрешает группу интерфейсов, так как она также является именем типа с указанием пространства имен. Метод IInspectable::GetRuntimeClassName возвращает строку в формате строки с разделительной точкой для использования в RoGetMetaDataFile.

Разрешение сторонних типов из процесса, который отсутствует в приложении Магазина Windows, не поддерживается. В этом случае функция возвращает ошибку HRESULT_FROM_WIN32(ERROR_NO_PACKAGE) и задает для выходных параметров значение nullptr. Но типы Windows разрешаются в процессе, который не находится в приложении Магазина Windows.

Примеры

В следующем примере C++ показано, как использовать функцию RoGetMetaDataFile для поиска файла метаданных для указанного имени типа.

#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;
}

Требования

Требование Значение
Минимальная версия клиента Windows 8 [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2012 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header rometadataresolution.h
Библиотека WindowsApp.lib
DLL WinTypes.dll