CoAllowSetForegroundWindow, fonction (objbase.h)

Article
02/29/2024

Cette fonction transmet le privilège de premier plan (le privilège permettant de définir la fenêtre de premier plan) d’un processus à un autre. Le processus qui dispose du privilège de premier plan peut appeler cette fonction pour passer ce privilège à un processus serveur COM local. Notez que l’appel de CoAllowSetForegroundWindow confère uniquement le privilège ; elle ne définit pas la fenêtre de premier plan elle-même. Le premier plan et le focus ne sont retirés de l’application cliente que lorsque le serveur COM cible appelle SetForegroundWindow ou une autre API qui le fait indirectement.

Syntaxe

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

Paramètres

[in] pUnk

Pointeur vers l’interface IUnknown sur le proxy du serveur COM cible.

[in] lpvReserved

Ce paramètre est réservé et doit être NULL.

Valeur retournée

Cette fonction peut retourner les valeurs suivantes.

Code de retour	Description
S_OK	La méthode a réussi.
E_INVALIDARG	Le paramètre lpvReserved n’est pas NULL.
E_NOINTERFACE	Le paramètre pUnk ne prend pas en charge le contrôle de fenêtre de premier plan.
E_ACCESSDENIED	Le processus appelant ne possède pas actuellement le privilège de premier plan.

Remarques

Le système restreint les processus pouvant appeler les fonctions SetForegroundWindow et AllowSetForegroundWindow pour définir la fenêtre de premier plan. Par conséquent, une application ne peut pas voler le focus d’une autre application, même lorsque l’utilisateur interagit avec elle. Utilisez CoAllowSetForegroundWindow pour passer le privilège de premier plan d’un processus qui l’a à un processus qui ne l’a pas encore. Cela peut être effectué de manière transitive : passer le privilège d’un processus à un autre, puis à un autre, et ainsi de suite.

CoAllowSetForegroundWindow permet à un utilisateur disposant d’une interface personnalisée d’obtenir le même comportement que celui qui se produit pour les interfaces OLE où un changement de fenêtre est attendu (principalement associé à la liaison et à l’incorporation).

En arrière-plan, l’interface IForegroundTransfer est utilisée pour générer la fenêtre de premier plan entre les processus. Un proxy fourni par COM standard implémente déjà IForegroundTransfer, de sorte que vous n’avez pas à effectuer de travail supplémentaire si vous utilisez un proxy standard. Appelez simplement CoAllowSetForegroundWindow pour transférer le privilège de premier plan vers n’importe quel objet COM hors processus.

Exemples

L’exemple suivant montre comment un processus client peut créer un serveur COM local, appeler CoAllowSetForegroundWindow pour transférer le privilège de premier plan, puis appeler une fonction sur le serveur COM qui appelle à son tour directement ou indirectement 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();

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	objbase.h
Bibliothèque	Ole32.lib
DLL	Ole32.dll
Ensemble d’API	ext-ms-win-com-ole32-l1-1-1 (introduit dans Windows 8.1)

Voir aussi

IForegroundTransfer

Partager via