QueryActCtxW, fonction (winbase.h)

Article
08/27/2023

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
QUERY_ACTCTX_FLAG_USE_ACTIVE_ACTCTX	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.
QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE	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.
QUERY_ACTCTX_FLAG_ACTCTX_IS_ADDRESS	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
AssemblyDetailedInformationInActivationContext	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.
FileInformationInAssemblyOfAssemblyInActivationContext	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
ActivationContextBasicInformation 1	Non disponible.
ActivationContextDetailedInformation 2	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 .
AssemblyDetailedInformationInActivationContext 3	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 .
FileInformationInAssemblyOfAssemblyInActivationContext 4	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 .
RunlevelInformationInActivationContext 5	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.
CompatibilityInformationInActivationContext 6	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, &amp;cbRequired) &amp;&amp; (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, &amp;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