Funzione SetAdditionalForegroundBoostProcesses (Winuser.h)
SetAdditionalForegroundBoostProcesses è un'API di supporto per le prestazioni che consente alle applicazioni con un modello di applicazione multiprocesso in cui più processi contribuiscono a un'esperienza in primo piano, come dati o rendering. Gli esempi includono browser (con gestione browser o frame, schede, plug-in e così via ospitati in processi diversi) e IDE (che generano processi per la compilazione e altre attività).
Le applicazioni possono usare questa API per fornire un aumento della priorità in primo piano per i processi di lavoro che supportano l'applicazione principale. Tali applicazioni possono avere un incremento di priorità uniforme applicato a tutti i processi costitutivi quando la finestra di primo livello dell'applicazione è in primo piano.
Sintassi
BOOL SetAdditionalForegroundBoostProcesses(
HWND topLevelWindow,
DWORD processHandleCount,
HANDLE *processHandleArray
);
Parametri
topLevelWindow
Handle per la finestra di primo livello (HWND) dell'applicazione.
processHandleCount
Numero di handle di processo in processHandleArray. Questa funzione può essere chiamata in un'unica volta con un massimo di 32 handle. Impostare questo parametro su 0 insieme all'impostazione di processHandleArray su NULL per cancellare una configurazione boost precedente.
processHandleArray
Un gruppo di handle di processo da aumentare o de-boosting in primo piano. Impostare questo parametro su NULL insieme all'impostazione di processHandleCount su 0 per cancellare una configurazione con boost precedente.
Valore restituito
Restituisce TRUE se la chiamata ha esito positivo nell'aumento dell'applicazione, FALSE in caso contrario. SetAdditionalForegroundBoostProcesses imposta l'ultimo codice di errore, in modo che l'applicazione possa chiamare GetLastError() per ottenere informazioni estese se la chiamata non è riuscita, ad esempio ERROR_INVALID_PARAMETER, ERROR_NOT_ENOUGH_MEMORY o ERROR_ACCESS_DENIED.
Commenti
Questa funzione accetta un gruppo di handle di processo che tutti vengono incrementati in primo piano o de-boosted quando il valore HWND di primo livello passato passa rispettivamente in primo piano o in background. Ogni volta che il valore HWND di primo livello passato diventa la finestra in primo piano, verrà applicato anche un boost in primo piano ai processi passati nella matrice di handle. Un de-boost simile si verifica quando il livello superiore HWND passa allo sfondo.
Il valore HWND di primo livello passato a questa funzione deve essere di proprietà del processo chiamante. Il processo chiamante deve avere il diritto di accesso PROCESS_SET_INFORMATION sugli handle del processo in processHandleArray . In altre parole, è necessario avere il controllo completo di ogni finestra del processo. Se un componente esterno inserisce una finestra in primo piano o se viene visualizzata una finestra di dialogo, perdere la spinta.
Se sono presenti due finestre di primo livello, è necessario chiamare questa funzione per ognuna di esse.
Se il valore HWND di primo livello passato è già in primo piano quando viene chiamato SetAdditionalForegroundBoostProcesses , tutti i processi nel processHandleArray vengono immediatamente incrementati.
Un processo il cui handle si trova in processHandleArray otterrà un boost in primo piano solo quando il valore HWND di primo livello diventa la finestra in primo piano.
Il boost in primo piano aggiuntivo viene applicato solo quando:
- La finestra in primo piano cambia o
- Se questa funzione viene chiamata mentre la finestra è in primo piano e il nuovo elenco ha l'handle di processo oppure l'elenco non include l'handle di processo mentre è stato incluso in precedenza.
Quando il processo proprietario del livello superiore HWND esce o termina, la relazione di boosting aggiuntiva viene interrotta e i processi secondari non ricevono alcun ulteriore boosting in primo piano.
L'HWND di livello principale del processo primario continuerà a contenere riferimenti ai processi secondari fino a quando HWND del processo primario non cancella lo stato di boost raggruppato o l'HWND non viene eliminato definitivamente.
Esempio
In questo semplice scenario, l'applicazione configura la configurazione di boost del processo in primo piano quando viene creata la finestra di primo livello. Quando WM_CREATE viene gestito, la funzione viene chiamata con handle in lParam e il conteggio degli handle in wParam. Questi processi verranno incrementati in primo piano o priorità in background man mano che m_AppWindow si sposta all'interno e all'esterno della finestra in primo piano. Se il m_AppWindow è la finestra in primo piano quando viene chiamata la funzione, i processi otterranno anche un incremento immediato della priorità in primo piano.
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;
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 11 Build 22621 |
| Intestazione | Winuser.h (include Windows.h) |
| Libreria | User32.lib |
| DLL | User32.dll |