ホーム › System.WinRT.Metadata › RoGetMetaDataFile

RoGetMetaDataFile

関数

指定した型名のWinRTメタデータファイルを検索し取得する。

DLLapi-ms-win-ro-typeresolution-l1-1-0.dll呼出規約winapi対応OSwindows8.0

シグネチャ

// api-ms-win-ro-typeresolution-l1-1-0.dll
#include <windows.h>

HRESULT RoGetMetaDataFile(
    HSTRING name,
    IMetaDataDispenserEx* metaDataDispenser,   // optional
    HSTRING* metaDataFilePath,   // optional
    IMetaDataImport2** metaDataImport,   // optional
    DWORD* typeDefToken   // optional
);

パラメーター

名前	型	方向	説明
name	HSTRING	in	解決する名前。型名または名前空間を指定します。name の入力文字列は空であってはならず、埋め込みの NUL 文字を含んでいてはなりません。名前がドット区切りの文字列である場合、最後のドットの左側の部分文字列と右側の部分文字列は、いずれも空であってはなりません。
metaDataDispenser	IMetaDataDispenserEx*	inoptional	RoGetMetaDataFile 関数が、指定された IMetaDataDispenserEx::OpenScope メソッドを通じてメタデータファイルを開けるようにするために、呼び出し元が任意で渡すことができるメタデータディスペンサー。メタデータディスペンサーのパラメーターに nullptr を設定した場合、この関数はリファクタリングされたメタデータリーダー (RoMetadata.dll) の内部インスタンスを作成し、その IMetaDataDispenserEx::OpenScope メソッドを使用します。メタデータディスペンサーは MetaDataGetDispenser 関数を使用して作成できます。
metaDataFilePath	HSTRING*	outoptional	nullptr に設定されている場合を除き、ABI を記述するメタデータ (.winmd) ファイルの絶対パス。呼び出し元は、WindowsDeleteString メソッドを呼び出して HSTRING を解放する責任があります。
metaDataImport	IMetaDataImport2**	outoptional	メタデータファイルリーダーオブジェクトへのポインター。呼び出し元が nullptr を渡した場合、この関数は IMetaDataImport2 の参照を解放します。それ以外の場合は、呼び出し元が参照を解放する必要があります。失敗した場合、この値は nullptr に設定されます。
typeDefToken	DWORD*	outoptional	name の入力文字列が型名として正常に解決された場合、このパラメーターにはその型名のトークンが設定されます。失敗した場合、このパラメーターには mdTypeDefNil が設定されます。

戻り値の型: HRESULT

公式ドキュメント

指定された型名のアプリケーションバイナリインターフェイス (ABI) を記述するメタデータファイルを検索して取得します。

戻り値

型: HRESULT

この関数は次のいずれかの値を返すことがあります。

戻り値	説明
S_OK	解決に成功しました。これは、入力文字列が .winmd ファイルで定義されている型を表していることを意味します。
E_INVALIDARG	入力された name 文字列について、次の条件の少なくとも 1 つが満たされていません。 null でなく、空でもないこと埋め込みの null 文字を含まないこと。ドット区切りの文字列である場合、最後のドットの左側の部分文字列と右側の部分文字列がいずれも空でないこと。
RO_E_METADATA_NAME_NOT_FOUND	入力文字列は、調査対象のいずれの .winmd ファイルでも定義されていない型です。
RO_E_METADATA_NAME_IS_NAMESPACE	入力文字列は型名ではなく、既存の名前空間です。

解説(Remarks)

呼び出し元は、RoGetMetaDataFile 関数が IMetaDataDispenserEx::OpenScope メソッドを通じてメタデータファイルを開けるように、メタデータディスペンサーを任意で渡すことができます。

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

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

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

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

型の解決には次の 3 つのシナリオがあります。

シナリオ #1	型名の入力文字列が、WinMD ファイルで定義されている型である場合。戻り値 S_OK メタデータファイルパスの出力パラメーターこれは省略可能な出力パラメーターです。呼び出し元が nullptr を設定していない場合、指定された型の ABI を記述する .winmd ファイルの絶対パスが格納されます。呼び出し元は WindowsDeleteString を呼び出して HSTRING を解放する責任があります。メタデータリーダーオブジェクトへの参照の出力パラメーターこれは省略可能な出力パラメーターです。nullptr でない場合、メタデータリーダーオブジェクト (IMetaDataImport2) への参照が格納され、呼び出し元がそれを解放する責任があります。呼び出し元がこのパラメーターに nullptr を渡した場合は、メタデータリーダーオブジェクトを必要としないことを意味するため、この関数は内部の参照を解放します。 Typedef トークンの出力パラメーターこれは省略可能な出力パラメーターです。呼び出し元が nullptr を設定していない場合、その型の typedef エントリのトークンが設定されます。言語プロジェクションはこのトークンを使用して IMetaDataImport::GetTypeDefProps を呼び出し、その型に関するメタデータを取得できます。
シナリオ #2	型名の入力文字列が、実際には型名ではなく既存の名前空間である場合。戻り値 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 関数は interfacegroup も解決します。interfacegroup も名前空間で修飾された型名であるためです。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);
    }

    // リソースをクリーンアップします。
    if (hstrTypeName != nullptr)
    {
        WindowsDeleteString(hstrTypeName);
    }

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

    return hr;
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// api-ms-win-ro-typeresolution-l1-1-0.dll
#include <windows.h>

HRESULT RoGetMetaDataFile(
    HSTRING name,
    IMetaDataDispenserEx* metaDataDispenser,   // optional
    HSTRING* metaDataFilePath,   // optional
    IMetaDataImport2** metaDataImport,   // optional
    DWORD* typeDefToken   // optional
);

[DllImport("api-ms-win-ro-typeresolution-l1-1-0.dll", ExactSpelling = true)]
static extern int RoGetMetaDataFile(
    IntPtr name,   // HSTRING
    IntPtr metaDataDispenser,   // IMetaDataDispenserEx* optional
    IntPtr metaDataFilePath,   // HSTRING* optional, out
    IntPtr metaDataImport,   // IMetaDataImport2** optional, out
    IntPtr typeDefToken   // DWORD* optional, out
);

<DllImport("api-ms-win-ro-typeresolution-l1-1-0.dll", ExactSpelling:=True)>
Public Shared Function RoGetMetaDataFile(
    name As IntPtr,   ' HSTRING
    metaDataDispenser As IntPtr,   ' IMetaDataDispenserEx* optional
    metaDataFilePath As IntPtr,   ' HSTRING* optional, out
    metaDataImport As IntPtr,   ' IMetaDataImport2** optional, out
    typeDefToken As IntPtr   ' DWORD* optional, out
) As Integer
End Function

' name : HSTRING
' metaDataDispenser : IMetaDataDispenserEx* optional
' metaDataFilePath : HSTRING* optional, out
' metaDataImport : IMetaDataImport2** optional, out
' typeDefToken : DWORD* optional, out
Declare PtrSafe Function RoGetMetaDataFile Lib "api-ms-win-ro-typeresolution-l1-1-0" ( _
    ByVal name As LongPtr, _
    ByVal metaDataDispenser As LongPtr, _
    ByVal metaDataFilePath As LongPtr, _
    ByVal metaDataImport As LongPtr, _
    ByVal typeDefToken As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

RoGetMetaDataFile = ctypes.windll.LoadLibrary("api-ms-win-ro-typeresolution-l1-1-0.dll").RoGetMetaDataFile
RoGetMetaDataFile.restype = ctypes.c_int
RoGetMetaDataFile.argtypes = [
    wintypes.HANDLE,  # name : HSTRING
    ctypes.c_void_p,  # metaDataDispenser : IMetaDataDispenserEx* optional
    ctypes.c_void_p,  # metaDataFilePath : HSTRING* optional, out
    ctypes.c_void_p,  # metaDataImport : IMetaDataImport2** optional, out
    ctypes.POINTER(wintypes.DWORD),  # typeDefToken : DWORD* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('api-ms-win-ro-typeresolution-l1-1-0.dll')
RoGetMetaDataFile = Fiddle::Function.new(
  lib['RoGetMetaDataFile'],
  [
    Fiddle::TYPE_VOIDP,  # name : HSTRING
    Fiddle::TYPE_VOIDP,  # metaDataDispenser : IMetaDataDispenserEx* optional
    Fiddle::TYPE_VOIDP,  # metaDataFilePath : HSTRING* optional, out
    Fiddle::TYPE_VOIDP,  # metaDataImport : IMetaDataImport2** optional, out
    Fiddle::TYPE_VOIDP,  # typeDefToken : DWORD* optional, out
  ],
  Fiddle::TYPE_INT)

#[link(name = "api-ms-win-ro-typeresolution-l1-1-0")]
extern "system" {
    fn RoGetMetaDataFile(
        name: *mut core::ffi::c_void,  // HSTRING
        metaDataDispenser: *mut core::ffi::c_void,  // IMetaDataDispenserEx* optional
        metaDataFilePath: *mut *mut core::ffi::c_void,  // HSTRING* optional, out
        metaDataImport: *mut *mut core::ffi::c_void,  // IMetaDataImport2** optional, out
        typeDefToken: *mut u32  // DWORD* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("api-ms-win-ro-typeresolution-l1-1-0.dll")]
public static extern int RoGetMetaDataFile(IntPtr name, IntPtr metaDataDispenser, IntPtr metaDataFilePath, IntPtr metaDataImport, IntPtr typeDefToken);
"@
$api = Add-Type -MemberDefinition $sig -Name 'api-ms-win-ro-typeresolution-l1-1-0_RoGetMetaDataFile' -Namespace Win32 -PassThru
# $api::RoGetMetaDataFile(name, metaDataDispenser, metaDataFilePath, metaDataImport, typeDefToken)

#uselib "api-ms-win-ro-typeresolution-l1-1-0.dll"
#func global RoGetMetaDataFile "RoGetMetaDataFile" sptr, sptr, sptr, sptr, sptr
; RoGetMetaDataFile name, metaDataDispenser, metaDataFilePath, metaDataImport, varptr(typeDefToken)   ; 戻り値は stat
; name : HSTRING -> "sptr"
; metaDataDispenser : IMetaDataDispenserEx* optional -> "sptr"
; metaDataFilePath : HSTRING* optional, out -> "sptr"
; metaDataImport : IMetaDataImport2** optional, out -> "sptr"
; typeDefToken : DWORD* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "api-ms-win-ro-typeresolution-l1-1-0.dll"
#cfunc global RoGetMetaDataFile "RoGetMetaDataFile" sptr, sptr, sptr, sptr, var
; res = RoGetMetaDataFile(name, metaDataDispenser, metaDataFilePath, metaDataImport, typeDefToken)
; name : HSTRING -> "sptr"
; metaDataDispenser : IMetaDataDispenserEx* optional -> "sptr"
; metaDataFilePath : HSTRING* optional, out -> "sptr"
; metaDataImport : IMetaDataImport2** optional, out -> "sptr"
; typeDefToken : DWORD* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "api-ms-win-ro-typeresolution-l1-1-0.dll"
#cfunc global RoGetMetaDataFile "RoGetMetaDataFile" sptr, sptr, sptr, sptr, sptr
; res = RoGetMetaDataFile(name, metaDataDispenser, metaDataFilePath, metaDataImport, varptr(typeDefToken))
; name : HSTRING -> "sptr"
; metaDataDispenser : IMetaDataDispenserEx* optional -> "sptr"
; metaDataFilePath : HSTRING* optional, out -> "sptr"
; metaDataImport : IMetaDataImport2** optional, out -> "sptr"
; typeDefToken : DWORD* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。