Función RpcServerSubscribeForNotification (rpcasync.h)

La función RpcServerSubscribeForNotification suscribe el servidor para las notificaciones RPC.

Sintaxis

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

Parámetros

[in] Binding

RPC_BINDING_HANDLE estructura que contiene el identificador de enlace de la llamada actual. Si se llama a esta función en el mismo subproceso en el que RPC ha enviado una llamada, este parámetro se puede establecer en NULL; de lo contrario, se debe pasar un identificador de enlace explícito en este parámetro.

[in] Notification

Combinación bit a bit de los valores de enumeración de RPC_NOTIFICATIONS que especifica el tipo de notificación solicitada desde RPC por el servidor.

Windows Vista: Actualmente, solo se admiten RpcNotificationClientDisconnect y RpcNotificationCallCancel . Si se especifica cualquier otro valor para este parámetro, se devuelve el código de error RPC_S_CANNOT_SUPPORT.

[in] NotificationType

RPC_NOTIFICATION_TYPES valor de enumeración que especifica el método por el que RPC notificará al servidor.

Windows Vista: RpcNotificationTypeNone no se admite. Si se especifica este valor, se devuelve el RPC_S_INVALID_ARG código de error.

[in] NotificationInfo

Puntero a una unión de RPC_ASYNC_NOTIFICATION_INFO que contiene la información específica necesaria para que RPC se comunique con el servidor para la notificación. Los datos contenidos en esta unión son específicos del método pasado al parámetro NotificationType .

Si el método RpcNotificationTypeCallback se especifica en NotificationTypes, el miembro NotificationRoutine de la rama correspondiente de la unión se establece en el identificador de enlace para las llamadas sincrónicas y el identificador asincrónico para las llamadas asincrónicas.

RPC realiza una copia de este parámetro durante una llamada correcta a esta función. El autor de la llamada puede liberar o actualizar este parámetro cuando se devuelve la API.

Valor devuelto

Esta función devuelve RPC_S_OK si se realiza correctamente; De lo contrario, se devuelve un código de error RPC_S_*.

Nota Para obtener una lista de códigos de error válidos, consulte Rpc Return Values.

 

Comentarios

Si el autor de la llamada especifica cualquier tipo de notificación distinto de RpcNotificationTypeEvent, puede suscribirse a las notificaciones RpcNotificationClientDisconnect y RpcNotificationCallCancel con una sola llamada. En el caso de los eventos, se requieren dos llamadas independientes a esta API.

La aplicación de servidor debe cancelar la suscripción a la notificación antes de que se complete la llamada RPC. Si la llamada RPC es sincrónica, se completa cuando el servidor envía un valor devuelto a RPC. Si la llamada RPC es asincrónica, se completa cuando el servidor llama a RpcAsyncCompleteCall o RpcAsyncAbortCall, o inicia una excepción de la rutina del administrador. Si el servidor no cancela la suscripción a las notificaciones de cambio de estado de llamada, los resultados no están definidos y el servidor puede bloquearse más adelante. Tenga en cuenta que la suscripción solo se aplica a una llamada RPC. Si la aplicación de servidor necesita supervisar más de una llamada, debe suscribirse específicamente a cada llamada.

La aplicación de servidor puede esperar que no se indique para las notificaciones para las que no se ha suscrito. Si se ha suscrito para más de una notificación, cada notificación se comunica al método de finalización si el método de finalización seleccionado lo permite. Si no permite la comunicación de notificaciones, la aplicación de servidor puede llamar a en las API del servidor RPC para probar si el cliente ha cancelado o desconectado. En la tabla siguiente se indica cómo se comunica el tipo de notificación (llamada cancelación o desconexión de cliente) a cada método de notificación:

Notification (método)	Tipo de evento o notificación
RpcNotificationTypeNone	No se permite para la suscripción.
RpcNotificationTypeEvent	El tipo de notificación no está disponible.
RpcNotificationTypeApc	El tipo de notificación se encuentra en el parámetro Event de la función APC.
RpcNotificationTypeIoc	El tipo de notificación no está disponible.
RpcNotificationTypeCallback	El tipo de notificación se encuentra en el parámetro Event de la función de devolución de llamada.

 

Tenga en cuenta que la tabla no implica si un autor de la llamada puede suscribirse o no a las notificaciones mediante el método de notificación especificado; en su lugar, simplemente indica la información que el autor de la llamada puede obtener cuando se recibe la notificación, como el tipo de notificación.

El llamador debe sincronizarse entre RpcServerSubscribeForNotification y RpcServerUnsubscribeForNotification en el mismo identificador de enlace. Si se llama simultáneamente, los resultados no están definidos y podrían incurrir en notificaciones perdidas, notificaciones adicionales, un recuento de notificaciones incorrecto, bloqueos de procesos, daños en los datos y pérdidas de memoria. La misma preocupación se aplica a los subprocesos que llaman a RpcServerSubscribeForNotification en el mismo identificador de enlace.

Llamar a RpcServerSubscribeForNotification y RpcServerUnsubscribeForNotification en el mismo identificador de enlace es seguro para subprocesos. En el caso de las notificaciones actuales, RPC notificará al servidor no más de una vez por llamada.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista, Windows XP con SP2 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2008, Windows Server 2003 con SP1 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	rpcasync.h (incluir Rpc.h)
Library	Rpcrt4.lib
Archivo DLL	Rpcrt4.dll

Consulte también

RpcServerUnsubscribeForNotification