Função CoAllowSetForegroundWindow (objbase.h)

Essa função passa o privilégio de primeiro plano (o privilégio para definir a janela em primeiro plano) de um processo para outro. O processo que tem o privilégio de primeiro plano pode chamar essa função para passar esse privilégio para um processo de servidor COM local. Observe que chamar CoAllowSetForegroundWindow apenas confere o privilégio; ele não define a janela em primeiro plano em si. O primeiro plano e o foco só são retirados do aplicativo cliente quando o servidor COM de destino chama SetForegroundWindow ou outra API que faz isso indiretamente.

Sintaxe

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

Parâmetros

[in] pUnk

Um ponteiro para a interface IUnknown no proxy do servidor COM de destino.

[in] lpvReserved

Esse parâmetro é reservado e deve ser NULL.

Retornar valor

Essa função pode retornar os valores a seguir.

Código de retorno	Descrição
S_OK	O método foi bem-sucedido.
E_INVALIDARG	O parâmetro lpvReserved não é NULL.
E_NOINTERFACE	O parâmetro pUnk não dá suporte ao controle de janela em primeiro plano.
E_ACCESSDENIED	No momento, o processo de chamada não possui o privilégio de primeiro plano.

Comentários

O sistema restringe quais processos podem chamar as funções SetForegroundWindow e AllowSetForegroundWindow para definir a janela em primeiro plano. Como resultado, um aplicativo é impedido de roubar o foco de outro aplicativo mesmo quando o usuário está interagindo com ele. Use CoAllowSetForegroundWindow para passar o privilégio de primeiro plano de um processo que o tem para um processo que ainda não o tem. Isso pode ser feito transitivamente: passando o privilégio de um processo para outro e, em seguida, para outro e assim por diante.

CoAllowSetForegroundWindow permite que um usuário que tenha uma interface personalizada obtenha o mesmo comportamento que acontece para interfaces OLE em que uma alteração de janela é esperada (principalmente associada à vinculação e à inserção).

Nos bastidores, a interface IForegroundTransfer é usada para produzir a janela em primeiro plano entre os processos. Um proxy padrão fornecido por COM já implementa IForegroundTransfer, portanto, você não precisa fazer nenhum trabalho extra se estiver usando um proxy padrão. Basta chamar CoAllowSetForegroundWindow para transferir o privilégio de primeiro plano para qualquer objeto COM fora do processo.

Exemplos

O exemplo a seguir demonstra como um processo de cliente pode criar um servidor COM local, chamar CoAllowSetForegroundWindow para transferir o privilégio de primeiro plano e, em seguida, chamar uma função no servidor COM que, por sua vez, chama SetForegroundWindow direta ou indiretamente.

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();

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	objbase.h
Biblioteca	Ole32.lib
DLL	Ole32.dll
Conjunto de APIs	ext-ms-win-com-ole32-l1-1-1 (introduzido no Windows 8.1)

Confira também

IForegroundTransfer