Fonction SxsLookupClrGuid
Récupère le nom de classe et d’autres informations associées à un GUID donné dans le manifeste d’un composant. Cette fonction est utilisée uniquement lors de l’implémentation de l’interopérabilité managée non managée de bas niveau dans le .NET Framework. Pour plus d’informations sur l’interopérabilité managée-non managée, consultez « Interopérabilité avec du code non managé » dans le Kit de développement logiciel (SDK) .NET Framework, ainsi que sur les applications isolées et les assemblys côte à côte.
Syntaxe
BOOL SxsLookupClrGuid(
_In_ DWORD dwFlags,
_In_ LPGUID pClsid,
_In_opt_ HANDLE hActCtx,
_Inout_opt_ PVOID pvOutputBuffer,
_In_ SIZE_T cbOutputBuffer,
_Out_ PSIZE_T pcbOutputBuffer
);
Paramètres
-
dwFlags [in]
-
Combinaison de zéro ou plus des indicateurs suivants.
Valeur Signification - SXS_LOOKUP_CLR_GUID_USE_ACTCTX
- 0x00000001
Si cet indicateur est défini, le paramètre hActCtx doit contenir un handle de contexte d’activation retourné par la fonction CreateActCtx . Si cet indicateur n’est pas défini, le paramètre hActCtx est ignoré et SxsLookupClrGuid recherche le contexte d’activation actuellement actif (la fonction ActivateActCtx est utilisée pour activer un contexte d’activation). - SXS_LOOKUP_CLR_GUID_FIND_SURROGATE
- 0x00010000
Si cet indicateur est défini, SxsLookupClrGuid recherche un substitut. - SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS
- 0x00020000
Si cet indicateur est défini, SxsLookupClrGuid recherche une classe. - SXS_LOOKUP_CLR_GUID_FIND_ANY
- 0x00030000
Il s’agit d’une combinaison des indicateurs SXS_LOOKUP_CLR_GUID_FIND_SURROGATE et SXS_LOOKUP_CLR_GUID_FIND_CLR_CLASS ; si les deux sont définis, SxsLookupClrGuid recherche d’abord un substitut, et seulement s’il n’en trouve pas, recherche ensuite une classe. -
pClsid [in]
-
Pointeur vers le GUID sur lequel rechercher des informations d’interopérabilité dans le contexte d’activation. Ce paramètre ne peut pas avoir la valeur NULL.
-
hActCtx [in, facultatif]
-
Si l’indicateur SXS_LOOKUP_CLR_GUID_USE_ACTCTX est défini dans le paramètre dwFlags , hActCtx doit contenir un handle de contexte d’activation retourné par la fonction CreateActCtx . Sinon, hActCtx est ignoré.
-
pvOutputBuffer [in, out, optional]
-
Pointeur vers la mémoire tampon dans laquelle les informations de retour sont copiées. Ce paramètre peut avoir une valeur NULL uniquement si le paramètre cbOutputBuffer a une valeur nulle. Les données placées dans cette mémoire tampon à la sortie (le cas échéant) se composent d’une structure SXS_GUID_INFORMATION_CLR suivie de toutes les données de chaîne supplémentaires requises. Pour plus d’informations, consultez la section Remarques ci-dessous.
-
cbOutputBuffer [in]
-
Taille en octets de la mémoire tampon pointée vers le paramètre pvOutputBuffer .
-
pcbOutputBuffer [out]
-
Pointeur vers une variable où la taille, en octets, des informations de retour est placée à la sortie. Si le paramètre cbOutputBuffer est égal à zéro ou si la taille de la mémoire tampon de sortie est inférieure à la taille des informations de retour, SxsLookupClrGuid échoue et GetLastError retourne une erreur de ERROR_INSUFFICIENT_BUFFER. Dans ce cas, utilisez la valeur dans la variable pointée par pcbOutputBuffer pour allouer une mémoire tampon suffisamment grande, puis appelez à nouveau SxsLookupClrGuid pour récupérer les informations souhaitées.
Valeur retournée
Retourne LA valeur TRUE si elle réussit ou FALSE dans le cas contraire. Pour plus d’informations sur l’erreur, appelez GetLastError
Notes
Cette fonction n’a aucune bibliothèque d’importation ou fichier d’en-tête associé ; vous devez l’appeler à l’aide des fonctions LoadLibrary et GetProcAddress .
Les composants managés peuvent se déclarer comme prenant en charge les « assemblys d’interopérabilité » managés afin de permettre à un consommateur de composants Win32 non managé de référencer l’assembly déclarant. Le consommateur de composants peut interagir avec le composant managé en appelant CoCreateInstance sur un GUID. La couche d’interopérabilité achemine la demande de création d’objet vers .NET Framework, crée un instance de l’objet managé et retourne un pointeur d’interface.
SxsLookupClrGuid permet aux frameworks de récupérer des informations associées à un GUID donné dans le manifeste du composant, telles que le nom de sa classe .NET, la version du .NET Framework dont il a besoin et l’assembly hôte dans lequel il se trouve. Les composants managés publient un assembly d’interopérabilité qui contient un certain nombre d’instructions associant des GUID avec des noms d’assembly et de type, et le runtime .NET répartit la construction d’instances d’objets managés lorsque CoCreateInstance est appelé.
Voici un exemple de manifeste de composant déclarant un GUID CLR et une substitution CLR que SxsLookupClrGuid peut rechercher :
<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>
Un fournisseur d’interopérabilité appelle SxsLookupClrGuid avec un pointeur vers le GUID « {fdb46ca5-9477-4528-b4b2-7f00a254cdea} », et recevaient en retour le nom de classe « MySampleSurrogate », la version d’exécution requise « 1.0.3055 » et l’identité textuelle « DotNet.Sample.Surrogates,version='1.0.0.0',type='interop' » du composant d’hébergement.
Ces informations de retour sont contenues et/ou référencées par une structure de SXS_GUID_INFORMATION_CLR déclarée comme suit.
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;
Les membres de cette structure contiennent les informations suivantes.
| Membre | Description |
|---|---|
|
cbSize |
Contient la taille de la structure SXS_GUID_INFORMATION_CLR (cela permet à la structure de croître dans les versions ultérieures). |
|
dwFlags |
Contient l’une des deux valeurs d’indicateur suivantes :
|
|
pcwszRuntimeVersion |
Pointe vers une chaîne de caractères larges sans fin qui identifie la version du runtime spécifiée dans le manifeste de l’hôte pour cette classe. |
|
pcwszTypeName |
Pointe vers une chaîne de caractères larges sans fin qui contient le nom de la classe .NET associée au GUID spécifié. |
|
pcwszAssemblyIdentity |
Pointe vers une chaîne de caractères larges sans fin qui contient l’identité textuelle de l’assembly qui héberge cette classe. Pour plus d’informations sur l’identité textuelle, consultez « Spécification de noms de types complets » sous « Découverte des informations de type au moment de l’exécution » sous « Programmation avec le .NET Framework » dans le Kit de développement logiciel (SDK) .NET Framework. |
Une application non managée peut utiliser les informations retournées de cette façon pour charger la version appropriée du .NET Framework, charger l’assembly identifié par l’élément pcwszAssemblyIdentity, puis créer un instance de la classe nommée par l’élément pcwszTypeName.
Exemples
Utilisez la liaison dynamique comme suit pour appeler la fonction 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 );
}
}
Spécifications
| Condition requise | Valeur |
|---|---|
| DLL |
|
Voir aussi