Funzione CoAllowSetForegroundWindow (objbase.h)

Articolo
02/29/2024

Questa funzione passa il privilegio primo piano (il privilegio per impostare la finestra in primo piano) da un processo a un altro. Il processo con privilegi in primo piano può chiamare questa funzione per passare tale privilegio a un processo del server COM locale. Si noti che la chiamata a CoAllowSetForegroundWindow conferisce solo il privilegio; non imposta la finestra in primo piano. Il primo piano e lo stato attivo vengono sottratti dall'applicazione client solo quando il server COM di destinazione chiama SetForegroundWindow o un'altra API che lo fa indirettamente.

Sintassi

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

Parametri

[in] pUnk

Puntatore all'interfaccia IUnknown nel proxy del server COM di destinazione.

[in] lpvReserved

Questo parametro è riservato e deve essere NULL.

Valore restituito

Questa funzione può restituire i valori seguenti.

Codice restituito	Descrizione
S_OK	Il metodo è stato eseguito correttamente.
E_INVALIDARG	Il parametro lpvReserved non è NULL.
E_NOINTERFACE	Il parametro pUnk non supporta il controllo finestra in primo piano.
E_ACCESSDENIED	Il processo chiamante non dispone attualmente del privilegio in primo piano.

Commenti

Il sistema limita i processi che possono chiamare le funzioni SetForegroundWindow e AllowSetForegroundWindow per impostare la finestra in primo piano. Di conseguenza, un'applicazione viene impedita di rubare lo stato attivo da un'altra applicazione anche quando l'utente interagisce con esso. Usare CoAllowSetForegroundWindow per passare il privilegio in primo piano da un processo che lo contiene a un processo che non lo ha ancora. Questa operazione può essere eseguita in modo transitivo: passando il privilegio da un processo a un altro, quindi a un altro e così via.

CoAllowSetForegroundWindow consente a un utente con un'interfaccia personalizzata di ottenere lo stesso comportamento che si verifica per le interfacce OLE in cui è prevista una modifica della finestra (principalmente associata al collegamento e all'incorporamento).

Dietro le quinte, l'interfaccia IForegroundTransfer viene usata per restituire la finestra in primo piano tra i processi. Un proxy fornito da COM standard implementa già IForegroundTransfer, quindi non è necessario eseguire operazioni aggiuntive se si usa un proxy standard. È sufficiente chiamare CoAllowSetForegroundWindow per trasferire il privilegio in primo piano a qualsiasi oggetto COM out-of-process.

Esempio

L'esempio seguente illustra come un processo client può creare un server COM locale, chiamare CoAllowSetForegroundWindow per trasferire il privilegio in primo piano e quindi chiamare una funzione sul server COM che a sua volta chiama direttamente o indirettamente 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();

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	objbase.h
Libreria	Ole32.lib
DLL	Ole32.dll
Set di API	ext-ms-win-com-ole32-l1-1-1 (introdotto in Windows 8.1)

Vedi anche

IForegroundTransfer

Condividi tramite