RoGetMetaDataFile 함수(rometadataresolution.h)

아티클
08/25/2023

지정된 형식 이름에 대한 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

resolve 이름(typename 또는 네임스페이스)입니다. 이름 입력 문자열은 비어 있지 않아야 하며 포함된 NUL 문자를 포함해서는 안 됩니다. 이름이 점으로 구분된 문자열인 경우 마지막 점의 왼쪽에 있는 부분 문자열과 마지막 점의 오른쪽에 있는 부분 문자열은 비어 있지 않아야 합니다.

[in, optional] metaDataDispenser

형식: IMetaDataDispenserEx*

제공된 IMetaDataDispenserEx::OpenScope 메서드를 통해 메타데이터 파일을 열 수 있도록 호출자가 선택적으로 RoGetMetaDataFile 함수에 전달할 수 있는 메타데이터 디스펜서입니다. 메타데이터 디스펜서 매개 변수가 nullptr로 설정된 경우 함수는 리팩터링된 메타데이터 판독기(RoMetadata.dll)의 내부 instance 만들고 해당 IMetaDataDispenserEx::OpenScope 메서드를 사용합니다. MetaDataGetDispenser 함수를 사용하여 메타데이터 디스펜서를 만들 수 있습니다.

[out, optional] metaDataFilePath

형식: HSTRING*

nullptr로 설정하지 않는 한 ABI를 설명하는 메타데이터(.winmd) 파일의 절대 경로입니다. 호출자는 WindowsDeleteString 메서드를 호출하여 HSTRING을 해제할 책임이 있습니다.

[out, optional] metaDataImport

형식: IMetaDataImport2**

메타데이터 파일 판독기 개체에 대한 포인터입니다. 호출자가 nullptr 를 전달하는 경우 함수는 IMetaDataImport2 참조를 해제합니다. 그렇지 않으면 호출자는 참조를 해제해야 합니다. 값은 실패 시 nullptr 로 설정됩니다.

[out, optional] typeDefToken

형식: mdTypeDef*

이름 입력 문자열이 typename으로 성공적으로 확인되면 이 매개 변수는 typename의 토큰으로 설정됩니다.

실패 시 이 매개 변수는 mdTypeDefNil로 설정됩니다.

반환 값

형식: HRESULT

이 함수는 이러한 값 중 하나를 반환할 수 있습니다.

반환 코드	Description
S_OK	해결에 성공했습니다. 즉, 입력 문자열이 .winmd 파일에 정의된 형식을 나타냅니다.
E_INVALIDARG	입력 이름 문자열의 다음 속성 중 하나 이상이 보유하지 않습니다. null이 아니고 비어 있지 않음 포함된 null 문자를 포함하지 않습니다. 점으로 구분된 문자열인 경우 마지막 점의 왼쪽에 있는 부분 문자열과 마지막 점의 오른쪽에 있는 부분 문자열은 비어 있지 않아야 합니다.
RO_E_METADATA_NAME_NOT_FOUND	입력 문자열은 검사된 .winmd 파일에 정의된 형식이 아닙니다.
RO_E_METADATA_NAME_IS_NAMESPACE	입력 문자열은 typename이 아닌 기존 네임스페이스입니다.

설명

호출자는 필요에 따라 RoGetMetaDataFile 함수에 대한 메타데이터 디스펜서를 전달하여 IMetaDataDispenserEx::OpenScope 메서드를 통해 메타데이터 파일을 열 수 있습니다.

메타데이터 디스펜서 매개 변수가 nullptr로 설정된 경우 함수는 리팩터링된 메타데이터 판독기의 내부 instance 만들고 해당 판독기의 IMetaDataDispenserEx::OpenScope 메서드를 사용합니다.

함수가 내부 읽기 전용 메타데이터 판독기를 만들 때 메타데이터 디스펜서 매개 변수에 nullptr을 전달하는 경우 RoGetMetaDataFile 함수는 스레드로부터 안전합니다. 이 보장은 RoMetadata와 같은 읽기 전용 메타데이터 판독기를 함수에 전달하는 경우에도 유지됩니다.

세 가지 출력 매개 변수는 모두 선택 사항이며 둘 중 어느 것도 지정할 필요가 없습니다. 모든 출력 매개 변수에 대해 nullptr을 사용하여 RoGetMetaDataFile 함수를 호출하는 것은 입력 형식 이름 또는 네임스페이스가 정의되어 있는지 여부를 묻는 것과 같습니다.

메타데이터 판독기 개체 참조 및 TypeDef 토큰 매개 변수가 페어링되므로 둘 다 함께 설정하거나 nullptr로 설정해야 합니다.

가능한 세 가지 형식 확인 시나리오는 다음과 같습니다.

시나리오 #1	Typename 입력 문자열은 WinMD 파일에 정의된 형식입니다. 반환 값 S_OK 메타데이터 파일 경로 출력 매개 변수 선택적 출력 매개 변수입니다. 호출자가 nullptr 로 설정하지 않으면 지정된 형식의 ABI를 설명하는 .winmd 파일의 절대 경로를 보유합니다. 호출자는 WindowsDeleteString을 호출하여 HSTRING을 해제할 책임이 있습니다. 메타데이터 판독기 개체 출력 매개 변수에 대한 참조 선택적 출력 매개 변수입니다. nullptr이 아닌 경우 메타데이터 판독기 개체(IMetaDataImport2)에 대한 참조를 보유하며 호출자는 이를 해제해야 합니다. 호출자가 이 매개 변수에 대해 nullptr 을 전달하면 호출자가 메타데이터 판독기 개체를 원하지 않으므로 함수가 내부 참조를 해제합니다. Typedef 토큰 출력 매개 변수 선택적 출력 매개 변수입니다. 호출자가 nullptr 로 설정하지 않으면 형식의 typedef 항목의 토큰으로 설정됩니다. 언어 프로젝션은 이 토큰을 사용하여 IMetaDataImport::GetTypeDefProps 를 호출하여 형식에 대한 메타데이터를 가져올 수 있습니다.
시나리오 #2	Typename 입력 문자열은 실제로 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
라이브러리	WindowsApp.lib
DLL	WinTypes.dll

RoGetMetaDataFile 함수(rometadataresolution.h)

구문

매개 변수

반환 값

설명

예제

요구 사항

피드백

피드백

추가 리소스