RoGetMetaDataFile-Funktion (rometadataresolution.h)

Artikel
08/25/2023

Sucht und ruft die Metadatendatei ab, die die Application Binary Interface (ABI) für den angegebenen Typnamen beschreibt.

Syntax

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

Parameter

[in] name

Typ: const HSTRING

Der aufzulösde Name, entweder ein Typname oder ein Namespace. Die Namenseingabezeichenfolge darf nicht leer sein und darf keine eingebetteten NUL-Zeichen enthalten. Wenn der Name eine durch Punkt getrennte Zeichenfolge ist, muss die Teilzeichenfolge links vom letzten Punkt und die Teilzeichenfolge rechts vom letzten Punkt nicht leer sein.

[in, optional] metaDataDispenser

Typ: IMetaDataDispenserEx*

Ein Metadatenspender, den der Aufrufer optional für die RoGetMetaDataFile-Funktion übergeben kann, um die Metadatendateien über die bereitgestellte IMetaDataDispenserEx::OpenScope-Methode öffnen zu können. Wenn der Parameter des Metadatenspenders auf nullptr festgelegt ist, erstellt die Funktion eine interne instance des umgestalteten Metadatenlesers (RoMetadata.dll) und verwendet die IMetaDataDispenserEx::OpenScope-Methode. Sie können mithilfe der MetaDataGetDispenser-Funktion einen Metadatenspender erstellen.

[out, optional] metaDataFilePath

Typ: HSTRING*

Der absolute Pfad der Metadatendatei (.winmd), die die ABI beschreibt, sofern nicht auf nullptr festgelegt. Der Aufrufer ist für die Freigabe des HSTRING durch Aufrufen der WindowsDeleteString-Methode verantwortlich.

[out, optional] metaDataImport

Typ: IMetaDataImport2**

Ein Zeiger auf das Metadatendateileseobjekt. Wenn der Aufrufer einen Nullptr übergibt, gibt die Funktion den IMetaDataImport2-Verweis frei, andernfalls muss der Aufrufer den Verweis freigeben. Der Wert wird bei Einem Fehler auf NULLptr festgelegt.

[out, optional] typeDefToken

Typ: mdTypeDef*

Wenn die Namenseingabezeichenfolge erfolgreich als Typname aufgelöst wurde, wird dieser Parameter auf das Token des Typnamens festgelegt.

Bei Einem Fehler wird dieser Parameter auf mdTypeDefNil festgelegt.

Rückgabewert

Typ: HRESULT

Diese Funktion kann einen dieser Werte zurückgeben.

Rückgabecode	BESCHREIBUNG
S_OK	Die Lösung war erfolgreich. Dies bedeutet, dass die Eingabezeichenfolge einen Typ darstellt, der in einer WINMD-Datei definiert ist.
E_INVALIDARG	Mindestens eine der folgenden Eigenschaften der Eingabenamenzeichenfolge enthält nicht: Nicht NULL, nicht leer Enthält keine eingebetteten NULL-Zeichen. Bei einer punkttrennten Zeichenfolge müssen die Teilzeichenfolge links vom letzten Punkt und die Teilzeichenfolge rechts vom letzten Punkt nicht leer sein.
RO_E_METADATA_NAME_NOT_FOUND	Die Eingabezeichenfolge ist kein Typ, der in einer überprüften WINMD-Datei definiert ist.
RO_E_METADATA_NAME_IS_NAMESPACE	Die Eingabezeichenfolge ist ein vorhandener Namespace und kein Typname.

Hinweise

Der Aufrufer kann optional einen Metadatenspender für die RoGetMetaDataFile-Funktion übergeben, um die Metadatendateien über die IMetaDataDispenserEx::OpenScope-Methode zu öffnen.

Wenn der Parameter des Metadatenspenders auf nullptr festgelegt ist, erstellt die Funktion eine interne instance des umgestalteten Metadatenlesers und verwendet die IMetaDataDispenserEx::OpenScope-Methode dieses Readers.

Die RoGetMetaDataFile-Funktion ist garantiert threadsicher, wenn Sie nullptr an den Metadatenspenderparameter übergeben, da die Funktion einen internen schreibgeschützten Metadatenleser erstellt. Diese Garantie gilt auch, wenn Sie den schreibgeschützten Metadatenleser wie RoMetadata an die Funktion übergeben.

Alle drei Ausgabeparameter sind optional, und keiner von ihnen muss angegeben werden. Das Aufrufen der RoGetMetaDataFile-Funktion mit nullptr für alle Ausgabeparameter entspricht der Frage, ob der Eingabetypname oder -namespace definiert ist.

Der Metadatenleserobjektverweis und die TypeDef-Tokenparameter sind gekoppelt, sodass beide zusammen oder auf nullptr festgelegt werden müssen.

Es gibt drei mögliche Typauflösungsszenarien:

Szenario Nr. 1	Die Typename-Eingabezeichenfolge ist ein typ, der in einer WinMD-Datei definiert ist. Rückgabewert S_OK Ausgabeparameter des Metadatendateipfads Dies ist ein optionaler Ausgabeparameter. Wenn der Aufrufer nicht auf nullptr festgelegt ist, enthält er den absoluten Pfad der WINMD-Datei, die die ABI des angegebenen Typs beschreibt. Der Aufrufer ist für die Freigabe des HSTRING durch Aufrufen von WindowsDeleteString verantwortlich. Verweis auf den Ausgabeparameter des Metadatenleseobjekts Dies ist ein optionaler Ausgabeparameter. Wenn kein NULLptr vorhanden ist, enthält es einen Verweis auf das Metadatenleseobjekt (IMetaDataImport2), und der Aufrufer ist für die Freigabe verantwortlich. Wenn der Aufrufer nullptr für diesen Parameter übergibt, bedeutet dies, dass der Aufrufer das Metadatenleseobjekt nicht möchte, sodass die Funktion den internen Verweis freigibt. Typedef-Tokenausgabeparameter Dies ist ein optionaler Ausgabeparameter. Wenn der Aufrufer nicht auf nullptr festgelegt ist, wird er auf das Token des typedef-Eintrags des Typs festgelegt. Sprachprojektionen können dieses Token verwenden, um IMetaDataImport::GetTypeDefProps aufzurufen, um Metadaten zum Typ abzurufen.
Szenario Nr. 2	Die Typename-Eingabezeichenfolge ist eigentlich ein vorhandener Namespace und kein Typname. Rückgabewert RO_E_METADATA_NAME_IS_NAMESPACE Ausgabeparameter des Metadatendateipfads Dies ist ein optionaler Ausgabeparameter. Wenn der Aufrufer nicht auf nullptr festgelegt ist, wird er auf nullptr festgelegt. Verweis auf den Ausgabeparameter des Metadatenleseobjekts Dies ist ein optionaler Ausgabeparameter. Wenn der Aufrufer nicht auf nullptr festgelegt ist, wird er auf nullptr festgelegt. Typedef-Tokenausgabeparameter Dies ist ein optionaler Ausgabeparameter. Wenn der Aufrufer nicht auf nullptr festgelegt ist, lautet dies mdTypeDefNil.
Szenario Nr. 3	Die Eingabezeichenfolge ist kein Typ, der in einer überprüften WinMD-Datei definiert ist. Rückgabewert RO_E_METADATA_NAME_NOT_FOUND Ausgabeparameter des Metadatendateipfads Dies ist ein optionaler Ausgabeparameter. Wenn der Aufrufer nicht auf nullptr festgelegt ist, wird er auf nullptr festgelegt. Verweis auf den Ausgabeparameter des Metadatenleseobjekts Dies ist ein optionaler Ausgabeparameter. Wenn der Aufrufer nicht auf nullptr festgelegt ist, wird er auf nullptr festgelegt. Typedef-Tokenausgabeparameter Dies ist ein optionaler Ausgabeparameter. Wenn der Aufrufer nicht auf nullptr festgelegt ist, wird er auf mdTypeDefNil festgelegt.

Die RoGetMetaDataFile-Funktion löst eine Schnittstellengruppe auf, da die Schnittstellengruppe auch ein namespacequalifizierter Typname ist. Die IInspectable::GetRuntimeClassName-Methode gibt die Zeichenfolge im durch Punkt getrennten Zeichenfolgenformat zur Verwendung durch RoGetMetaDataFile zurück.

Das Auflösen von Drittanbietertypen aus einem Prozess, der sich nicht in einer Windows Store-App befindet, wird nicht unterstützt. In diesem Fall gibt die Funktion error HRESULT_FROM_WIN32(ERROR_NO_PACKAGE) zurück und legt ausgabeparameter auf nullptr fest. Windows-Typen werden jedoch in einem Prozess aufgelöst, der sich nicht in einer Windows Store-App befindet.

Beispiele

Im folgenden C++-Beispiel wird gezeigt, wie die RoGetMetaDataFile-Funktion verwendet wird, um die Metadatendatei für einen angegebenen Typnamen zu finden.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2012 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	rometadataresolution.h
Bibliothek	WindowsApp.lib
DLL	WinTypes.dll