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*

指定された IMetaDataDispenserEx::OpenScope メソッドを使用してメタデータ ファイルを開くことができるよう、RoGetMetaDataFile 関数の呼び出し元が必要に応じて渡すことができるメタデータ ディスペンサー。 メタデータ ディスペンサー パラメーターが nullptr に設定されている場合、関数はリファクタリングされたメタデータ リーダー (RoMetadata.dll) の内部インスタンスを作成し、その IMetaDataDispenserEx::OpenScope メソッドを 使用します。 メタデータ ディスペンサーは、 MetaDataGetDispenser 関数を使用して作成できます。

[out, optional] metaDataFilePath

型: HSTRING*

nullptr に設定されていない限り、ABI を記述するメタデータ (.winmd) ファイルの絶対パス。 呼び出し元は、WindowsDeleteString メソッドを呼び出して HSTRING を解放します。

[out, optional] metaDataImport

種類: IMetaDataImport2**

メタデータ ファイル リーダー オブジェクトへのポインター。 呼び出し元が nullptr を渡す場合、関数は IMetaDataImport2 参照を 解放します。それ以外の場合、呼び出し元は参照を解放する必要があります。 エラーが発生した場合、値は nullptr に設定されます。

[out, optional] typeDefToken

型: mdTypeDef*

名前入力文字列が型名として正常に解決された場合、このパラメーターは typename のトークンに設定されます。

失敗した場合、このパラメーターは mdTypeDefNil に設定されます。

戻り値

型: HRESULT

この関数は、これらの値のいずれかを返すことができます。

リターン コード 説明
S_OK
 解決が成功しました。これは、入力文字列が .winmd ファイルで定義されている型を表していることを意味します。
E_INVALIDARG
 入力名文字列の次のプロパティの少なくとも 1 つが保持されていません。
  • null ではない、空ではない
  • 埋め込み null 文字は含まれません。
  • ドット区切りの文字列の場合、最後のドットの左側の部分文字列と最後のドットの右側にある部分文字列は空でない必要があります。
RO_E_METADATA_NAME_NOT_FOUND
 入力文字列は、検査対象の .winmd ファイルで定義された型ではありません。
RO_E_METADATA_NAME_IS_NAMESPACE
 入力文字列は、型名ではなく既存の名前空間です。

注釈

呼び出し元は、必要に応じて RoGetMetaDataFile 関数のメタデータ ディスペンサーを渡して 、IMetaDataDispenserEx::OpenScope メソッドを使用してメタデータ ファイルを開くことができます。

メタデータ ディスペンサー パラメーターが nullptr に設定されている場合、関数はリファクタリングされたメタデータ リーダーの内部インスタンスを作成し、そのリーダーの IMetaDataDispenserEx::OpenScope メソッドを 使用します。

RoGetMetaDataFile 関数は、nullptr をメタデータ ディスペンサー パラメーターに渡すとスレッド セーフであることが保証されます。この関数は内部読み取り専用メタデータ リーダーを作成するためです。 この保証は、RoMetadata などの読み取り専用メタデータ リーダーを関数に渡す場合にも保持されます。

3 つの出力パラメーターはすべて省略可能であり、いずれも指定する必要はありません。 すべての出力パラメーターに対して nullptr を指定して RoGetMetaDataFile 関数を呼び出すことは、入力型名と名前空間のどちらが定義されているかを確認することと同じです。

メタデータ リーダー オブジェクト参照と TypeDef トークン パラメーターがペアになっています。そのため、両方を一緒に設定するか 、nullptr に設定する必要があります。

次の 3 つの型解決シナリオが考えられます。

シナリオ 1 Typename 入力文字列は、WinMD ファイルで定義されている型です。
  • 戻り値

    S_OK

  • メタデータ ファイル パスの出力パラメーター

    これは省略可能な出力パラメーターです。 呼び出し元によって nullptr に設定されていない場合、指定された型の ABI を記述する .winmd ファイルの絶対パスが保持されます。 呼び出し元は、WindowsDeleteString を呼び出して HSTRING を解放する役割を担います。

  • メタデータ リーダー オブジェクト出力パラメーターへの参照

    これは省略可能な出力パラメーターです。 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
ヘッダー rometadataresolution.h
Library WindowsApp.lib
[DLL] WinTypes.dll