Fungsi CoAllowSetForegroundWindow (objbase.h)

Artikel
03/15/2023

Fungsi ini melewati hak istimewa latar depan (hak istimewa untuk mengatur jendela latar depan) dari satu proses ke proses lainnya. Proses yang memiliki hak istimewa latar depan dapat memanggil fungsi ini untuk meneruskan hak istimewa tersebut ke proses server COM lokal. Perhatikan bahwa memanggil CoAllowSetForegroundWindow hanya menganugerahkan hak istimewa; itu tidak mengatur jendela latar depan itu sendiri. Latar depan dan fokus hanya diambil dari aplikasi klien ketika server COM target memanggil SetForegroundWindow atau API lain yang melakukannya secara tidak langsung.

Sintaks

HRESULT CoAllowSetForegroundWindow(
  [in] IUnknown *pUnk,
  [in] LPVOID   lpvReserved
);

Parameter

[in] pUnk

Penunjuk ke antarmuka IUnknown pada proksi server COM target.

[in] lpvReserved

Parameter ini dicadangkan dan harus NULL.

Nilai kembali

Fungsi ini dapat mengembalikan nilai berikut.

Menampilkan kode	Deskripsi
S_OK	Metode berhasil.
E_INVALIDARG	Parameter lpvReserved bukan NULL.
E_NOINTERFACE	Parameter pUnk tidak mendukung kontrol jendela latar depan.
E_ACCESSDENIED	Proses panggilan saat ini tidak memiliki hak istimewa latar depan.

Keterangan

Sistem membatasi proses mana yang dapat memanggil fungsi SetForegroundWindow dan AllowSetForegroundWindow untuk mengatur jendela latar depan. Akibatnya, aplikasi diblokir untuk mencuri fokus dari aplikasi lain bahkan ketika pengguna berinteraksi dengannya. Gunakan CoAllowSetForegroundWindow untuk meneruskan hak istimewa latar depan dari proses yang memilikinya ke proses yang belum memilikinya. Ini dapat dilakukan secara transitif: meneruskan hak istimewa dari satu proses ke proses lain, dan kemudian ke proses lainnya, dan sebagainya.

CoAllowSetForegroundWindow memungkinkan pengguna yang memiliki antarmuka kustom untuk mendapatkan perilaku yang sama yang terjadi untuk antarmuka OLE di mana perubahan jendela diharapkan (terutama terkait dengan penautan dan penyematan).

Di balik layar, antarmuka IForegroundTransfer digunakan untuk menghasilkan jendela latar depan di antara proses. Proksi standar yang disediakan COM sudah mengimplementasikan IForegroundTransfer, sehingga Anda tidak perlu melakukan pekerjaan tambahan jika Anda menggunakan proksi standar. Cukup panggil CoAllowSetForegroundWindow untuk mentransfer hak istimewa latar depan ke objek COM yang tidak diproses.

Contoh

Contoh berikut menunjukkan bagaimana proses klien dapat membuat server COM lokal, memanggil CoAllowSetForegroundWindow untuk mentransfer hak istimewa latar depan, lalu memanggil fungsi di server COM yang pada gilirannya secara langsung atau tidak langsung memanggil SetForegroundWindow.

Microsoft::WRL::ComPtr<IExampleInterface> exampleLocalServer;

ThrowIfFailed(::CoCreateInstance(CLSID_ExampleLocalServer,
	nullptr, CLSCTX_LOCAL_SERVER, IID_PPV_ARGS(&exampleLocalServer)));

// You can adapt to success or failure, but don't automatically throw. Don’t make the
// opening of a window dependent on successfully passing privilege (and taking foreground),
// because the window will signal to the user that it is ready to take focus.
HRESULT hr = ::CoAllowSetForegroundWindow(exampleLocalServer.Get(), nullptr);

// Call an example method that itself calls ::SetForegroundWindow(HWND).
hr = exampleLocalServer->FunctionThatSetsForegroundWindow();

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	objbase.h
Pustaka	Ole32.lib
DLL	Ole32.dll
Set API	ext-ms-win-com-ole32-l1-1-1 (diperkenalkan dalam Windows 8.1)

Lihat juga

IForegroundTransfer

Bagikan melalui