QueryActCtxW, fonction (winbase.h)
La fonction QueryActCtxW interroge le contexte d’activation.
Syntaxe
BOOL QueryActCtxW(
[in] DWORD dwFlags,
[in] HANDLE hActCtx,
[in, optional] PVOID pvSubInstance,
[in] ULONG ulInfoClass,
[out] PVOID pvBuffer,
[in, optional] SIZE_T cbBuffer,
[out, optional] SIZE_T *pcbWrittenOrRequired
);
Paramètres
[in] dwFlags
Ce paramètre doit être défini sur l’un des bits d’indicateur suivants.
| Indicateur | Signification |
|---|---|
|
QueryActCtxW interroge le contexte d’activation actif sur le thread au lieu du contexte spécifié par hActCtx. Il s’agit généralement du dernier contexte d’activation passé à ActivateActCtx. Si ActivateActCtx n’a pas été appelé, le contexte d’activation actif peut être le contexte d’activation utilisé par l’exécutable du processus actuel. Dans d’autres cas, le système d’exploitation détermine le contexte d’activation actif. Par exemple, lorsque la fonction de rappel à un nouveau thread est appelée, le contexte d’activation actif peut être le contexte qui était actif lorsque vous avez créé le thread en appelant CreateThread. |
|
QueryActCtxW interprète hActCtx comme un type de données HMODULE et interroge un contexte d’activation associé à une DLL ou EXE.
Lorsqu’une DLL ou EXE est chargée, le chargeur recherche un manifeste stocké dans une ressource. Si le chargeur trouve une ressource RT_MANIFEST avec un identificateur de ressource défini sur ISOLATIONAWARE_MANIFEST_ RESOURCE_ID, le chargeur associe le contexte d’activation résultant à la DLL ou à l’EXE. Il s’agit du contexte d’activation que QueryActCtxW interroge lorsque l’indicateur QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE a été défini. |
|
QueryActCtxW interprète hActCtx comme une adresse au sein d’une DLL ou d’un EXE et interroge un contexte d’activation qui a été associé à la DLL ou à l’EXE. Il peut s’agir de n’importe quelle adresse dans la DLL ou EXE. Par exemple, l’adresse d’une fonction au sein d’une DLL ou d’un EXE ou l’adresse de toutes les données statiques, telles qu’une chaîne constante.
Quand une DLL ou EXE est chargée, le chargeur recherche un manifeste stocké dans une ressource de la même façon que QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE. |
[in] hActCtx
Gérez le contexte d’activation interrogé.
[in, optional] pvSubInstance
Index de l’assembly, ou combinaison d’assemblys et de fichiers, dans le contexte d’activation. La signification de pvSubInstance dépend de l’option spécifiée par la valeur du paramètre ulInfoClass .
Ce paramètre peut avoir la valeur null.
| UlInfoClass, option | Signification |
|---|---|
|
Pointeur vers un DWORD qui spécifie l’index de l’assembly dans le contexte d’activation. Il s’agit du contexte d’activation que QueryActCtxW interroge. |
|
Pointeur vers une structure ACTIVATION_CONTEXT_QUERY_INDEX . Si QueryActCtxW est appelé avec cette option et que la fonction réussit, la mémoire tampon retournée contient des informations pour un fichier dans l’assembly. Ces informations sont sous la forme de la structure ASSEMBLY_FILE_DETAILED_INFORMATION . |
[in] ulInfoClass
Ce paramètre peut avoir uniquement les valeurs indiquées dans le tableau suivant.
| Option | Signification |
|---|---|
|
Non disponible. |
|
Si QueryActCtxW est appelé avec cette option et que la fonction réussit, la mémoire tampon retournée contient des informations détaillées sur le contexte d’activation. Ces informations sont sous la forme de la structure ACTIVATION_CONTEXT_DETAILED_INFORMATION . |
|
Si QueryActCtxW est appelé avec cette option et que la fonction réussit, la mémoire tampon contient des informations sur l’assembly dont l’index est spécifié dans pvSubInstance. Ces informations sont sous la forme de la structure ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION . |
|
Informations sur un fichier dans l’un des assemblys dans le contexte d’activation. Le paramètre pvSubInstance doit pointer vers une structure ACTIVATION_CONTEXT_QUERY_INDEX . Si QueryActCtxW est appelé avec cette option et que la fonction réussit, la mémoire tampon retournée contient des informations pour un fichier dans l’assembly. Ces informations sont sous la forme de la structure ASSEMBLY_FILE_DETAILED_INFORMATION . |
|
Si QueryActCtxW est appelé avec cette option et que la fonction réussit, la mémoire tampon contient des informations sur le niveau d’exécution demandé du contexte d’activation. Ces informations sont sous la forme de la structure ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION .
Windows Server 2003 et Windows XP : Cette valeur n’est pas disponible. |
|
Si QueryActCtxW est appelé avec cette option et que la fonction réussit, la mémoire tampon contient des informations sur le contexte de compatibilité demandé. Ces informations sont sous la forme de la structure ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION .
Windows Server 2008 et versions antérieures, windows Vista et versions antérieures : Cette valeur n’est pas disponible. Cette option est disponible à partir de Windows Server 2008 R2 et Windows 7. |
[out] pvBuffer
Pointeur vers une mémoire tampon qui contient les informations retournées. Ce paramètre est facultatif. Si pvBuffer a la valeur Null, cbBuffer doit être égal à zéro. Si la taille de la mémoire tampon pointée par pvBuffer est trop petite, QueryActCtxW retourne ERROR_INSUFFICIENT_BUFFER et aucune donnée n’est écrite dans la mémoire tampon. Consultez la section Remarques pour la méthode que vous pouvez utiliser pour déterminer la taille requise de la mémoire tampon.
[in, optional] cbBuffer
Taille de la mémoire tampon en octets pointée par pvBuffer. Ce paramètre est facultatif.
[out, optional] pcbWrittenOrRequired
Nombre d’octets écrits ou requis. Le paramètre pcbWrittenOrRequired ne peut être NULL que lorsque pvBuffer a la valeur NULL. Si pcbWrittenOrRequired n’a pas la valeur NULL, il est rempli avec le nombre d’octets requis pour stocker la mémoire tampon retournée.
Valeur retournée
Si la fonction réussit, elle retourne TRUE. Sinon, elle retourne FALSE.
Cette fonction définit les erreurs qui peuvent être récupérées en appelant GetLastError. Pour obtenir un exemple, consultez Récupération du code Last-Error. Pour obtenir la liste complète des codes d’erreur, consultez Codes d’erreur système.
Remarques
Le paramètre cbBuffer spécifie la taille en octets de la mémoire tampon pointée par pvBuffer. Si pvBuffer a la valeur NULL, cbBuffer doit être 0. Le paramètre pcbWrittenOrRequired ne peut être NULL que si pvBuffer a la valeur NULL. Si pcbWrittenOrRequired n’a pas la valeur NULL au retour, il est rempli avec le nombre d’octets requis pour stocker les informations retournées. Lorsque les données d’informations retournées sont supérieures à la mémoire tampon fournie, QueryActCtxW retourne ERROR_INSUFFICIENT_BUFFER et aucune donnée n’est écrite dans la mémoire tampon pointée par pvBuffer.
L’exemple suivant montre la méthode qui consiste à appeler d’abord avec une petite mémoire tampon, puis à se rappeler si la mémoire tampon est trop petite.
SIZE_T cbRequired;
PVOID pvData = NULL;
SIZE_T cbAvailable = 0;
if (!QueryActCtxW(..., pvData, cbAvailable, &cbRequired) && (GetLastError()== ERROR_INSUFFICIENT_BUFFER))
{
// Allocate enough space to store the returned buffer, fail if too small
if (NULL == (pvData = HeapAlloc(GetProcessHeap(), 0, cbRequired)))
{
SetLastError(ERROR_NOT_ENOUGH_MEMORY);
return FALSE;
}
cbAvailable = cbRequired;
// Try again, this should succeed.
if (QueryActCtxW(..., pvData, cbAvailable, &cbRequired))
{
// Use the returned data in pvData
}
HeapFree(GetProcessHeap(), 0, pvData);
pvData = NULL;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winbase.h (inclure Windows.h) |
| Bibliothèque | Kernel32.lib |
| DLL | Kernel32.dll |