Fungsi SxsLookupClrGuid

Mengambil nama kelas dan informasi lain yang terkait dengan GUID tertentu dalam manifes komponen. Fungsi ini hanya digunakan saat menerapkan interoperabilitas tidak terkelola tingkat rendah dalam .NET Framework. Untuk informasi selengkapnya tentang interoperabilitas terkelola yang tidak dikelola, lihat "Beroperasi dengan Kode Tidak Terkelola" di SDK .NET Framework dan juga Aplikasi Terisolasi dan Rakitan Berdampingan.

Sintaks

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]

Kombinasi nol atau lebih dari bendera berikut.

Nilai	Makna
SXS_LOOKUP_CLR_GUID_USE_ACTCTX 0x00000001	Jika bendera ini diatur, parameter hActCtx harus berisi handel konteks aktivasi yang dikembalikan oleh fungsi CreateActCtx . Jika bendera ini tidak diatur, parameter hActCtx diabaikan dan SxsLookupClrGuid mencari konteks aktivasi yang saat ini aktif (fungsi ActivateActCtx digunakan untuk membuat konteks aktivasi aktif).
SXS_LOOKUP_CLR_GUID_FIND_SURROGATE 0x00010000	Jika bendera ini diatur, SxsLookupClrGuid mencari pengganti.
SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS 0x00020000	Jika bendera ini diatur, SxsLookupClrGuid mencari kelas.
SXS_LOOKUP_CLR_GUID_FIND_ANY 0x00030000	Ini adalah kombinasi dari bendera SXS_LOOKUP_CLR_GUID_FIND_SURROGATE dan SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS ; jika keduanya diatur, SxsLookupClrGuid mencari pengganti terlebih dahulu, dan hanya jika tidak menemukannya, maka cari kelas.

 

pClsid [in]

Penunjuk ke GUID untuk mencari konteks aktivasi untuk informasi interoperabilitas. Parameter ini tidak boleh NULL.

hActCtx [in, opsional]

Jika bendera SXS_LOOKUP_CLR_GUID_USE_ACTCTX diatur dalam parameter dwFlags , maka hActCtx harus berisi handel konteks aktivasi yang dikembalikan oleh fungsi CreateActCtx . Jika tidak, hActCtx diabaikan.

pvOutputBuffer [masuk, keluar, opsional]

Penunjuk ke buffer tempat informasi pengembalian disalin. Parameter ini mungkin bernilai NULL hanya jika parameter cbOutputBuffer bernilai nol. Data yang ditempatkan dalam buffer ini saat keluar (jika ada) terdiri dari struktur SXS_GUID_INFORMATION_CLR diikuti oleh data string tambahan yang diperlukan. Lihat bagian Keterangan di bawah ini untuk informasi selengkapnya.

cbOutputBuffer [in]

Ukuran dalam byte buffer yang diacu oleh parameter pvOutputBuffer .

pcbOutputBuffer [out]

Penunjuk ke variabel di mana ukuran, dalam byte, dari informasi pengembalian ditempatkan saat keluar. Jika parameter cbOutputBuffer adalah nol, atau jika ukuran buffer output lebih kecil dari ukuran informasi pengembalian, maka SxsLookupClrGuid gagal dan GetLastError mengembalikan kesalahan ERROR_INSUFFICIENT_BUFFER. Dalam hal ini, gunakan nilai dalam variabel yang diarahkan oleh pcbOutputBuffer untuk mengalokasikan buffer yang cukup besar, lalu panggil SxsLookupClrGuid lagi untuk mengambil informasi yang diinginkan.

Menampilkan nilai

Mengembalikan TRUE jika berhasil, atau FALSE sebaliknya. Untuk informasi kesalahan lainnya, hubungi GetLastError

Keterangan

Fungsi ini tidak memiliki pustaka impor atau file header terkait; Anda harus memanggilnya menggunakan fungsi LoadLibrary dan GetProcAddress .

Komponen terkelola dapat mendeklarasikan diri sebagai "rakitan interop" terkelola pendukung sehingga memungkinkan konsumen komponen Win32 yang tidak dikelola untuk mereferensikan perakitan yang menyatakan. Konsumen komponen dapat berinteraksi dengan komponen terkelola dengan memanggil CoCreateInstance pada GUID. Lapisan interoperaksi merutekan permintaan pembuatan objek ke .NET Framework, membuat instans objek terkelola, dan mengembalikan penunjuk antarmuka.

SxsLookupClrGuid memungkinkan kerangka kerja untuk mengambil informasi yang terkait dengan GUID tertentu dalam manifes komponen, seperti apa nama kelas .NET-nya, versi .NET Framework yang diperlukannya, dan rakitan host tempatnya berada. Komponen terkelola menerbitkan rakitan interop yang berisi sejumlah pernyataan yang mengaitkan GUID dengan nama perakitan dan jenis, dan runtime .NET broker konstruksi instans objek terkelola ketika CoCreateInstance dipanggil.

Berikut ini adalah manifes komponen sampel yang mendeklarasikan GUID CLR dan pengganti CLR yang dapat dicari oleh SxsLookupClrGuid :

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

Penyedia interoperaksi akan memanggil SxsLookupClrGuid dengan pointer ke GUID "{fdb46ca5-9477-4528-b4b2-7f00a254cdea}", dan akan menerima sebagai gantinya nama kelas "MySampleSurrogate", versi runtime yang diperlukan "1.0.3055", dan identitas tekstual "DotNet.Sample.Surrogates,version='1.0.0.0',type='interop'" dari komponen hosting.

Informasi pengembalian ini akan dimuat dan/atau direferensikan oleh struktur SXS_GUID_INFORMATION_CLR yang dideklarasikan sebagai berikut.

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;

Anggota struktur ini berisi informasi berikut.

Aplikasi yang tidak dikelola dapat menggunakan informasi yang dikembalikan dengan cara ini untuk memuat versi .NET Framework yang tepat, memuat rakitan yang diidentifikasi oleh elemen pcwszAssemblyIdentity, lalu membuat instans kelas bernama oleh elemen pcwszTypeName.

Contoh

Gunakan penautan dinamis sebagai berikut untuk memanggil fungsi 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 );
  }
}

Persyaratan

Lihat juga

Aplikasi Terisolasi dan Rakitan Berdampingan

CreateActCtx

ActivateActCtx

CoCreateInstance