SetAdditionalForegroundBoostProcesses, fonction (Winuser.h)

Article
10/26/2023

SetAdditionalForegroundBoostProcesses est une API d’assistance aux performances qui aide les applications avec un modèle d’application multiprocessus où plusieurs processus contribuent à une expérience de premier plan, que ce soit sous forme de données ou de rendu. Par exemple, les navigateurs (avec le gestionnaire de navigateur ou le cadre, les onglets, les plug-ins, etc. hébergés dans différents processus) et les IDE (qui génèrent des processus pour la compilation et d’autres tâches).

Les applications peuvent utiliser cette API pour fournir une priorité de premier plan aux processus de travail qui aident à prendre en charge l’application main. Ces applications peuvent avoir un renforcement de priorité uniforme appliqué à tous leurs processus constitutifs lorsque la fenêtre de niveau supérieur de l’application se trouve au premier plan.

Syntaxe

BOOL SetAdditionalForegroundBoostProcesses(
  HWND   topLevelWindow,
  DWORD  processHandleCount,
  HANDLE *processHandleArray
);

Paramètres

topLevelWindow

Handle vers la fenêtre de niveau supérieur (HWND) de l’application.

processHandleCount

Nombre de handles de processus dans processHandleArray. Cette fonction peut être appelée en une seule fois avec un maximum de 32 handles. Définissez ce paramètre sur 0 et définissez processHandleArray sur NULL pour effacer une configuration d’augmentation précédente.

processHandleArray

Groupe de handles de processus à améliorer ou à dé booster au premier plan. Définissez ce paramètre sur NULL et définissez processHandleCount sur 0 pour effacer une configuration d’augmentation précédente.

Valeur retournée

Retourne TRUE si l’appel réussit à stimuler l’application ; SINON, FALSE . SetAdditionalForegroundBoostProcesses définit le dernier code d’erreur, afin que l’application puisse appeler GetLastError() pour obtenir des informations étendues si l’appel a échoué (par exemple, ERROR_INVALID_PARAMETER, ERROR_NOT_ENOUGH_MEMORY ou ERROR_ACCESS_DENIED).

Remarques

Cette fonction prend un groupe de handles de processus qui sont tous optimisés ou dé boostés au premier plan lorsque le HWND de niveau supérieur passé se déplace respectivement vers le premier plan ou l’arrière-plan. Chaque fois que le HWND de niveau supérieur passé devient la fenêtre de premier plan, un renforcement au premier plan est également appliqué aux processus passés dans le tableau de handles. Un dé boost similaire se produit lorsque le HWND de niveau supérieur passe à l’arrière-plan.

Le HWND de niveau supérieur passé à cette fonction doit appartenir au processus appelant. Le processus appelant doit avoir l’accès PROCESS_SET_INFORMATION droit sur les handles de processus dans le processHandleArray . En d’autres termes, vous devez avoir le contrôle total de chaque fenêtre de votre processus. Si un composant externe injecte une fenêtre qui prend le premier plan, ou si une boîte de dialogue s’affiche, vous perdez votre impulsion.

Si vous avez deux fenêtres de niveau supérieur, vous devez appeler cette fonction pour chacune d’elles.

Si le HWND de niveau supérieur passé se trouve déjà au premier plan lorsque SetAdditionalForegroundBoostProcesses est appelé, tous les processus du processHandleArray sont immédiatement optimisés.

Un processus dont le handle se trouve dans le processHandleArray n’obtient une augmentation de premier plan que lorsque le HWND de niveau supérieur devient la fenêtre de premier plan.

Un renforcement supplémentaire au premier plan est appliqué uniquement dans les cas suivants :

La fenêtre de premier plan change, ou
Si cette fonction est appelée alors que la fenêtre se trouve au premier plan et que la nouvelle liste a le handle de processus, ou si la liste n’inclut pas le handle de processus alors qu’elle était précédemment incluse.

Lorsque le processus propriétaire du HWND de niveau supérieur se ferme ou se termine, la relation de renforcement supplémentaire est détruite et les processus secondaires ne reçoivent pas d’augmentation supplémentaire au premier plan.

Le HWND de niveau supérieur du processus principal continue de contenir des références aux processus secondaires jusqu’à ce que le HWND de niveau supérieur du processus principal efface son état d’amplification groupé ou que le HWND soit détruit.

Exemple

Dans ce scénario simple, l’application configure sa configuration d’augmentation du processus de premier plan lors de la création de la fenêtre de niveau supérieur. Lorsque WM_CREATE est géré, la fonction est appelée avec des handles dans le lParam et le nombre de handles dans le wParam. Ces processus obtiennent une priorité de premier plan ou d’arrière-plan renforcée à mesure que m_AppWindow se déplace dans et hors de la fenêtre de premier plan. Si le m_AppWindow est la fenêtre de premier plan lorsque la fonction est appelée, les processus obtiennent également un renforcement immédiat de la priorité au premier plan.

case WM_CREATE:   

    // 
    // Configure the passed in worker processes (handles) in lParam, to get foreground priority boost when m_AppWindow moves in and 
    // out of the foreground. 
    //  

    HANDLE *pMyHandles = retinterpret_cast<HANDLE*>(lParam); 
    DWORD cHandles = reinterpret_cast<DWORD>(wParam);  

    If (!SetAdditionalForegroundBoostProcesses(m_AppWindow, cHandles, pMyHandles)) 
    { 
        printf(“SetAdditionalForegroundBoostProcesses() setup failed with error code : %d\n”, GetLastError()); 
    } 

    break;

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 11 Build 22621
En-tête	Winuser.h (y compris Windows.h)
Bibliothèque	User32.lib
DLL	User32.dll

Voir aussi

SetForegroundWindow

Partager via