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 |
|---|---|
|
O método foi bem-sucedido. |
|
O parâmetro lpvReserved não é NULL. |
|
O parâmetro pUnk não dá suporte ao controle de janela em primeiro plano. |
|
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) |