Поделиться через

Функция SxsLookupClrGuid

  • Статья

Извлекает имя класса и другие сведения, связанные с заданным ИДЕНТИФИКАТОРом GUID в манифесте компонента. Эта функция используется только при реализации низкоуровневого управляемого неуправляемого взаимодействия в платформа .NET Framework. Дополнительные сведения об управляемом и неуправляемом взаимодействии см. в разделе Взаимодействие с неуправляемыми кодами в пакете SDK для платформа .NET Framework, а также изолированные приложения и параллельные сборки.

Синтаксис

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

Параметры

dwFlags [in]

Сочетание нулевых или нескольких следующих флагов.

Значение Значение
SXS_LOOKUP_CLR_GUID_USE_ACTCTX
0x00000001
 Если этот флаг установлен, параметр hActCtx должен содержать дескриптор контекста активации, возвращаемый функцией CreateActCtx . Если этот флаг не задан, параметр hActCtx игнорируется и SxsLookupClrGuid выполняет поиск в активном контексте активации (функция ActivateActCtx используется для активации).
SXS_LOOKUP_CLR_GUID_FIND_SURROGATE
0x00010000
 Если этот флаг установлен, SxsLookupClrGuid выполняет поиск суррогата.
SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS
0x00020000
 Если этот флаг установлен, SxsLookupClrGuid выполняет поиск класса.
SXS_LOOKUP_CLR_GUID_FIND_ANY
0x00030000
 Это сочетание флагов SXS_LOOKUP_CLR_GUID_FIND_SURROGATE и SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS ; Если заданы оба параметра, SxsLookupClrGuid сначала ищет суррогат и только если он не находит его, затем выполняет поиск класса.

 

pClsid [in]

Указатель на GUID, по которому выполняется поиск сведений о взаимодействии в контексте активации. Этот параметр не может иметь значение NULL.

hActCtx [in, необязательный]

Если флаг SXS_LOOKUP_CLR_GUID_USE_ACTCTX задан в параметре dwFlags , то hActCtx должен содержать дескриптор контекста активации, возвращаемый функцией CreateActCtx . В противном случае hActCtx игнорируется.

pvOutputBuffer [in, out, optional]

Указатель на буфер, в который копируются возвращаемые сведения. Этот параметр может иметь значение NULL, только если параметр cbOutputBuffer имеет нулевое значение. Данные, помещенные в этот буфер при выходе (если таковые есть), состоят из SXS_GUID_INFORMATION_CLR структуры, за которой следуют все необходимые дополнительные строковые данные. Дополнительные сведения см. в разделе Примечания ниже.

cbOutputBuffer [in]

Размер буфера в байтах, на который указывает параметр pvOutputBuffer .

pcbOutputBuffer [out]

Указатель на переменную, в которой размер возвращаемой информации в байтах помещается при выходе. Если параметр cbOutputBuffer равен нулю или размер выходного буфера меньше размера возвращаемой информации, то SxsLookupClrGuid завершается сбоем и GetLastError возвращает ошибку ERROR_INSUFFICIENT_BUFFER. В этом случае используйте значение в переменной, на которую указывает pcbOutputBuffer , чтобы выделить достаточно большой буфер, а затем снова вызовите SxsLookupClrGuid , чтобы получить нужные сведения.

Возвращаемое значение

Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Для получения дополнительных сведений об ошибке вызовите Метод GetLastError.

Комментарии

У этой функции нет связанной библиотеки импорта или файла заголовка; его необходимо вызвать с помощью функций LoadLibrary и GetProcAddress .

Управляемые компоненты могут объявлять себя как поддерживающие управляемые "сборки взаимодействия", чтобы позволить неуправляемым потребителю компонента Win32 ссылаться на объявляющую сборку. Потребитель компонента может взаимодействовать с управляемым компонентом, вызывая CoCreateInstance по идентификатору GUID. Слой взаимодействия направляет запрос на создание объекта в платформа .NET Framework, создает экземпляр управляемого объекта и возвращает указатель интерфейса.

SxsLookupClrGuid позволяет платформам получать сведения, связанные с заданным GUID в манифесте компонента, например имя класса .NET, требуемую версию платформа .NET Framework и сборку узла, в которой она находится. Управляемые компоненты публикуют сборку взаимодействия, содержащую ряд инструкций, связывающих GUID с именами сборок и типов, а среда выполнения .NET создает экземпляры управляемых объектов при вызове CoCreateInstance .

Ниже приведен пример манифеста компонента, объявляющего GUID CLR и суррогат CLR, который может искать 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>

Поставщик взаимодействия вызывает SxsLookupClrGuid с указателем на GUID "{fdb46ca5-9477-4528-b4b2-7f00a254cdea}", и получат в ответ имя класса MySampleSurrogate, требуемую версию среды выполнения 1.0.3055 и текстовое удостоверение DotNet.Sample.Surrogates,version='1.0.0.0',type='interop'" компонента размещения.

Эти возвращаемые сведения будут содержаться и /или ссылаться в SXS_GUID_INFORMATION_CLR структуре, объявленной следующим образом.

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;

Элементы этой структуры содержат следующие сведения.

Член Описание
cbSize
 Содержит размер структуры SXS_GUID_INFORMATION_CLR (это позволяет увеличивать структуру в более поздних версиях).
Dwflags
 Содержит одно из следующих двух значений флага:
  • SXS_GUID_INFORMATION_CLR_FLAG_IS_SURROGATE (0x00000001). Указывает, что указанный GUID был связан с "суррогатом".
  • SXS_GUID_INFORMATION_CLR_FLAG_IS_CLASS (0x00000002): указывает, что указанный GUID был связан с "классом".
pcwszRuntimeVersion
 Указывает на строку расширенных символов с нулем, которая определяет версию среды выполнения, указанную в манифесте узла для этого класса.
pcwszTypeName
 Указывает на строку расширенных символов с нулем, содержащую имя класса .NET, связанное с указанным GUID.
pcwszAssemblyIdentity
 Указывает на строку расширенных символов с нулем, содержащую текстовое удостоверение сборки, в котором размещен этот класс. Дополнительные сведения о текстовом удостоверении см. в разделе "Указание полных имен типов" раздела "Обнаружение сведений о типе во время выполнения" раздела "Программирование с помощью платформа .NET Framework" пакета SDK для платформа .NET Framework.

 

Неуправляемое приложение может использовать возвращаемые таким образом сведения, чтобы загрузить правильную версию платформа .NET Framework, загрузить сборку, определяемую элементом pcwszAssemblyIdentity, а затем создать экземпляр класса с именем элемента pcwszTypeName.

Примеры

Используйте динамическое связывание следующим образом для вызова функции 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 );
  }
}

Требования

Требование Значение
DLL
Mscoree.dll;
Sxs.dll

См. также раздел

Изолированные приложения и параллельные сборки

CreateActCtx

ActivateActCtx

CoCreateInstance