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

Статья
08/25/2023

Находит и извлекает файл метаданных, описывающий двоичный интерфейс приложения (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

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

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

Синтаксис

Параметры

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

Комментарии

Примеры

Требования

Обратная связь

Дополнительные ресурсы