SxsLookupClrGuid-Funktion

Ruft den Klassennamen und andere Informationen ab, die einer bestimmten GUID im Manifest einer Komponente zugeordnet sind. Diese Funktion wird nur verwendet, wenn auf niedriger Ebene verwaltete nicht verwaltete Interoperabilität im .NET Framework implementiert wird. Weitere Informationen zur verwalteten und nicht verwalteten Interoperabilität finden Sie unter "Interoperating with Unmanaged Code" (Interoperating with Unmanaged Code) im .NET Framework SDK sowie unter Isolierte Anwendungen und parallele Assemblys.

Syntax

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

Parameter

dwFlags [in]

Eine Kombination aus null oder mehr der folgenden Flags.

Wert	Bedeutung
SXS_LOOKUP_CLR_GUID_USE_ACTCTX 0x00000001	Wenn dieses Flag festgelegt ist, muss der hActCtx-Parameter ein Aktivierungskontexthandle enthalten, das von der CreateActCtx-Funktion zurückgegeben wird. Wenn dieses Flag nicht festgelegt ist, wird der hActCtx-Parameter ignoriert, und SxsLookupClrGuid durchsucht den derzeit aktiven Aktivierungskontext (die ActivateActCtx-Funktion wird verwendet, um einen Aktivierungskontext aktiv zu machen).
SXS_LOOKUP_CLR_GUID_FIND_SURROGATE 0x00010000	Wenn dieses Flag festgelegt ist, sucht SxsLookupClrGuid nach einem Ersatz.
SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS 0x00020000	Wenn dieses Flag festgelegt ist, sucht SxsLookupClrGuid nach einer Klasse.
SXS_LOOKUP_CLR_GUID_FIND_ANY 0x00030000	Dies ist eine Kombination aus SXS_LOOKUP_CLR_GUID_FIND_SURROGATE und SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS Flags. wenn beide festgelegt sind, sucht SxsLookupClrGuid zuerst nach einem Ersatz, und nur wenn es keins findet, sucht SxsLookupClrGuid nach einer Klasse.

 

pClsid [in]

Ein Zeiger auf die GUID, über die der Aktivierungskontext nach Interoperationsinformationen gesucht werden soll. Dieser Parameter darf nicht NULL sein.

hActCtx [in, optional]

Wenn das SXS_LOOKUP_CLR_GUID_USE_ACTCTX-Flag im dwFlags-Parameter festgelegt ist, muss hActCtx ein Aktivierungskontexthandle enthalten, das von der CreateActCtx-Funktion zurückgegeben wird. Andernfalls wird hActCtx ignoriert.

pvOutputBuffer [in, out, optional]

Zeiger auf den Puffer, in den zurückgegebene Informationen kopiert werden. Dieser Parameter kann nur nullwertig sein, wenn der cbOutputBuffer-Parameter nullwertig ist. Die Daten, die beim Beenden (sofern vorhanden) in diesem Puffer platziert werden, bestehen aus einer SXS_GUID_INFORMATION_CLR-Struktur gefolgt von allen erforderlichen zusätzlichen Zeichenfolgendaten. Weitere Informationen finden Sie im Abschnitt Hinweise unten.

cbOutputBuffer [in]

Größe in Bytes des Puffers, auf den der parameter pvOutputBuffer verweist.

pcbOutputBuffer [out]

Zeiger auf eine Variable, bei der die Größe der Rückgabeinformationen in Bytes beim Beenden platziert wird. Wenn der cbOutputBuffer-Parameter 0 ist oder die Größe des Ausgabepuffers kleiner als die Größe der Rückgabeinformationen ist, schlägt SxsLookupClrGuid fehl, und GetLastError gibt den Fehler ERROR_INSUFFICIENT_BUFFER zurück. Verwenden Sie in diesem Fall den Wert in der Variablen, auf die von pcbOutputBuffer verwiesen wird, um einen ausreichend großen Puffer zuzuweisen, und rufen Sie dann SxsLookupClrGuid erneut auf, um die gewünschten Informationen abzurufen.

Rückgabewert

Gibt TRUE zurück, wenn der Vorgang erfolgreich war, oder andernfalls FALSE . Rufen Sie GetLastError auf, um weitere Fehlerinformationen zu erhalten.

Bemerkungen

Diese Funktion verfügt über keine zugeordnete Importbibliothek oder Headerdatei. Sie müssen es mit den Funktionen LoadLibrary und GetProcAddress aufrufen.

Verwaltete Komponenten können sich selbst als Unterstützung für verwaltete "Interopassemblys" deklarieren, damit ein nicht verwalteter Win32-Komponenten-Consumer auf die deklarierende Assembly verweisen kann. Der Komponenten-Consumer kann mit der verwalteten Komponente interagieren, indem er CoCreateInstance auf einer GUID aufruft. Die Interoperationsebene leitet die Objekterstellungsanforderung an .NET Framework weiter, erstellt eine instance des verwalteten Objekts und gibt einen Schnittstellenzeiger zurück.

SxsLookupClrGuid ermöglicht es den Frameworks, Informationen abzurufen, die einer bestimmten GUID im Manifest der Komponente zugeordnet sind, z. B. der Name der .NET-Klasse, welche Version der .NET Framework benötigt wird und in welcher Hostassembly sie sich befindet. Verwaltete Komponenten veröffentlichen eine Interopassembly, die eine Reihe von Anweisungen enthält, die GUIDs mit Assembly- und Typnamen zuordnen, und die .NET-Runtime vermittelt die Konstruktion verwalteter Objektinstanzen, wenn CoCreateInstance aufgerufen wird.

Im Folgenden finden Sie ein Beispiel für ein Komponentenmanifest, das eine CLR-GUID und einen CLR-Ersatz deklariert, nach dem SxsLookupClrGuid suchen kann:

<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>

Ein Interoperationsanbieter ruft SxsLookupClrGuid mit einem Zeiger auf die GUID "{fdb46ca5-9477-4528-b4b2-7f00a254cdea}" auf. und erhält im Gegenzug den Klassennamen "MySampleSurrogate", die erforderliche Laufzeitversion "1.0.3055" und die Textidentität "DotNet.Sample.Surrogates,version='1.0.0.0',type='interop'" der Hostingkomponente.

Diese Rückgabeinformationen würden von einer wie folgt deklarierten SXS_GUID_INFORMATION_CLR-Struktur enthalten und/oder referenziert.

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;

Die Member dieser Struktur enthalten die folgenden Informationen.

Eine nicht verwaltete Anwendung kann die auf diese Weise zurückgegebenen Informationen verwenden, um die richtige Version des .NET Framework zu laden, die assembly zu laden, die durch das pcwszAssemblyIdentity-Element identifiziert wurde, und dann eine instance der Klasse mit dem Namen des pcwszTypeName-Elements zu erstellen.

Beispiele

Verwenden Sie die dynamische Verknüpfung wie folgt, um die SxsLookupClrGuid-Funktion aufzurufen:

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

Anforderungen

Siehe auch

Isolierte Anwendungen und parallele Assemblys

CreateActCtx

ActivateActCtx

Cocreateinstance