SetAdditionalForegroundBoostProcesses-Funktion (Winuser.h)
SetAdditionalForegroundBoostProcesses ist eine Leistungsunterstützungs-API, die Anwendungen mit einem Mehrprozessanwendungsmodell unterstützt, bei dem mehrere Prozesse zu einer Vordergrundumgebung beitragen, entweder als Daten oder als Rendering. Beispiele sind Browser (mit dem Browser-Manager oder -Frame, Registerkarten, Plug-Ins usw., die in verschiedenen Prozessen gehostet werden) und IDEs (die Prozesse für die Kompilierung und andere Aufgaben erzeugen).
Anwendungen können diese API verwenden, um Workerprozessen, die die Standard-Anwendung unterstützen, eine Prioritätserhöhung im Vordergrund bereitzustellen. Für solche Anwendungen kann eine einheitliche Prioritätserhöhung auf alle ihre bestandteileden Prozesse angewendet werden, wenn sich das Fenster der obersten Ebene der Anwendung im Vordergrund befindet.
Syntax
BOOL SetAdditionalForegroundBoostProcesses(
HWND topLevelWindow,
DWORD processHandleCount,
HANDLE *processHandleArray
);
Parameter
topLevelWindow
Ein Handle zum Fenster der obersten Ebene (HWND) der Anwendung.
processHandleCount
Die Anzahl der ProzesshandleArray-Handles. Diese Funktion kann zu einem einzigen Zeitpunkt mit maximal 32 Handles aufgerufen werden. Legen Sie diesen Parameter auf 0 fest, und legen Sie processHandleArray auf NULL fest, um eine vorherige Boostkonfiguration zu löschen.
processHandleArray
Eine Gruppe von Prozesshandles, die im Vordergrund verstärkt oder de-boosted werden sollen. Legen Sie diesen Parameter auf NULL fest, und legen Sie processHandleCount auf 0 fest, um eine vorherige Boostkonfiguration zu löschen.
Rückgabewert
Gibt TRUE zurück, wenn der Aufruf die Anwendung erfolgreich erhöht, andernfalls FALSE . SetAdditionalForegroundBoostProcesses legt den letzten Fehlercode fest, damit die Anwendung GetLastError() aufrufen kann, um erweiterte Informationen zu erhalten, wenn der Aufruf fehlgeschlagen ist (z. B. ERROR_INVALID_PARAMETER, ERROR_NOT_ENOUGH_MEMORY oder ERROR_ACCESS_DENIED).
Hinweise
Diese Funktion verwendet eine Gruppe von Prozesshandles, die alle den Vordergrund verstärken oder aufheben, wenn der übergebene HWND der obersten Ebene in den Vordergrund bzw. hintergrund verschoben wird. Wenn der übergebene HWND der obersten Ebene zum Vordergrundfenster wird, wird auch eine Vordergrundverstärkung auf die prozesse angewendet, die im Handle-Array übergeben werden. Eine ähnliche De-Boost-Einstellung tritt auf, wenn der HWND der obersten Ebene in den Hintergrund wechselt.
Der an diese Funktion übergebene HWND der obersten Ebene muss sich im Besitz des aufrufenden Prozesses befinden. Der aufrufende Prozess sollte über das PROCESS_SET_INFORMATION Zugriffsrecht auf die Prozesshandlearray-Handles verfügen. Das heißt, Sie müssen die vollständige Kontrolle über jedes Fenster in Ihrem Prozess haben. Wenn eine externe Komponente ein Fenster einschleust, das den Vordergrund einnimmt, oder wenn ein Dialogfeld angezeigt wird, verlieren Sie Ihren Boost.
Wenn Sie über zwei Fenster der obersten Ebene verfügen, müssen Sie diese Funktion für jedes aufrufen.
Wenn sich der übergebene HWND der obersten Ebene bereits im Vordergrund befindet, wenn SetAdditionalForegroundBoostProcesses aufgerufen wird, werden alle Prozesse im processHandleArray sofort verstärkt.
Ein Prozess, dessen Handle im processHandleArray enthalten ist, erhält nur dann eine Vordergrundverstärkung, wenn der HWND der obersten Ebene zum Vordergrundfenster wird.
Zusätzliche Vordergrundverstärkung wird nur angewendet, wenn:
- Das Vordergrundfenster ändert sich, oder
- Wenn diese Funktion aufgerufen wird, während sich das Fenster im Vordergrund befindet und die neue Liste über das Prozesshandle verfügt, oder die Liste enthält das Prozesshandle nicht, während es zuvor enthalten war.
Wenn der Prozess, der den HWND der obersten Ebene besitzt, beendet oder beendet wird, wird die zusätzliche Verstärkungsbeziehung abgerissen, und sekundäre Prozesse erhalten keine zusätzliche Vordergrundaufstufung.
Der HWND der obersten Ebene des primären Prozesses enthält weiterhin Verweise auf sekundäre Prozesse, bis entweder der HWND der obersten Ebene des primären Prozesses seinen gruppierten Boostzustand löscht oder der HWND zerstört wird.
Beispiel
In diesem einfachen Szenario richtet die Anwendung ihre Vordergrundprozessverstärkungskonfiguration ein, wenn das Fenster der obersten Ebene erstellt wird. Wenn WM_CREATE behandelt wird, wird die Funktion mit Handles im lParam und der Anzahl der Handles in der wParam aufgerufen. Diese Prozesse erhalten eine höhere Vordergrund- oder Hintergrundpriorität, wenn m_AppWindow in das Vordergrundfenster ein- und aus dem Fenster wechselt. Wenn die m_AppWindow das Vordergrundfenster ist, wenn die Funktion aufgerufen wird, erhalten die Prozesse auch eine sofortige Prioritätserhöhung im Vordergrund.
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;
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 11 Build 22621 |
| Kopfzeile | Winuser.h (einschließlich Windows.h) |
| Bibliothek | User32.lib |
| DLL | User32.dll |