SetAdditionalForegroundBoostProcesses 関数 (Winuser.h)

[アーティクル]
08/28/2023

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アクセス権が必要です。つまり、プロセス内のすべてのウィンドウを完全に制御する必要があります。一部の外部コンポーネントがフォアグラウンドを取るウィンドウを挿入した場合、またはダイアログボックスが表示された場合は、ブーストが失われます。

最上位のウィンドウが 2 つある場合は、それぞれに対してこの関数を呼び出す必要があります。

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
Header	Winuser.h (Windows.h を含む)
Library	User32.lib
[DLL]	User32.dll

こちらもご覧ください

SetForegroundWindow

次の方法で共有

SetAdditionalForegroundBoostProcesses 関数 (Winuser.h)

構文

パラメーター

戻り値

注釈

例

要件

こちらもご覧ください

フィードバック

その他のリソース