RoGetMetaDataFile function (rometadataresolution.h)
Locates and retrieves the metadata file that describes the Application Binary Interface (ABI) for the specified typename.
Syntax
HRESULT RoGetMetaDataFile(
[in] const HSTRING name,
[in, optional] IMetaDataDispenserEx *metaDataDispenser,
[out, optional] HSTRING *metaDataFilePath,
[out, optional] IMetaDataImport2 **metaDataImport,
[out, optional] mdTypeDef *typeDefToken
);
Parameters
[in] name
Type: const HSTRING
The name to resolve, either a typename or a namespace. The name input string must be non-empty and must not contain embedded NUL characters. If the name is a dot-separated string, then the substring to the left of the last dot and the substring to the right of the last dot must be non-empty.
[in, optional] metaDataDispenser
Type: IMetaDataDispenserEx*
A metadata dispenser that the caller can optionally pass in for the RoGetMetaDataFile function to be able to open the metadata files through the provided IMetaDataDispenserEx::OpenScope method. If the metadata dispenser parameter is set to nullptr, the function creates an internal instance of the refactored metadata reader (RoMetadata.dll) and uses its IMetaDataDispenserEx::OpenScope method. You can create a metadata dispenser using the MetaDataGetDispenser function.
[out, optional] metaDataFilePath
Type: HSTRING*
The absolute path of the metadata (.winmd) file that describes the ABI, unless set to nullptr. The caller is responsible for freeing the HSTRING by calling the WindowsDeleteString method.
[out, optional] metaDataImport
Type: IMetaDataImport2**
A pointer to the metadata file reader object. If the caller passes in a nullptr , the function releases the IMetaDataImport2 reference, otherwise the caller must release the reference. The value is set to nullptr on failure.
[out, optional] typeDefToken
Type: mdTypeDef*
If the name input string is resolved successfully as a typename, this parameter is set to the token of the typename.
On failure, this parameter is set to mdTypeDefNil.
Return value
Type: HRESULT
This function can return one of these values.
| Return code | Description |
|---|---|
|
Resolution was successful, which means that the input string represents a type defined in a .winmd file. |
|
At least one of the following properties of the input name string does not hold:
|
|
The input string is not a type defined in any examined .winmd file. |
|
The input string is an existing namespace rather than a typename. |
Remarks
The caller can optionally pass-in a metadata dispenser for the RoGetMetaDataFile function to open the metadata files through the IMetaDataDispenserEx::OpenScope method.
If the metadata dispenser parameter is set to nullptr, the function creates an internal instance of the refactored metadata reader and uses that reader’s IMetaDataDispenserEx::OpenScope method.
The RoGetMetaDataFile function is guaranteed to be thread-safe if you pass-in nullptr to the metadata dispenser parameter, as the function creates an internal read-only metadata reader. This guarantee also holds if you pass in the read-only metadata reader, like RoMetadata to the function.
All three output parameters are optional and none of them needs to be specified. Calling the RoGetMetaDataFile function with nullptr for all output parameters is equivalent to asking whether the input typename or namespace is defined.
The metadata reader object reference and the TypeDef token parameters paired, so both must be set together or be set to nullptr.
There are three possible type resolution scenarios:
| Scenario #1 |
Typename input string is a type defined in a WinMD file.
|
| Scenario #2 | Typename input string is actually an existing namespace rather than a typename.
|
| Scenario #3 | Input string is not a type defined in any examined WinMD file
|
The RoGetMetaDataFile function resolves an interfacegroup, because the interfacegroup also is a namespace-qualified typename. The IInspectable::GetRuntimeClassName method returns the string in dot-separated string format for use by RoGetMetaDataFile.
Resolving 3rd-party types from a process that's not in a Windows Store app is not supported. In this case, the function returns error HRESULT_FROM_WIN32(ERROR_NO_PACKAGE) and sets output parameters to nullptr. But Windows types are resolved in a process that's not in a Windows Store app.
Examples
The following C++ example shows how to use the RoGetMetaDataFile function to find the metadata file for a specified type name.
#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;
}
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8 [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2012 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | rometadataresolution.h |
| Library | WindowsApp.lib |
| DLL | WinTypes.dll |