Función SxsLookupClrGuid

Recupera el nombre de clase y otra información asociada a un GUID determinado en el manifiesto de un componente. Esta función solo se usa al implementar la interoperabilidad administrada y no administrada de bajo nivel en .NET Framework. Para obtener más información sobre la interoperabilidad no administrada, vea "Interoperating with Unmanaged Code" (Interoperar con código no administrado) en el SDK de .NET Framework y también aplicaciones aisladas y ensamblados en paralelo.

Sintaxis

BOOL SxsLookupClrGuid(
  _In_        DWORD   dwFlags,
  _In_        LPGUID  pClsid,
  _In_opt_    HANDLE  hActCtx,
  _Inout_opt_ PVOID   pvOutputBuffer,
  _In_        SIZE_T  cbOutputBuffer,
  _Out_       PSIZE_T pcbOutputBuffer
);

Parámetros

dwFlags [in]

Combinación de cero o más de las marcas siguientes.

Valor	Significado
SXS_LOOKUP_CLR_GUID_USE_ACTCTX 0x00000001	Si se establece esta marca, el parámetro hActCtx debe contener un identificador de contexto de activación devuelto por la función CreateActCtx . Si no se establece esta marca, se omite el parámetro hActCtx y SxsLookupClrGuid busca en el contexto de activación que está activo actualmente (la función ActivateActCtx se usa para activar un contexto de activación).
SXS_LOOKUP_CLR_GUID_FIND_SURROGATE 0x00010000	Si se establece esta marca, SxsLookupClrGuid busca un suplente.
SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS 0x00020000	Si se establece esta marca, SxsLookupClrGuid busca una clase.
SXS_LOOKUP_CLR_GUID_FIND_ANY 0x00030000	Se trata de una combinación de las marcas SXS_LOOKUP_CLR_GUID_FIND_SURROGATE y SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS ; Si se establecen ambos, SxsLookupClrGuid busca primero un suplente y solo si no encuentra uno, busca una clase.

 

pClsid [in]

Puntero al GUID sobre el que se va a buscar el contexto de activación para obtener información de interoperación. Este parámetro no puede ser NULL.

hActCtx [in, optional]

Si la marca SXS_LOOKUP_CLR_GUID_USE_ACTCTX se establece en el parámetro dwFlags , hActCtx debe contener un identificador de contexto de activación devuelto por la función CreateActCtx . De lo contrario, se omite hActCtx .

pvOutputBuffer [in, out, optional]

Puntero al búfer en el que se copia la información de retorno. Este parámetro solo puede tener valores NULL si el parámetro cbOutputBuffer tiene valores cero. Los datos colocados en este búfer al salir (si existen) constan de una estructura de SXS_GUID_INFORMATION_CLR seguida de los datos de cadena adicionales necesarios. Para obtener más información, vea la sección Comentarios, más adelante.

cbOutputBuffer [in]

Tamaño en bytes del búfer al que apunta el parámetro pvOutputBuffer .

pcbOutputBuffer [out]

Puntero a una variable en la que el tamaño, en bytes, de la información de retorno se coloca al salir. Si el parámetro cbOutputBuffer es cero o si el tamaño del búfer de salida es menor que el tamaño de la información de retorno, SxsLookupClrGuid genera un error y GetLastError devuelve un error de ERROR_INSUFFICIENT_BUFFER. En este caso, use el valor de la variable a la que apunta pcbOutputBuffer para asignar un búfer lo suficientemente grande y, a continuación, llame a SxsLookupClrGuid de nuevo para recuperar la información deseada.

Valor devuelto

Devuelve TRUE si se ejecuta correctamente o FALSE de lo contrario. Para obtener más información de error, llame a GetLastError.

Comentarios

Esta función no tiene ninguna biblioteca de importación o archivo de encabezado asociado; Debe llamarlo mediante las funciones LoadLibrary y GetProcAddress .

Los componentes administrados pueden declararse como compatibles con los "ensamblados de interoperabilidad" administrados para permitir que un consumidor de componentes Win32 no administrado haga referencia al ensamblado declarativo. El consumidor de componentes puede interactuar con el componente administrado llamando a CoCreateInstance en un GUID. La capa de interoperación enruta la solicitud de creación de objetos a .NET Framework, crea una instancia del objeto administrado y devuelve un puntero de interfaz.

SxsLookupClrGuid permite a los marcos recuperar información asociada a un GUID determinado en el manifiesto del componente, como su nombre de clase .NET, qué versión de .NET Framework requiere y en qué ensamblado de host se encuentra. Los componentes administrados publican un ensamblado de interoperabilidad que contiene una serie de instrucciones que asocian GUID con nombres de ensamblado y tipo, y el entorno de ejecución de .NET lleva a cabo la construcción de instancias de objetos administrados cuando se llama a CoCreateInstance .

A continuación se muestra un manifiesto de componente de ejemplo que declara un GUID de CLR y un suplente clR que SxsLookupClrGuid puede buscar:

<assembly manifestVersion="1.0" xmlns=
    "urn:schemas-microsoft-com:asm.v1">
   <assemblyIdentity type="interop" name=
    "DotNet.Sample.Surrogates" version="1.0.0.0"/>
   <clrClass name="MySampleClass" clsid=
    "{19f7f420-4cc5-4b0d-8a82-c24645c0ba1f}"
      progId="MySampleClass.1" runtimeVersion="1.0.3055"/>
   <clrSurrogate name="MySampleSurrogate" clsid=
    "{fdb46ca5-9477-4528-b4b2-7f00a254cdea}"
      runtimeVersion="1.0.3055"/>
</assembly>

Un proveedor de interoperación llamaría a SxsLookupClrGuid con un puntero al GUID "{fdb46ca5-9477-4528-b4b2-7f00a254cdea}", y recibiría en devolución el nombre de clase. "MySampleSurrogate", la versión en tiempo de ejecución necesaria "1.0.3055" y la identidad textual "DotNet.Sample.Surrogates,version='1.0.0.0',type='interop'" del componente de hospedaje.

Esta información de devolución se incluirá o hará referencia a esta información mediante una estructura de SXS_GUID_INFORMATION_CLR declarada como se indica a continuación.

typedef struct _SXS_GUID_INFORMATION_CLR
{
  DWORD   cbSize;
  DWORD   dwFlags;
  PCWSTR  pcwszRuntimeVersion;
  PCWSTR  pcwszTypeName;
  PCWSTR  pcwszAssemblyIdentity;
} SXS_GUID_INFORMATION_CLR, *PSXS_GUID_INFORMATION_CLR;
typedef const SXS_GUID_INFORMATION_CLR *PCSXS_GUID_INFORMATION_CLR;

Los miembros de esta estructura contienen la siguiente información.

Una aplicación no administrada puede usar la información devuelta de esta manera para cargar la versión correcta de .NET Framework, cargar el ensamblado identificado por el elemento pcwszAssemblyIdentity y, a continuación, crear una instancia de la clase denominada por el elemento pcwszTypeName .

Ejemplos

Use la vinculación dinámica como se indica a continuación para llamar a la función SxsLookupClrGuid :

#include <windows.h>

// Declare a type for a SxsLookupClrGuid function pointer:
typedef BOOL (WINAPI* PFN_SXS_LOOKUP_CLR_GUID)
    ( IN DWORD      dwFlags,
    IN LPGUID     pClsid,
    IN HANDLE     hActCtx,
    IN OUT PVOID  pvOutputBuffer,
    IN SIZE_T     cbOutputBuffer,
    OUT PSIZE_T   pcbOutputBuffer );

// Declare an actual function pointer
PFN_SXS_LOOKUP_CLR_GUID pfn_SxsLookupClrGuid;

// Declare a handle for the system DLL
HINSTANCE hSxsDll;

// Other declarations:
BOOL isOK;
GUID exampleGuid = 
{0xFDB46CA5, 0x9477, 0x4528, 0xB4, 0xB2, 
    0x7F, 0x00, 0xA2, 0x54, 0xCD, 0xEA};
#define  OUTPUT_BUFFER_SIZE  512
unsigned char outputBuffer[OUTPUT_BUFFER_SIZE];
SIZE_T neededBufferSize;
DWORD errorCode;

#define SXS_LOOKUP_CLR_GUID_USE_ACTCTX       (0x00000001)
#define SXS_LOOKUP_CLR_GUID_FIND_SURROGATE   (0x00010000)
#define SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS   (0x00020000)
#define SXS_LOOKUP_CLR_GUID_FIND_ANY         (0x00030000) 
    // (SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS | 
    //    SXS_LOOKUP_CLR_GUID_FIND_SURROGATE)

#define SXS_GUID_INFORMATION_CLR_FLAG_IS_SURROGATE  (0x00000001)
#define SXS_GUID_INFORMATION_CLR_FLAG_IS_CLASS      (0x00000002)

typedef struct _SXS_GUID_INFORMATION_CLR
{
    DWORD       cbSize;
    DWORD       dwFlags;
    PCWSTR      pcwszRuntimeVersion;
    PCWSTR      pcwszTypeName;
    PCWSTR      pcwszAssemblyIdentity;
} SXS_GUID_INFORMATION_CLR, *PSXS_GUID_INFORMATION_CLR;
typedef const SXS_GUID_INFORMATION_CLR *PCSXS_GUID_INFORMATION_CLR;

void main()
{
// Use LoadLibrary to obtain a handle to the "SXS.DLL" system library
  hSxsDll = LoadLibrary( "sxs" );

// If SXS.DLL has loaded properly, 
// try to obtain a pointer to SxsLookupClrGuid
  if( hSxsDll != NULL )
  {
    pfn_SxsLookupClrGuid = (PFN_SXS_LOOKUP_CLR_GUID) GetProcAddress(
                            hSxsDll, "SxsLookupClrGuid" );
    if( pfn_SxsLookupClrGuid == NULL )
    {
       // (Handle failure to find SxsLookupClrGuid here...)
    }
    else
    {
      isOK = (pfn_SxsLookupClrGuid)(
                 SXS_LOOKUP_CLR_GUID_FIND_ANY,     // dwFlags
                 &exampleGuid,                     // pClsid
                 NULL,                             // hActCtx
                 (PVOID) outputBuffer,             // pvOutputBuffer
                 (SIZE_T) OUTPUT_BUFFER_SIZE,      // cbOutputBuffer
                 &neededBufferSize );              // pcbOutputBuffer
      if( isOK == FALSE )
      {
        errorCode = GetLastError( );
        if( errorCode == ERROR_INSUFFICIENT_BUFFER )
        {
          // If the allocation fails because the buffer was too small,
          // allocate a larger output buffer, of the size 
          // now indicated by "neededBufferSize", and try again.
        }
        else
        {
          // Handle other errors here
        }
      }
      else
      {
        // (Use the information here...)
      }
    }
    // Free the library instance when you're done
    FreeLibrary( hSxsDll );
  }
}

Requisitos

Consulte también

Aplicaciones aisladas y ensamblados en paralelo

CreateActCtx

ActivateActCtx

Cocreateinstance