RpcServerSubscribeForNotification 函数 (rpcasync.h)

  • 项目

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 参数的方法。

如果在 NotificationTypes 中指定 RpcNotificationTypeCallback 方法，则联合的相应分支的 NotificationRoutine 成员将设置为同步调用的绑定句柄和异步调用的异步句柄。

RPC 在成功调用此函数期间复制此参数。 当 API 返回时，调用方可以释放或更新此参数。

返回值

此函数在成功时返回RPC_S_OK;否则，将返回RPC_S_* 错误代码。

注意 有关有效错误代码的列表，请参阅 RPC 返回值。
 

注解

如果调用方指定 RpcNotificationTypeEvent 以外的任何通知类型，则它可以通过单个调用订阅 RpcNotificationClientDisconnect 和 RpcNotificationCallCancel 通知。 对于事件，需要对此 API 进行两次单独调用。

在 RPC 调用完成之前，服务器应用程序必须取消订阅通知。 如果 RPC 调用是同步的，则服务器将返回值发送到 RPC 时完成。 如果 RPC 调用是异步的，则在服务器调用 RpcAsyncCompleteCall 或 RpcAsyncAbortCall 或从管理器例程引发异常时完成。 如果服务器未能取消订阅呼叫状态更改通知，则结果为未定义，服务器可能会在以后崩溃。 请注意，订阅仅适用于一次 RPC 调用。 如果服务器应用程序需要监视多个调用，则需要专门订阅每个调用。

服务器应用程序预期不会针对尚未订阅的通知发出信号。 如果已订阅多个通知，则如果所选完成方法允许，则会将每个通知传达给完成方法。 如果它不允许通知通信，服务器应用程序可以在 RPC 服务器 API 上调用，以测试客户端是否已取消或断开连接。 下表指示通知类型 (调用取消或客户端断开连接) 如何传达给每个通知方法：

通知方法 事件/通知类型
RpcNotificationTypeNone 不允许订阅。
RpcNotificationTypeEvent 通知类型不可用。
RpcNotificationTypeApc 通知类型位于 APC 函数的 Event 参数中。
RpcNotificationTypeIoc 通知类型不可用。
RpcNotificationTypeCallback 通知类型位于回调函数的 Event 参数中。
 

请注意，该表并不表示调用方是否可以使用给定通知方法订阅通知;相反，它只是声明调用方在收到通知时可以获取的信息，例如通知类型。

调用方必须在同一绑定句柄上的 RpcServerSubscribeForNotification 和 RpcServerUnsubscribeForNotification 之间同步。 如果同时调用它们，则结果未定义，并可能导致丢失通知、额外的通知、不正确的通知计数、进程崩溃、数据损坏和内存泄漏。 同样的关注点适用于在同一绑定句柄上调用 RpcServerSubscribeForNotification 的线程。

在同一绑定句柄上调用 RpcServerSubscribeForNotification 和 RpcServerUnsubscribeForNotification 是线程安全的。 对于当前通知，RPC 每次调用通知服务器不超过一次。

要求

要求 值
最低受支持的客户端 Windows Vista、Windows XP 和 SP2 [仅限桌面应用]
最低受支持的服务器 Windows Server 2008、Windows Server 2003 SP1 [仅限桌面应用]
目标平台 Windows
标头 rpcasync.h (包括 Rpc.h)
Library Rpcrt4.lib
DLL Rpcrt4.dll

另请参阅

RpcServerUnsubscribeForNotification