Função SxsLookupClrGuid
Recupera o nome da classe e outras informações associadas a um determinado GUID no manifesto de um componente. Essa função é usada somente ao implementar a interoperabilidade não gerenciada de baixo nível no .NET Framework. Para obter mais informações sobre a interoperabilidade gerenciada não gerenciada, confira "Interoperação com código não gerenciado" no SDK do .NET Framework e também Aplicativos isolados e assemblies lado a lado.
Sintaxe
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]
-
Uma combinação de zero ou mais dos sinalizadores a seguir.
Valor Significado - SXS_LOOKUP_CLR_GUID_USE_ACTCTX
- 0x00000001
Se esse sinalizador for definido, o parâmetro hActCtx deverá conter um identificador de contexto de ativação retornado pela função CreateActCtx . Se esse sinalizador não estiver definido, o parâmetro hActCtx será ignorado e SxsLookupClrGuid pesquisará o contexto de ativação que está ativo no momento (a função ActivateActCtx é usada para tornar um contexto de ativação ativo). - SXS_LOOKUP_CLR_GUID_FIND_SURROGATE
- 0x00010000
Se esse sinalizador estiver definido, SxsLookupClrGuid procurará um substituto. - SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS
- 0x00020000
Se esse sinalizador estiver definido, SxsLookupClrGuid procurará uma classe. - SXS_LOOKUP_CLR_GUID_FIND_ANY
- 0x00030000
Essa é uma combinação dos sinalizadores SXS_LOOKUP_CLR_GUID_FIND_SURROGATE e SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS ; se ambos estiverem definidos, SxsLookupClrGuid procurará um substituto primeiro e, somente se ele não encontrar um, procurará uma classe. -
pClsid [in]
-
Um ponteiro para o GUID sobre o qual pesquisar informações de interoperação no contexto de ativação. Esse parâmetro não pode ser NULL.
-
hActCtx [in, opcional]
-
Se o sinalizador SXS_LOOKUP_CLR_GUID_USE_ACTCTX estiver definido no parâmetro dwFlags , hActCtx deverá conter um identificador de contexto de ativação retornado pela função CreateActCtx . Caso contrário, hActCtx será ignorado.
-
pvOutputBuffer [in, out, optional]
-
Ponteiro para o buffer no qual as informações de retorno são copiadas. Esse parâmetro só poderá ter valor NULL se o parâmetro cbOutputBuffer tiver valor zero. Os dados colocados nesse buffer na saída (se houver) consistem em uma estrutura de SXS_GUID_INFORMATION_CLR seguida por quaisquer dados de cadeia de caracteres adicionais necessários. Confira a seção Comentários abaixo para obter mais informações.
-
cbOutputBuffer [in]
-
Tamanho em bytes do buffer apontado pelo parâmetro pvOutputBuffer .
-
pcbOutputBuffer [out]
-
Ponteiro para uma variável em que o tamanho, em bytes, das informações de retorno é colocado na saída. Se o parâmetro cbOutputBuffer for zero ou se o tamanho do buffer de saída for menor que o tamanho das informações de retorno, SxsLookupClrGuid falhará e GetLastError retornará um erro de ERROR_INSUFFICIENT_BUFFER. Nesse caso, use o valor na variável apontada por pcbOutputBuffer para alocar um buffer grande o suficiente e, em seguida, chame SxsLookupClrGuid novamente para recuperar as informações desejadas.
Valor retornado
Retornará TRUE se tiver êxito ou FALSE caso contrário. Para obter mais informações de erro, chame GetLastError
Comentários
Essa função não tem biblioteca de importação ou arquivo de cabeçalho associado; você deve chamá-lo usando as funções LoadLibrary e GetProcAddress .
Os componentes gerenciados podem se declarar como suporte a "assemblies de interoperabilidade" gerenciados para permitir que um consumidor de componente Win32 não gerenciado faça referência ao assembly declarado. O consumidor do componente pode interagir com o componente gerenciado chamando CoCreateInstance em um GUID. A camada de interoperação roteia a solicitação de criação de objeto para .NET Framework, cria uma instância do objeto gerenciado e retorna um ponteiro de interface.
SxsLookupClrGuid permite que as estruturas recuperem informações associadas a um determinado GUID no manifesto do componente, como qual é o nome da classe .NET, qual versão do .NET Framework requer e em qual assembly de host ele está localizado. Os componentes gerenciados publicam um assembly de interoperabilidade que contém várias instruções que associam GUIDs a nomes de assembly e tipo, e o runtime do .NET intermedia a construção de instâncias de objeto gerenciado quando CoCreateInstance é chamado.
Veja a seguir um manifesto de componente de exemplo declarando um GUID CLR e um substituto clr que SxsLookupClrGuid pode pesquisar:
<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>
Um provedor de interoperação chamaria SxsLookupClrGuid com um ponteiro para o GUID "{fdb46ca5-9477-4528-b4b2-7f00a254cdea}" e receberia em troca o nome da classe "MySampleSurrogate", a versão de runtime necessária "1.0.3055" e a identidade textual "DotNet.Sample.Surrogates,version='1.0.0.0',type='interop'" do componente de hospedagem.
Essas informações de retorno seriam contidas e/ou referenciadas por uma estrutura SXS_GUID_INFORMATION_CLR declarada da seguinte maneira.
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;
Os membros dessa estrutura contêm as informações a seguir.
| Membro | Descrição |
|---|---|
|
Cbsize |
Contém o tamanho da estrutura SXS_GUID_INFORMATION_CLR (isso permite que a estrutura cresça em versões posteriores). |
|
dwFlags |
Contém um dos dois valores de sinalizador a seguir:
|
|
pcwszRuntimeVersion |
Aponta para uma cadeia de caracteres largos terminada em zero que identifica a versão do runtime especificada no manifesto do host para essa classe. |
|
pcwszTypeName |
Aponta para uma cadeia de caracteres largos terminada em zero que contém o nome da classe .NET associada ao GUID especificado. |
|
pcwszAssemblyIdentity |
Aponta para uma cadeia de caracteres largos terminada em zero que contém a identidade textual do assembly que hospeda essa classe. Para obter mais informações sobre a identidade textual, confira "Especificando nomes de tipo totalmente qualificados" em "Descobrindo informações de tipo em tempo de execução" em "Programação com o .NET Framework" no SDK do .NET Framework. |
Um aplicativo não gerenciado pode usar as informações retornadas dessa forma para carregar a versão correta do .NET Framework, carregar o assembly identificado pelo elemento pcwszAssemblyIdentity e, em seguida, criar uma instância da classe chamada pelo elemento pcwszTypeName.
Exemplos
Use a vinculação dinâmica da seguinte maneira para chamar a função 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
| Requisito | Valor |
|---|---|
| DLL |
|
Confira também