Функция RpcServerSubscribeForNotification (rpcasync.h)

Статья
03/15/2023

Функция RpcServerSubscribeForNotification подписывает сервер на уведомления RPC.

Синтаксис

RPC_STATUS RpcServerSubscribeForNotification(
  [in] RPC_BINDING_HANDLE          Binding,
  [in] RPC_NOTIFICATIONS           Notification,
  [in] RPC_NOTIFICATION_TYPES      NotificationType,
  [in] RPC_ASYNC_NOTIFICATION_INFO *NotificationInfo
);

Параметры

[in] Binding

RPC_BINDING_HANDLE структуры, содержащей дескриптор привязки для текущего вызова. Если эта функция вызывается в том же потоке, в который RPC отправил вызов, для этого параметра можно задать значение NULL; В противном случае в этом параметре должен быть передан явный дескриптор привязки.

[in] Notification

Побитовое сочетание значений перечисления RPC_NOTIFICATIONS , указывающее тип уведомления, запрошенного сервером из RPC.

Windows Vista: В настоящее время поддерживаются только RpcNotificationClientDisconnect и RpcNotificationCallCancel . Если для этого параметра указано любое другое значение, возвращается код ошибки RPC_S_CANNOT_SUPPORT.

[in] NotificationType

RPC_NOTIFICATION_TYPES значение перечисления , указывающее метод, с помощью которого RPC будет уведомлять сервер.

Windows Vista: RpcNotificationTypeNone не поддерживается. Если это значение указано, возвращается код ошибки RPC_S_INVALID_ARG.

[in] NotificationInfo

Указатель на RPC_ASYNC_NOTIFICATION_INFO объединение, содержащее конкретные сведения, необходимые для связи RPC с сервером для уведомления. Данные, содержащиеся в этом объединении, относятся к методу, передаваемого в параметр NotificationType .

Если метод RpcNotificationTypeCallback указан в NotificationTypes, то члену NotificationRoutine соответствующей ветви объединения присваивается дескриптор привязки для синхронных вызовов и асинхронный дескриптор для асинхронных вызовов.

RPC создает копию этого параметра во время успешного вызова этой функции. Вызывающий объект может освободить или обновить этот параметр при возврате API.

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

Эта функция возвращает RPC_S_OK об успешном выполнении; в противном случае возвращается код ошибки RPC_S_*.

Примечание Список допустимых кодов ошибок см. в разделе Возвращаемые значения RPC.

Если вызывающий объект указывает любой тип уведомления, отличный от RpcNotificationTypeEvent, он может подписаться на уведомления RpcNotificationClientDisconnect и RpcNotificationCallCancel с помощью одного вызова. Для событий требуются два отдельных вызова этого API.

Серверное приложение должно отменить подписку на уведомление до завершения вызова RPC. Если вызов RPC является синхронным, он завершается, когда сервер отправляет возвращаемое значение в RPC. Если вызов RPC является асинхронным, он завершается, когда сервер вызывает RpcAsyncCompleteCall или RpcAsyncAbortCall или создает исключение из подпрограммы диспетчера. Если серверу не удается отменить подписку на уведомления об изменении состояния звонка, результаты не будут определены, и сервер может завершить работу позже. Обратите внимание, что подписка применяется только для одного вызова RPC. Если серверное приложение должно отслеживать несколько вызовов, оно должно подписаться на каждый вызов.

Серверное приложение может ожидать, что оно не будет получать уведомления, на которые оно не подписано. Если у него есть подписка на несколько уведомлений, каждое уведомление передается методу завершения, если выбранный метод завершения разрешает это. Если он не разрешает обмен уведомлениями, серверное приложение может вызвать API сервера RPC, чтобы проверить, был ли клиент отменен или отключен. В таблице ниже показано, как тип уведомления (отмена вызова или отключение клиента) передается каждому методу уведомления:

Метод уведомления	Тип события или уведомления
RpcNotificationTypeNone	Не разрешено для подписки.
RpcNotificationTypeEvent	Тип уведомления недоступен.
RpcNotificationTypeApc	Тип уведомления находится в параметре Event функции APC.
RpcNotificationTypeIoc	Тип уведомления недоступен.
RpcNotificationTypeCallback	Тип уведомления находится в параметре Event функции обратного вызова.

Обратите внимание, что таблица не подразумевает, может ли вызывающий объект подписаться на уведомления с помощью заданного метода уведомления. вместо этого в нем просто указывается информация, которую вызывающий объект может получить при получении уведомления, например тип уведомления.

Вызывающий объект должен синхронизироваться между RpcServerSubscribeForNotification и RpcServerUnsubscribeForNotification в одном дескрипторове привязки. Если они вызываются одновременно, результаты будут неопределенными и могут привести к потере уведомлений, дополнительным уведомлениям, неправильному количеству уведомлений, сбоям процесса, повреждению данных и утечкам памяти. Та же проблема относится к потокам, вызывающим RpcServerSubscribeForNotification в том же дескрипторове привязки.

Вызовы RpcServerSubscribeForNotification и RpcServerUnsubscribeForNotification в одном дескрипторове привязки являются потокобезопасны. Для текущих уведомлений RPC будет уведомлять сервер не более одного раза за каждый вызов.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista, Windows XP с пакетом обновления 2 (SP2) [только классические приложения]
Минимальная версия сервера	Windows Server 2008, Windows Server 2003 с пакетом обновления 1 (SP1) [только классические приложения]
Целевая платформа	Windows
Header	rpcasync.h (включая Rpc.h)
Библиотека	Rpcrt4.lib
DLL	Rpcrt4.dll

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

RpcServerUnsubscribeForNotification

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