다음을 통해 공유

SxsLookupClrGuid 함수

  • 아티클

구성 요소 매니페스트에서 지정된 GUID와 연결된 클래스 이름 및 기타 정보를 검색합니다. 이 함수는 .NET Framework 낮은 수준의 관리되지 않는 상호 운용성을 구현할 때만 사용됩니다. 관리되지 않는 상호 운용성에 대한 자세한 내용은 .NET Framework SDK의 "비관리 코드와 상호 운용"과 격리된 애플리케이션 및 병렬 어셈블리를 참조하세요.

구문

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]

다음 플래그 중 0개 이상의 조합입니다.

값 의미
SXS_LOOKUP_CLR_GUID_USE_ACTCTX
0x00000001
 이 플래그가 설정되면 hActCtx 매개 변수에 CreateActCtx 함수에서 반환된 활성화 컨텍스트 핸들이 포함되어야 합니다. 이 플래그를 설정하지 않으면 hActCtx 매개 변수가 무시되고 SxsLookupClrGuid 는 현재 활성 상태인 활성화 컨텍스트를 검색합니다( ActivatActCtx 함수는 활성화 컨텍스트를 활성화하는 데 사용됨).
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, optional]

SXS_LOOKUP_CLR_GUID_USE_ACTCTX 플래그가 dwFlags 매개 변수에 설정된 경우 hActCtx는 CreateActCtx 함수에서 반환된 활성화 컨텍스트 핸들을 포함해야 합니다. 그렇지 않으면 hActCtx 가 무시됩니다.

pvOutputBuffer [in, out, optional]

반환 정보가 복사되는 버퍼에 대한 포인터입니다. 이 매개 변수는 cbOutputBuffer 매개 변수 값이 0인 경우에만 NULL 값이 될 수 있습니다. 종료 시 이 버퍼에 배치된 데이터(있는 경우)는 SXS_GUID_INFORMATION_CLR 구조와 필요한 추가 문자열 데이터로 구성됩니다. 자세한 내용은 아래 설명 섹션을 참조하세요.

cbOutputBuffer [in]

pvOutputBuffer 매개 변수가 가리키는 버퍼의 크기(바이트)입니다.

pcbOutputBuffer [out]

반환 정보의 크기(바이트)가 종료 시 배치되는 변수에 대한 포인터입니다. cbOutputBuffer 매개 변수가 0이거나 출력 버퍼의 크기가 반환 정보의 크기보다 작은 경우 SxsLookupClrGuid가 실패하고 GetLastError가 ERROR_INSUFFICIENT_BUFFER 오류를 반환합니다. 이 경우 pcbOutputBuffer 가 가리키는 변수의 값을 사용하여 충분한 버퍼를 할당한 다음 SxsLookupClrGuid 를 다시 호출하여 원하는 정보를 검색합니다.

반환 값

성공하면 TRUE를 반환하고 그렇지 않으면 FALSE를 반환합니다. 자세한 오류 정보는 GetLastError를 호출합니다.

설명

이 함수에는 연결된 가져오기 라이브러리 또는 헤더 파일이 없습니다. LoadLibrary 및 GetProcAddress 함수를 사용하여 호출해야 합니다.

관리되는 구성 요소는 관리되지 않는 Win32 구성 요소 소비자가 선언 어셈블리를 참조할 수 있도록 관리되는 "interop 어셈블리"를 지원하는 것으로 자신을 선언할 수 있습니다. 구성 요소 소비자는 GUID에서 CoCreateInstance 를 호출하여 관리되는 구성 요소와 상호 작용할 수 있습니다. 상호 운용 계층은 개체 만들기 요청을 .NET Framework 라우팅하고, 관리되는 개체의 instance 만들고, 인터페이스 포인터를 반환합니다.

SxsLookupClrGuid를 사용하면 프레임워크가 구성 요소의 매니페스트에서 지정된 GUID와 연결된 정보(예: .NET 클래스 이름, 필요한 .NET Framework 버전 및 호스트 어셈블리)를 검색할 수 있습니다. 관리되는 구성 요소는 GUID를 어셈블리 및 형식 이름과 연결한 여러 문이 포함된 interop 어셈블리를 게시하고, .NET 런타임은 CoCreateInstance 가 호출되면 관리되는 개체 인스턴스의 생성을 조정합니다.

다음은 SxsLookupClrGuid 가 조회할 수 있는 CLR GUID 및 CLR 서로게이트를 선언하는 샘플 구성 요소 매니페스트입니다.

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

상호 운용 공급자는 GUID "{fdb46ca5-9477-4528-b4b2-7f00a254cdea}"에 대한 포인터를 사용하여 SxsLookupClrGuid 를 호출합니다. 및 는 클래스 이름 "MySampleSurrogate", 필수 런타임 버전 "1.0.3055", 호스팅 구성 요소의 텍스트 ID "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
 이 클래스의 호스트 매니페스트에 지정된 런타임 버전을 식별하는 0으로 끝나는 와이드 문자열을 가리킵니다.
pcwszTypeName
 지정된 GUID와 연결된 .NET 클래스의 이름을 포함하는 0으로 끝나는 와이드 문자열을 가리킵니다.
pcwszAssemblyIdentity
 이 클래스를 호스트하는 어셈블리의 텍스트 ID를 포함하는 0으로 끝나는 와이드 문자열을 가리킵니다. 텍스트 ID에 대한 자세한 내용은 .NET Framework SDK의 ".NET Framework 사용하여 프로그래밍"의 "런타임에 형식 정보 검색" 아래의 "정규화된 형식 이름 지정"을 참조하세요.

 

관리되지 않는 애플리케이션은 이 방식으로 반환된 정보를 사용하여 올바른 버전의 .NET Framework 로드하고, pcwszAssemblyIdentity 요소로 식별된 어셈블리를 로드한 다음, pcwszTypeName 요소로 명명된 클래스의 instance 만들 수 있습니다.

예제

다음과 같이 동적 연결을 사용하여 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

추가 정보

격리된 애플리케이션 및 side-by-side 어셈블리

CreateActCtx

ActivateActCtx

CoCreateInstance