Fungsi SetAdditionalForegroundBoostProcesses (Winuser.h)

Artikel
03/13/2024

SetAdditionalForegroundBoostProcesses adalah API bantuan performa untuk membantu aplikasi dengan model aplikasi multi-proses di mana beberapa proses berkontribusi pada pengalaman latar depan, baik sebagai data atau penyajian. Contohnya termasuk browser (dengan manajer browser atau bingkai, tab, plugin, dll. yang dihosting dalam proses yang berbeda) dan IDEs (yang menghasilkan proses untuk kompilasi dan tugas lainnya).

Aplikasi dapat menggunakan API ini untuk memberikan peningkatan prioritas latar depan ke proses pekerja yang membantu mendukung aplikasi utama. Aplikasi tersebut dapat memiliki peningkatan prioritas yang seragam yang diterapkan pada semua proses konstituen mereka ketika jendela tingkat atas aplikasi berada di latar depan.

Sintaks

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

Parameter

topLevelWindow

Handel ke jendela tingkat atas (HWND) aplikasi.

processHandleCount

Jumlah handel proses dalam processHandleArray. Fungsi ini dapat dipanggil pada satu waktu dengan maksimum 32 handel. Atur parameter ini ke 0 bersama dengan mengatur processHandleArray ke NULL untuk menghapus konfigurasi peningkatan sebelumnya.

processHandleArray

Sekelompok handel proses menjadi latar depan yang didorong atau ditolak. Atur parameter ini ke NULL bersama dengan mengatur processHandleCount ke 0 untuk menghapus konfigurasi peningkatan sebelumnya.

Nilai kembali

Mengembalikan TRUE jika panggilan berhasil meningkatkan aplikasi, FALSE jika tidak. SetAdditionalForegroundBoostProcesses mengatur kode kesalahan terakhir, sehingga aplikasi dapat memanggil GetLastError() untuk mendapatkan informasi yang diperluas jika panggilan gagal (misalnya, ERROR_INVALID_PARAMETER, ERROR_NOT_ENOUGH_MEMORY, atau ERROR_ACCESS_DENIED).

Keterangan

Fungsi ini mengambil sekelompok handel proses yang semuanya didorong atau ditolak latar depan ketika HWND tingkat atas yang diteruskan masing-masing bergerak ke latar depan atau latar belakang. Setiap kali HWND tingkat atas yang diteruskan menjadi jendela latar depan, peningkatan latar depan juga akan diterapkan pada proses yang diteruskan dalam array handel. De-boost serupa terjadi ketika HWND tingkat atas bergerak ke latar belakang.

HWND tingkat atas yang diteruskan ke fungsi ini harus dimiliki oleh proses panggilan. Proses panggilan harus memiliki akses PROCESS_SET_INFORMATION tepat pada handel proses dalam processHandleArray - dengan kata lain, Anda harus memiliki kontrol penuh atas setiap jendela dalam proses Anda. Jika beberapa komponen eksternal menyuntikkan jendela yang mengambil latar depan, atau jika kotak dialog muncul, maka Anda kehilangan peningkatan Anda.

Jika Anda memiliki dua jendela tingkat atas, Anda perlu memanggil fungsi ini untuk masing-masing jendela.

Jika HWND tingkat atas yang diteruskan sudah berada di latar depan ketika SetAdditionalForegroundBoostProcesses dipanggil, semua proses dalam processHandleArray segera ditingkatkan.

Proses yang handelnya ada di processHandleArray akan mendapatkan peningkatan latar depan hanya ketika HWND tingkat atas menjadi jendela latar depan.

Peningkatan latar depan tambahan hanya diterapkan saat:

Jendela latar depan berubah, atau
Jika fungsi ini dipanggil saat jendela berada di latar depan dan daftar baru memiliki handel proses, atau daftar tidak menyertakan handel proses saat sebelumnya disertakan.

Ketika proses yang memiliki HWND tingkat atas keluar atau berakhir, hubungan peningkatan tambahan dirobohkan dan proses sekunder tidak menerima peningkatan latar depan tambahan.

HWND tingkat atas proses utama akan terus menyimpan referensi ke proses sekunder sampai HWND tingkat atas proses utama menghapus status peningkatan yang dikelompokkan, atau HWND dihancurkan.

Contoh

Dalam skenario sederhana ini, aplikasi menyiapkan konfigurasi peningkatan proses latar depannya saat jendela tingkat atas dibuat. Ketika WM_CREATE ditangani, fungsi dipanggil dengan handel di lParam dan jumlah handel di wParam. Proses ini akan mendapatkan prioritas latar depan atau latar belakang yang ditingkatkan saat m_AppWindow bergerak masuk dan keluar dari jendela latar depan. Jika m_AppWindow adalah jendela latar depan ketika fungsi dipanggil, proses juga akan mendapatkan peningkatan prioritas latar depan langsung.

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;

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 11 Build 22621
Header	Winuser.h (termasuk Windows.h)
Pustaka	User32.lib
DLL	User32.dll

Lihat juga

SetForegroundWindow

Bagikan melalui