Funzione RoGetMetaDataFile (rometadataresolution.h)

Articolo
08/25/2023

Individua e recupera il file di metadati che descrive l'interfaccia ABI (Application Binary Interface) per il nometipo specificato.

Sintassi

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

Parametri

[in] name

Tipo: const HSTRING

Nome da risolvere, nometipo o spazio dei nomi. La stringa di input del nome deve essere non vuota e non deve contenere caratteri NUL incorporati. Se il nome è una stringa separata da punti, la sottostringa a sinistra dell'ultimo punto e la sottostringa a destra dell'ultimo punto deve essere non vuota.

[in, optional] metaDataDispenser

Tipo: IMetaDataDispenserEx*

Distributore di metadati che il chiamante può facoltativamente passare per la funzione RoGetMetaDataFile per poter aprire i file di metadati tramite il metodo IMetaDataDispenserEx::OpenScope specificato. Se il parametro del distributore di metadati è impostato su nullptr, la funzione crea un'istanza interna del lettore di metadati di refactoring (RoMetadata.dll) e usa il relativo metodo IMetaDataDispenserEx::OpenScope . È possibile creare un distributore di metadati usando la funzione MetaDataGetDispenser .

[out, optional] metaDataFilePath

Tipo: HSTRING*

Percorso assoluto del file di metadati (con estensione winmd) che descrive l'ABI, a meno che non sia impostato su nullptr. Il chiamante è responsabile della liberazione di HSTRING chiamando il metodo WindowsDeleteString .

[out, optional] metaDataImport

Tipo: IMetaDataImport2**

Puntatore all'oggetto lettore di file di metadati. Se il chiamante passa un nullptr , la funzione rilascia il riferimento IMetaDataImport2 ; in caso contrario, il chiamante deve rilasciare il riferimento. Il valore è impostato su nullptr in caso di errore.

[out, optional] typeDefToken

Tipo: mdTypeDef*

Se la stringa di input del nome viene risolta correttamente come nometipo, questo parametro viene impostato sul token del nometipo.

In caso di errore, questo parametro è impostato su mdTypeDefNil.

Valore restituito

Tipo: HRESULT

Questa funzione può restituire uno di questi valori.

Codice restituito	Descrizione
S_OK	La risoluzione ha avuto esito positivo, il che significa che la stringa di input rappresenta un tipo definito in un file con estensione winmd.
E_INVALIDARG	Almeno una delle proprietà seguenti della stringa del nome di input non contiene: Non null, non vuoto Non contiene caratteri Null incorporati. Se una stringa separata da punti, la sottostringa a sinistra dell'ultimo punto e la sottostringa a destra dell'ultimo punto devono essere non vuote.
RO_E_METADATA_NAME_NOT_FOUND	La stringa di input non è un tipo definito in alcun file con estensione winmd esaminato.
RO_E_METADATA_NAME_IS_NAMESPACE	La stringa di input è uno spazio dei nomi esistente anziché un nometipo.

Commenti

Il chiamante può facoltativamente passare un distributore di metadati per la funzione RoGetMetaDataFile per aprire i file di metadati tramite il metodo IMetaDataDispenserEx::OpenScope .

Se il parametro del distributore di metadati è impostato su nullptr, la funzione crea un'istanza interna del lettore di metadati di refactoring e usa il metodo IMetaDataDispenserEx::OpenScope del lettore.

La funzione RoGetMetaDataFile è garantita come thread-safe se si passa nullptr al parametro del distributore di metadati, poiché la funzione crea un lettore di metadati di sola lettura interno. Questa garanzia vale anche se si passa il lettore di metadati di sola lettura, ad esempio RoMetadata alla funzione.

Tutti e tre i parametri di output sono facoltativi e nessuno di essi deve essere specificato. La chiamata alla funzione RoGetMetaDataFile con nullptr per tutti i parametri di output equivale a chiedere se è definito il nometipo o lo spazio dei nomi di input.

Riferimento all'oggetto lettore di metadati e parametri del token TypeDef associati, pertanto entrambi devono essere impostati insieme o essere impostati su nullptr.

Esistono tre possibili scenari di risoluzione dei tipi:

Scenario 1	La stringa di input Typename è un tipo definito in un file WinMD. Valore restituito S_OK Parametro di output del percorso del file di metadati Si tratta di un parametro di output facoltativo. Se non è impostato su nullptr dal chiamante, contiene il percorso assoluto del file con estensione winmd che descrive l'ABI del tipo specificato. Il chiamante è responsabile della liberazione di HSTRING chiamando WindowsDeleteString. Riferimento al parametro di output dell'oggetto lettore di metadati Si tratta di un parametro di output facoltativo. Se non nullptr, contiene un riferimento all'oggetto lettore di metadati (IMetaDataImport2) e il chiamante è responsabile del rilascio. Se il chiamante passa nullptr per questo parametro, significa che il chiamante non vuole l'oggetto lettore di metadati, quindi la funzione rilascia il riferimento interno. Parametro di output del token Typedef Si tratta di un parametro di output facoltativo. Se non è impostato su nullptr dal chiamante, viene impostato sul token della voce typedef del tipo. Le proiezioni del linguaggio possono usare questo token per chiamare IMetaDataImport::GetTypeDefProps per ottenere metadati sul tipo.
Scenario 2 #	La stringa di input typename è in realtà uno spazio dei nomi esistente anziché un nometipo. Valore restituito RO_E_METADATA_NAME_IS_NAMESPACE Parametro di output del percorso del file di metadati Si tratta di un parametro di output facoltativo. Se non è impostato su nullptr dal chiamante, viene impostato su nullptr. Riferimento al parametro di output dell'oggetto lettore di metadati Si tratta di un parametro di output facoltativo. Se non è impostato su nullptr dal chiamante, viene impostato su nullptr. Parametro di output del token Typedef Si tratta di un parametro di output facoltativo. Se non è impostato su nullptr dal chiamante, verrà impostato su mdTypeDefNil.
Scenario 3 #	La stringa di input non è un tipo definito in alcun file WinMD esaminato Valore restituito RO_E_METADATA_NAME_NOT_FOUND Parametro di output del percorso del file di metadati Si tratta di un parametro di output facoltativo. Se non è impostato su nullptr dal chiamante, viene impostato su nullptr Riferimento al parametro di output dell'oggetto lettore di metadati Si tratta di un parametro di output facoltativo. Se non è impostato su nullptr dal chiamante, viene impostato su nullptr Parametro di output del token Typedef Si tratta di un parametro di output facoltativo. Se non è impostato su nullptr dal chiamante, viene impostato su mdTypeDefNil.

La funzione RoGetMetaDataFile risolve un interfacegroup, perché il interfacegroup è anche un typename completo dello spazio dei nomi. Il metodo IInspectable::GetRuntimeClassName restituisce la stringa in formato stringa delimitata da punti da utilizzare da RoGetMetaDataFile.

La risoluzione dei tipi di terze parti da un processo non incluso in un'app di Windows Store non è supportata. In questo caso, la funzione restituisce l'errore HRESULT_FROM_WIN32(ERROR_NO_PACKAGE) e imposta i parametri di output su nullptr. Ma i tipi di Windows vengono risolti in un processo che non si trova in un'app di Windows Store.

Esempio

L'esempio C++ seguente illustra come usare la funzione RoGetMetaDataFile per trovare il file di metadati per un nome di tipo specificato.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2012 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	rometadataresolution.h
Libreria	WindowsApp.lib
DLL	WinTypes.dll

Condividi tramite