Função SetAdditionalForegroundBoostProcesses (Winuser.h)

SetAdditionalForegroundBoostProcesses é uma API de assistência de desempenho para ajudar aplicativos com um modelo de aplicativo de vários processos em que vários processos contribuem para uma experiência em primeiro plano, como dados ou renderização. Os exemplos incluem navegadores (com o gerenciador de navegador ou quadro, guias, plug-ins etc. hospedados em processos diferentes) e IDEs (que geram processos para compilação e outras tarefas).

Os aplicativos podem usar essa API para fornecer um aumento de prioridade em primeiro plano para processos de trabalho que ajudam a dar suporte ao aplicativo main. Esses aplicativos podem ter um aumento de prioridade uniforme aplicado a todos os seus processos constituintes quando a janela de nível superior do aplicativo está em primeiro plano.

Sintaxe

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

Parâmetros

topLevelWindow

Um identificador para a HWND (janela de nível superior) do aplicativo.

processHandleCount

O número de identificadores de processo em processHandleArray. Essa função pode ser chamada em um único momento com um máximo de 32 identificadores. Defina esse parâmetro como 0 , juntamente com a configuração processHandleArray como NULL para limpar uma configuração de aumento anterior.

processHandleArray

Um grupo de identificadores de processo a serem impulsionados em primeiro plano ou desativados. Defina esse parâmetro como NULL juntamente com a configuração processHandleCount como 0 para limpar uma configuração de aumento anterior.

Retornar valor

Retornará TRUE se a chamada tiver êxito em impulsionar o aplicativo, caso contrário, FALSE . SetAdditionalForegroundBoostProcesses define o último código de erro, de modo que o aplicativo pode chamar GetLastError() para obter informações estendidas se a chamada falhar (por exemplo, ERROR_INVALID_PARAMETER, ERROR_NOT_ENOUGH_MEMORY ou ERROR_ACCESS_DENIED).

Comentários

Essa função usa um grupo de identificadores de processo que são todos impulsionados em primeiro plano ou desativados quando o HWND de nível superior passado é movido para o primeiro plano ou plano de fundo, respectivamente. Sempre que o HWND de nível superior passado se tornar a janela de primeiro plano, um aumento em primeiro plano também será aplicado aos processos passados na matriz de identificadores. Um desanexamento semelhante ocorre quando o HWND de nível superior se move para o plano de fundo.

O HWND de nível superior passado para essa função deve pertencer ao processo de chamada. O processo de chamada deve ter o acesso PROCESS_SET_INFORMATION diretamente nos identificadores de processo no processoHandleArray – em outras palavras, você deve ter controle total de cada janela em seu processo. Se algum componente externo injetar uma janela em primeiro plano ou se uma caixa de diálogo for exibida, você perderá o aumento.

Se você tiver duas janelas de nível superior, precisará chamar essa função para cada uma delas.

Se o HWND de nível superior passado já estiver em primeiro plano quando SetAdditionalForegroundBoostProcesses for chamado, todos os processos no processHandleArray serão imediatamente aumentados.

Um processo cujo identificador está no processoHandleArray obterá um aumento em primeiro plano somente quando o HWND de nível superior se tornar a janela de primeiro plano.

O aumento de primeiro plano adicional é aplicado somente quando:

1. A janela em primeiro plano é alterada ou
2. Se essa função for chamada enquanto a janela estiver em primeiro plano e a nova lista tiver o identificador de processo ou a lista não incluir o identificador de processo enquanto ela foi incluída anteriormente.

Quando o processo que possui o HWND de nível superior é encerrado, a relação de aumento adicional é interrompida e os processos secundários não recebem nenhum aumento de primeiro plano adicional.

O HWND de nível superior do processo primário continuará a manter referências a processos secundários até que o HWND de nível superior do processo primário limpe seu estado de aumento agrupado ou o HWND seja destruído.

Exemplo

Nesse cenário simples, o aplicativo configura sua configuração de aumento de processo em primeiro plano quando a janela de nível superior é criada. Quando WM_CREATE é tratado, a função é chamada com identificadores no lParam e a contagem de identificadores no wParam. Esses processos terão prioridade em primeiro plano ou em segundo plano aumentada à medida que m_AppWindow entrar e sair da janela em primeiro plano. Se o m_AppWindow for a janela em primeiro plano quando a função for chamada, os processos também receberão um aumento imediato de prioridade em primeiro plano.

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;

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 11 Build 22621
Cabeçalho	Winuser.h (inclui Windows.h)
Biblioteca	User32.lib
DLL	User32.dll

Confira também

Setforegroundwindow