SetAdditionalForegroundBoostProcesses 函式 (Winuser.h)
SetAdditionalForegroundBoostProcesses 是一種效能協助 API，可協助具有多進程應用程式模型的應用程式，其中多個進程會作為數據或轉譯提供前景體驗。 範例包括瀏覽器管理員或框架、索引標籤、外掛程式等瀏覽器 (，這些瀏覽器裝載於不同的進程) 和 IDE (，這些進程會繁衍編譯和其他工作) 。
應用程式可以使用此 API 為背景工作進程提供前景優先順序提升，以協助支援主要應用程式。 當應用程式的最上層視窗位於前景時，這類應用程式可以套用至其所有組成進程的統一優先順序提升。
語法
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 必須由呼叫進程擁有。 呼叫進程應該在 processHandleArray 中的進程句柄上擁有PROCESS_SET_INFORMATION存取權，換句話說，您必須完全控制進程中的每個視窗。 如果某些外部元件插入採用前景的視窗，或出現對話框，則您會失去提升。
如果您有兩個最上層視窗，則必須為每個視窗呼叫此函式。
如果在呼叫 SetAdditionalForegroundBoostProcesses 時，傳入的最上層 HWND 已進入前景，則會立即提升 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 |