CoAllowSetForegroundWindow function (objbase.h)

This function passes the foreground privilege (the privilege to set the foreground window) from one process to another. The process that has the foreground privilege can call this function to pass that privilege on to a local COM server process. Note that calling CoAllowSetForegroundWindow only confers the privilege; it does not set the foreground window itself. Foreground and focus are only taken away from the client application when the target COM server calls either SetForegroundWindow or another API that does so indirectly.


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


[in] pUnk

A pointer to the IUnknown interface on the proxy of the target COM server.

[in] lpvReserved

This parameter is reserved and must be NULL.

Return value

This function can return the following values.

Return code Description
The method was successful.
The lpvReserved parameter is not NULL.
The pUnk parameter does not support foreground window control.
The calling process does not currently possess the foreground privilege.


The system restricts which processes can call the SetForegroundWindow and AllowSetForegroundWindow functions to set the foreground window. As a result, an application is blocked from stealing the focus from another application even when the user is interacting with it. Use CoAllowSetForegroundWindow to pass on the foreground privilege from a process that has it to a process that does not yet have it. This can be done transitively: passing the privilege from one process to another, and then to another, and so on.

CoAllowSetForegroundWindow enables a user that has a custom interface to get the same behavior that happens for OLE interfaces where a change of window is expected (primarily associated with linking and embedding).

Behind the scenes, the IForegroundTransfer interface is used to yield the foreground window between processes. A standard COM-provided proxy already implements IForegroundTransfer, so you don't have to do any extra work if you're using a standard proxy. Just call CoAllowSetForegroundWindow to transfer the foreground privilege to any out-of-process COM object.


The following example demonstrates how a client process can create a local COM server, call CoAllowSetForegroundWindow to transfer the foreground privilege, and then call a function on the COM server that in turn directly or indirectly calls SetForegroundWindow.

Microsoft::WRL::ComPtr<IExampleInterface> 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();


Minimum supported client Windows 2000 Professional [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header objbase.h
Library Ole32.lib
DLL Ole32.dll
API set ext-ms-win-com-ole32-l1-1-1 (introduced in Windows 8.1)

See also