Функция CoAllowSetForegroundWindow (objbase.h)

Статья
02/29/2024

Эта функция передает привилегию переднего плана (привилегию на настройку окна переднего плана) из одного процесса в другой. Процесс, имеющий привилегию переднего плана, может вызвать эту функцию, чтобы передать эту привилегию в локальный процесс COM-сервера. Обратите внимание, что вызов CoAllowSetForegroundWindow предоставляет только привилегии. оно не задает само окно переднего плана. Передний план и фокус удаляются от клиентского приложения только в том случае, если целевой COM-сервер вызывает метод SetForegroundWindow или другой API, который делает это косвенно.

Синтаксис

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

Параметры

[in] pUnk

Указатель на интерфейс IUnknown на прокси-сервере целевого COM-сервера.

[in] lpvReserved

Этот параметр зарезервирован и должен иметь значение NULL.

Возвращаемое значение

Эта функция может возвращать следующие значения.

Код возврата	Описание
S_OK	Метод выполнен успешно.
E_INVALIDARG	Параметр lpvReserved не имеет значения NULL.
E_NOINTERFACE	Параметр pUnk не поддерживает элемент управления окном переднего плана.
E_ACCESSDENIED	Вызывающий процесс в настоящее время не обладает привилегией переднего плана.

Система ограничивает, какие процессы могут вызывать функции SetForegroundWindow и AllowSetForegroundWindow , чтобы задать окно переднего плана. В результате приложение блокируется от кражи фокуса из другого приложения, даже если пользователь взаимодействует с ним. Используйте CoAllowSetForegroundWindow для передачи привилегии переднего плана от процесса, имеющего его, в процесс, у которого его еще нет. Это можно сделать транзитивно: передать привилегии из одного процесса в другой, а затем в другой и т. д.

CoAllowSetForegroundWindow позволяет пользователю с пользовательским интерфейсом получить то же поведение, что и для интерфейсов OLE, где ожидается изменение окна (в первую очередь связано с связыванием и внедрением).

Интерфейс IForegroundTransfer используется в фоновом режиме для создания окна переднего плана между процессами. Стандартный прокси-сервер, предоставляемый COM, уже реализует IForegroundTransfer, поэтому вам не нужно выполнять никаких дополнительных действий, если вы используете стандартный прокси-сервер. Просто вызовите CoAllowSetForegroundWindow , чтобы передать привилегию переднего плана любому внепроцессный COM-объект.

Примеры

В следующем примере показано, как клиентский процесс может создать локальный COM-сервер, вызвать CoAllowSetForegroundWindow для передачи привилегии переднего плана, а затем вызвать функцию на COM-сервере, которая, в свою очередь, прямо или косвенно вызывает 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();

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	objbase.h
Библиотека	Ole32.lib
DLL	Ole32.dll
Набор API	ext-ms-win-com-ole32-l1-1-1 (появилось в Windows 8.1)

См. также раздел

IForegroundTransfer

Поделиться через