Fungsi RoGetMetaDataFile (rometadataresolution.h)

  • Artikel

Menemukan dan mengambil file metadata yang menjelaskan Antarmuka Biner Aplikasi (ABI) untuk nama jenis yang ditentukan.

Sintaks

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

Jenis: const HSTRING

Nama yang akan diatasi, baik typename atau namespace. String input nama harus tidak kosong dan tidak boleh berisi karakter NUL yang disematkan. Jika nama adalah string yang dipisahkan titik, maka substring di sebelah kiri titik terakhir dan substring di sebelah kanan titik terakhir harus tidak kosong.

[in, optional] metaDataDispenser

Jenis: IMetaDataDispenserEx*

Dispenser metadata yang dapat diteruskan secara opsional oleh pemanggil untuk fungsi RoGetMetaDataFile agar dapat membuka file metadata melalui metode IMetaDataDispenserEx::OpenScope yang disediakan. Jika parameter dispenser metadata diatur ke nullptr, fungsi membuat instans internal pembaca metadata yang direfaktor (RoMetadata.dll) dan menggunakan metode IMetaDataDispenserEx::OpenScope . Anda dapat membuat dispenser metadata menggunakan fungsi MetaDataGetDispenser .

[out, optional] metaDataFilePath

Jenis: HSTRING*

Jalur absolut file metadata (.winmd) yang menjelaskan ABI, kecuali diatur ke nullptr. Pemanggil bertanggung jawab untuk membebaskan HSTRING dengan memanggil metode WindowsDeleteString .

[out, optional] metaDataImport

Jenis: IMetaDataImport2**

Penunjuk ke objek pembaca file metadata. Jika penelepon melewati nullptr , fungsi merilis referensi IMetaDataImport2 , jika tidak, pemanggil harus merilis referensi. Nilai diatur ke nullptr pada kegagalan.

[out, optional] typeDefToken

Jenis: mdTypeDef*

Jika string input nama berhasil diselesaikan sebagai typename, parameter ini diatur ke token typename.

Jika gagal, parameter ini diatur ke mdTypeDefNil.

Menampilkan nilai

Jenis: HRESULT

Fungsi ini dapat mengembalikan salah satu nilai ini.

Menampilkan kode Deskripsi
S_OK
 Resolusi berhasil, yang berarti bahwa string input mewakili jenis yang ditentukan dalam file .winmd.
E_INVALIDARG
 Setidaknya salah satu properti berikut dari string nama input tidak menahan:
  • Tidak null, tidak kosong
  • Tidak berisi karakter null yang disematkan.
  • Jika string yang dipisahkan titik, substring di sebelah kiri titik terakhir dan substring di sebelah kanan titik terakhir harus tidak kosong.
RO_E_METADATA_NAME_NOT_FOUND
 String input bukan jenis yang ditentukan dalam file .winmd yang diperiksa.
RO_E_METADATA_NAME_IS_NAMESPACE
 String input adalah namespace yang ada daripada typename.

Keterangan

Pemanggil dapat secara opsional meneruskan dispenser metadata untuk fungsi RoGetMetaDataFile untuk membuka file metadata melalui metode IMetaDataDispenserEx::OpenScope .

Jika parameter dispenser metadata diatur ke nullptr, fungsi membuat instans internal pembaca metadata yang direfaktor dan menggunakan metode IMetaDataDispenserEx::OpenScope pembaca tersebut.

Fungsi RoGetMetaDataFile dijamin aman untuk alur jika Anda meneruskan nullptr ke parameter dispenser metadata, karena fungsi membuat pembaca metadata baca-saja internal. Jaminan ini juga berlaku jika Anda meneruskan pembaca metadata baca-saja, seperti RoMetadata ke fungsi.

Ketiga parameter output bersifat opsional dan tidak ada yang perlu ditentukan. Memanggil fungsi RoGetMetaDataFile dengan nullptr untuk semua parameter output setara dengan menanyakan apakah nama jenis input atau namespace didefinisikan.

Referensi objek pembaca metadata dan parameter token TypeDef dipasangkan, sehingga keduanya harus diatur bersama-sama atau diatur ke nullptr.

Ada tiga skenario resolusi jenis yang mungkin:

Skenario #1 String input typename adalah jenis yang ditentukan dalam file WinMD.
  • Tampilkan Nilai

    S_OK

  • Parameter output jalur file metadata

    Ini adalah parameter output opsional. Jika tidak diatur ke nullptr oleh pemanggil, ia memegang jalur absolut file .winmd yang menjelaskan ABI jenis yang diberikan. Pemanggil bertanggung jawab untuk membebaskan HSTRING dengan memanggil WindowsDeleteString.

  • Referensi ke parameter output objek pembaca metadata

    Ini adalah parameter output opsional. Jika bukan nullptr, ia memegang referensi ke objek pembaca metadata (IMetaDataImport2) dan pemanggil bertanggung jawab untuk merilisnya. Jika penelepon melewati nullptr untuk parameter ini, itu berarti bahwa pemanggil tidak menginginkan objek pembaca metadata, sehingga fungsi merilis referensi internal.

  • Parameter output token typedef

    Ini adalah parameter output opsional. Jika tidak diatur ke nullptr oleh pemanggil, itu diatur ke token entri typedef jenis. Proyeksi bahasa dapat menggunakan token ini untuk memanggil IMetaDataImport::GetTypeDefProps untuk mendapatkan metadata tentang jenisnya.
Skenario #2 String input typename sebenarnya adalah namespace yang ada daripada typename.
  • Nilai kembali

    RO_E_METADATA_NAME_IS_NAMESPACE

  • Parameter output jalur file metadata

    Ini adalah parameter output opsional. Jika tidak diatur ke nullptr oleh pemanggil, itu diatur ke nullptr.

  • Referensi ke parameter output objek pembaca metadata

    Ini adalah parameter output opsional. Jika tidak diatur ke nullptr oleh pemanggil, maka diatur ke nullptr.

  • Parameter output token typedef

    Ini adalah parameter output opsional. Jika tidak diatur ke nullptr oleh pemanggil, itu akan menjadi mdTypeDefNil.
Skenario #3 String input bukan jenis yang ditentukan dalam file WinMD yang diperiksa
  • Mengembalikan nilai

    RO_E_METADATA_NAME_NOT_FOUND

  • Parameter output jalur file metadata

    Ini adalah parameter output opsional. Jika tidak diatur ke nullptr oleh pemanggil, maka diatur ke nullptr

  • Referensi ke parameter output objek pembaca metadata

    Ini adalah parameter output opsional. Jika tidak diatur ke nullptr oleh pemanggil, maka diatur ke nullptr

  • Parameter output token typedef

    Ini adalah parameter output opsional. Jika tidak diatur ke nullptr oleh pemanggil, itu diatur ke mdTypeDefNil.
 

Fungsi RoGetMetaDataFile menyelesaikan grup antarmuka, karena grup antarmuka juga merupakan nama jenis yang memenuhi syarat namespace. Metode IInspectable::GetRuntimeClassName mengembalikan string dalam format string yang dipisahkan titik untuk digunakan oleh RoGetMetaDataFile.

Mengatasi jenis pihak ketiga dari proses yang tidak ada di aplikasi Bursa Windows tidak didukung. Dalam hal ini, fungsi mengembalikan kesalahan HRESULT_FROM_WIN32(ERROR_NO_PACKAGE) dan mengatur parameter output ke nullptr. Tetapi jenis Windows diselesaikan dalam proses yang tidak ada di aplikasi Bursa Windows.

Contoh

Contoh C++ berikut menunjukkan cara menggunakan fungsi RoGetMetaDataFile untuk menemukan file metadata untuk nama jenis tertentu.

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

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 8 [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2012 [aplikasi desktop | Aplikasi UWP]
Target Platform Windows
Header rometadataresolution.h
Pustaka WindowsApp.lib
DLL WinTypes.dll