Función RoGetMetaDataFile (rometadataresolution.h)

Artículo
08/25/2023

Busca y recupera el archivo de metadatos que describe la interfaz binaria de la aplicación (ABI) para el nombre de tipo especificado.

Sintaxis

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

Parámetros

[in] name

Tipo: const HSTRING

Nombre que se va a resolver, ya sea un nombre de tipo o un espacio de nombres. La cadena de entrada de nombre debe no estar vacía y no debe contener caracteres NUL incrustados. Si el nombre es una cadena separada por puntos, la subcadena a la izquierda del último punto y la subcadena a la derecha del último punto debe no estar vacía.

[in, optional] metaDataDispenser

Tipo: IMetaDataDispenserEx*

Un dispensador de metadatos que el autor de la llamada puede pasar opcionalmente para que la función RoGetMetaDataFile pueda abrir los archivos de metadatos a través del método IMetaDataDispenserEx::OpenScope proporcionado. Si el parámetro dispensador de metadatos se establece en nullptr, la función crea una instancia interna del lector de metadatos refactorizado (RoMetadata.dll) y usa su método IMetaDataDispenserEx::OpenScope . Puede crear un dispensador de metadatos mediante la función MetaDataGetDispenser .

[out, optional] metaDataFilePath

Tipo: HSTRING*

Ruta de acceso absoluta del archivo de metadatos (.winmd) que describe la ABI, a menos que se establezca en nullptr. El autor de la llamada es responsable de liberar el HSTRING mediante una llamada al método WindowsDeleteString .

[out, optional] metaDataImport

Tipo: IMetaDataImport2**

Puntero al objeto de lector de archivos de metadatos. Si el autor de la llamada pasa un nullptr , la función libera la referencia IMetaDataImport2 ; de lo contrario, el autor de la llamada debe liberar la referencia. El valor se establece en nullptr en error.

[out, optional] typeDefToken

Tipo: mdTypeDef*

Si la cadena de entrada del nombre se resuelve correctamente como typename, este parámetro se establece en el token del typename.

Si se produce un error, este parámetro se establece en mdTypeDefNil.

Valor devuelto

Tipo: HRESULT

Esta función puede devolver uno de estos valores.

Código devuelto	Descripción
S_OK	La resolución se realizó correctamente, lo que significa que la cadena de entrada representa un tipo definido en un archivo .winmd.
E_INVALIDARG	Al menos una de las siguientes propiedades de la cadena de nombre de entrada no contiene: No es NULL, no está vacío No contiene caracteres NULL incrustados. Si una cadena separada por puntos, la subcadena a la izquierda del último punto y la subcadena a la derecha del último punto debe no estar vacía.
RO_E_METADATA_NAME_NOT_FOUND	La cadena de entrada no es un tipo definido en ningún archivo .winmd examinado.
RO_E_METADATA_NAME_IS_NAMESPACE	La cadena de entrada es un espacio de nombres existente en lugar de un nombre de tipo.

Comentarios

Opcionalmente, el autor de la llamada puede pasar un dispensador de metadatos para la función RoGetMetaDataFile para abrir los archivos de metadatos a través del método IMetaDataDispenserEx::OpenScope .

Si el parámetro dispensador de metadatos se establece en nullptr, la función crea una instancia interna del lector de metadatos refactorizado y usa el método IMetaDataDispenserEx::OpenScope del lector.

Se garantiza que la función RoGetMetaDataFile es segura para subprocesos si pasa nullptr al parámetro del dispensador de metadatos, ya que la función crea un lector de metadatos de solo lectura interno. Esta garantía también se mantiene si pasa el lector de metadatos de solo lectura, como RoMetadata a la función.

Los tres parámetros de salida son opcionales y no es necesario especificar ninguno de ellos. Llamar a la función RoGetMetaDataFile con nullptr para todos los parámetros de salida equivale a preguntar si se define el nombre de tipo de entrada o el espacio de nombres.

La referencia del objeto lector de metadatos y los parámetros del token TypeDef emparejados, por lo que ambos deben establecerse juntos o establecerse en nullptr.

Hay tres posibles escenarios de resolución de tipos:

Escenario 1	La cadena de entrada Typename es un tipo definido en un archivo WinMD. Valor devuelto S_OK Parámetro de salida de ruta de acceso del archivo de metadatos Se trata de un parámetro de salida opcional. Si no se establece en nullptr por llamador , contiene la ruta de acceso absoluta del archivo .winmd que describe la ABI del tipo especificado. El autor de la llamada es responsable de liberar el HSTRING mediante una llamada a WindowsDeleteString. Referencia al parámetro de salida del objeto lector de metadatos Se trata de un parámetro de salida opcional. Si no es nullptr, contiene una referencia al objeto lector de metadatos (IMetaDataImport2) y el autor de la llamada es responsable de liberarlo. Si el autor de la llamada pasa nullptr para este parámetro, significa que el autor de la llamada no quiere el objeto lector de metadatos, por lo que la función libera la referencia interna. Parámetro de salida del token typedef Se trata de un parámetro de salida opcional. Si no se establece en nullptr por llamador , se establece en el token de la entrada typedef del tipo. Las proyecciones de lenguaje pueden usar este token para llamar a IMetaDataImport::GetTypeDefProps para obtener metadatos sobre el tipo.
Escenario 2	La cadena de entrada Typename es realmente un espacio de nombres existente en lugar de un nombre de tipo. Valor devuelto RO_E_METADATA_NAME_IS_NAMESPACE Parámetro de salida de ruta de acceso del archivo de metadatos Se trata de un parámetro de salida opcional. Si no se establece en nullptr por el autor de la llamada, se establece en nullptr. Referencia al parámetro de salida del objeto lector de metadatos Se trata de un parámetro de salida opcional. Si no se establece en nullptr por llamador, se establece en nullptr. Parámetro de salida del token typedef Se trata de un parámetro de salida opcional. Si no se establece en nullptr por llamador, será mdTypeDefNil.
Escenario 3	La cadena de entrada no es un tipo definido en ningún archivo WinMD examinado Valor devuelto RO_E_METADATA_NAME_NOT_FOUND Parámetro de salida de ruta de acceso del archivo de metadatos Se trata de un parámetro de salida opcional. Si no se establece en nullptr por llamador, se establece en nullptr. Referencia al parámetro de salida del objeto lector de metadatos Se trata de un parámetro de salida opcional. Si no se establece en nullptr por llamador, se establece en nullptr. Parámetro de salida del token typedef Se trata de un parámetro de salida opcional. Si no se establece en nullptr por llamador, se establece en mdTypeDefNil.

La función RoGetMetaDataFile resuelve un grupo de interfaz, porque el grupo de interfaces también es un typename calificado por el espacio de nombres. El método IInspectable::GetRuntimeClassName devuelve la cadena en formato de cadena separada por puntos para su uso por RoGetMetaDataFile.

No se admite la resolución de tipos de terceros desde un proceso que no está en una aplicación de la Tienda Windows. En este caso, la función devuelve el error HRESULT_FROM_WIN32(ERROR_NO_PACKAGE) y establece los parámetros de salida en nullptr. Pero los tipos de Windows se resuelven en un proceso que no está en una aplicación de la Tienda Windows.

Ejemplos

En el siguiente ejemplo de C++ se muestra cómo usar la función RoGetMetaDataFile para buscar el archivo de metadatos de un nombre de tipo especificado.

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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8 [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2012 [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	rometadataresolution.h
Library	WindowsApp.lib
Archivo DLL	WinTypes.dll

Compartir a través de

Función RoGetMetaDataFile (rometadataresolution.h)

Sintaxis

Parámetros

Valor devuelto

Comentarios

Ejemplos

Requisitos

Comentarios

Recursos adicionales