Функция SetAdditionalForegroundBoostProcesses (Winuser.h)

Статья
08/28/2023

SetAdditionalForegroundBoostProcesses — это API помощи в повышении производительности, помогающий приложениям с многопроцессной моделью приложений, в которой несколько процессов участвуют в работе переднего плана в виде данных или отрисовки. К примерам относятся браузеры (с диспетчером браузера или фреймом, вкладками, подключаемыми модулями и т. д.), размещенными в разных процессах) и среды ED (которые порождают процессы компиляции и других задач).

Приложения могут использовать этот API для повышения приоритета переднего плана для рабочих процессов, которые помогают поддерживать main приложения. Такие приложения могут иметь единый приоритет, применяемый ко всем их составляющим процессам, когда окно верхнего уровня приложения находится на переднем плане.

Синтаксис

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

Параметры

topLevelWindow

Дескриптор окна верхнего уровня (HWND) приложения.

processHandleCount

Количество дескрипторов процесса в processHandleArray. Эту функцию можно вызывать за один раз, используя не более 32 дескрипторов. Присвойте этому параметру значение 0 , а для параметра processHandleArray задайте значение NULL , чтобы очистить предварительную конфигурацию повышения.

processHandleArray

Группа дескрипторов процесса, которые должны быть увеличены на переднем плане или деактивированы. Присвойте этому параметру значение NULL , а для параметра processHandleCount задайте значение 0 , чтобы очистить предварительную конфигурацию повышения.

Возвращаемое значение

Возвращает значение TRUE , если вызову удалось повысить уровень приложения, в противном случае — FALSE . SetAdditionalForegroundBoostProcesses задает код последней ошибки, чтобы приложение смогла вызвать GetLastError() для получения расширенных сведений в случае сбоя вызова (например, ERROR_INVALID_PARAMETER, ERROR_NOT_ENOUGH_MEMORY или ERROR_ACCESS_DENIED).

Эта функция принимает группу дескрипторов процесса, которые получают повышение или отмену переднего плана, когда переданный HWND верхнего уровня перемещается на передний план или фон соответственно. Всякий раз, когда переданный HWND верхнего уровня становится окном переднего плана, к процессам, переданным в массиве дескрипторов, также применяется повышение переднего плана. Аналогичное отключение происходит, когда HWND верхнего уровня перемещается в фоновый режим.

HWND верхнего уровня, передаваемый в эту функцию, должен принадлежать вызывающей процедуре. Вызывающий процесс должен иметь PROCESS_SET_INFORMATION доступ прямо к дескрипторам процесса в processHandleArray . Другими словами, вы должны иметь полный контроль над каждым окном в процессе. Если какой-либо внешний компонент внедряет окно, которое выходит на передний план, или если появляется диалоговое окно, вы потеряете повышение.

Если у вас два окна верхнего уровня, необходимо вызвать эту функцию для каждого из них.

Если переданный HWND верхнего уровня уже находится на переднем плане при вызове SetAdditionalForegroundBoostProcesses , все процессы в processHandleArray немедленно повышаются.

Процесс, дескриптор которого находится в processHandleArray , получит повышение переднего плана только в том случае, если HWND верхнего уровня становится окном переднего плана.

Дополнительное повышение переднего плана применяется только в том случае, если:

Изменяется окно переднего плана, или
Если эта функция вызывается, когда окно находится на переднем плане и новый список содержит дескриптор процесса, или список не включает дескриптор процесса, пока он был включен ранее.

Когда процесс, владеющий HWND верхнего уровня, завершается или завершается, дополнительная связь повышения разрывается, а вторичные процессы не получают никакого дополнительного повышения переднего плана.

HWND верхнего уровня основного процесса будет по-прежнему содержать ссылки на вторичные процессы, пока HWND верхнего уровня основного процесса не очистит свое сгруппированное состояние повышения или HWND не будет уничтожен.

Пример

В этом простом сценарии приложение настраивает конфигурацию повышения процесса переднего плана при создании окна верхнего уровня. При обработке WM_CREATE функция вызывается с дескрипторами в lParam и количеством дескрипторов в wParam. Эти процессы получают приоритет переднего плана или фона по мере того, как m_AppWindow перемещается в окно переднего плана и выходит из него. Если при вызове функции m_AppWindow является окном переднего плана, процессы также получат немедленное повышение приоритета переднего плана.

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;

Требования

Требование	Значение
Минимальная версия клиента	сборка Windows 11 22621
Верхняя часть	Winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll

См. также раздел

SetForegroundWindow

Поделиться через