Função RpcServerSubscribeForNotification (rpcasync.h)
A função RpcServerSubscribeForNotification assina o servidor para notificações de RPC.
Sintaxe
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 estrutura que contém o identificador de associação para a chamada atual. Se essa função for chamada no mesmo thread em que o RPC enviou uma chamada, esse parâmetro poderá ser definido como NULL; caso contrário, um identificador de associação explícito deve ser passado nesse parâmetro.
[in] Notification
Combinação bit a bit dos valores de enumeração RPC_NOTIFICATIONS que especifica o tipo de notificação solicitada do RPC pelo servidor.
Windows Vista: Atualmente, há suporte apenas para RpcNotificationClientDisconnect e RpcNotificationCallCancel . Se qualquer outro valor for especificado para esse parâmetro, o código de erro RPC_S_CANNOT_SUPPORT será retornado.
[in] NotificationType
RPC_NOTIFICATION_TYPES valor de enumeração que especifica o método pelo qual o RPC notificará o servidor.
Windows Vista: não há suporte para RpcNotificationTypeNone. Se esse valor for especificado, o código de erro RPC_S_INVALID_ARG será retornado.
[in] NotificationInfo
Ponteiro para uma união RPC_ASYNC_NOTIFICATION_INFO que contém as informações específicas necessárias para que o RPC entre em contato com o servidor para notificação. Os dados contidos nessa união são específicos para o método passado para o parâmetro NotificationType .
Se o método RpcNotificationTypeCallback for especificado em NotificationTypes, o membro NotificationRoutine do branch correspondente da união será definido como o identificador de associação para chamadas síncronas e o identificador assíncrono para chamadas assíncronas.
O RPC faz uma cópia desse parâmetro durante uma chamada bem-sucedida para essa função. O chamador pode liberar ou atualizar esse parâmetro quando a API retorna.
Retornar valor
Essa função retorna RPC_S_OK em caso de êxito; caso contrário, um código de erro RPC_S_* será retornado.
Comentários
Se o chamador especificar qualquer tipo de notificação diferente de RpcNotificationTypeEvent, ele poderá assinar as notificações RpcNotificationClientDisconnect e RpcNotificationCallCancel com uma única chamada. Para eventos, duas chamadas separadas para essa API são necessárias.
O aplicativo de servidor deve cancelar a assinatura para notificação antes que a chamada RPC seja concluída. Se a chamada RPC for síncrona, ela será concluída quando o servidor enviar um valor retornado ao RPC. Se a chamada RPC for assíncrona, ela será concluída quando o servidor chamar RpcAsyncCompleteCall ou RpcAsyncAbortCall ou gerar uma exceção da rotina do gerenciador. Se o servidor não conseguir cancelar a assinatura da chamada status notificações de alteração, os resultados serão indefinidos e o servidor poderá falhar posteriormente. Observe que a assinatura se aplica apenas a uma chamada RPC. Se o aplicativo de servidor precisar monitorar mais de uma chamada, ele precisará assinar cada chamada especificamente.
O aplicativo de servidor pode esperar que ele não seja sinalizado para notificações para as quais não se inscreveu. Se ele tiver assinado mais de uma notificação, cada notificação será comunicada ao método de conclusão se o método de conclusão selecionado permitir. Se não permitir a comunicação de notificações, o aplicativo de servidor poderá chamar as APIs do servidor RPC para testar se o cliente cancelou ou desconectou ou não. A tabela a seguir indica como o tipo de notificação (cancelamento de chamada ou desconexão do cliente) é comunicado a cada método de notificação:
| Método Notification | Tipo de evento/notificação |
|---|---|
| RpcNotificationTypeNone | Não permitido para assinatura. |
| RpcNotificationTypeEvent | O tipo de notificação não está disponível. |
| RpcNotificationTypeApc | O tipo de notificação é encontrado no parâmetro Event da função APC. |
| RpcNotificationTypeIoc | O tipo de notificação não está disponível. |
| RpcNotificationTypeCallback | O tipo de notificação é encontrado no parâmetro Event da função de retorno de chamada. |
Observe que a tabela não implica se um chamador pode ou não assinar notificações usando o método de notificação determinado; em vez disso, ele simplesmente declara as informações que o chamador pode obter quando a notificação é recebida, como o tipo de notificação.
O chamador deve sincronizar entre RpcServerSubscribeForNotification e RpcServerUnsubscribeForNotification no mesmo identificador de associação. Se forem chamados simultaneamente, os resultados serão indefinidos e poderão incorrer em notificações perdidas, notificações extras, uma contagem incorreta de notificações, falhas de processo, dados corrompidos e vazamentos de memória. A mesma preocupação se aplica a threads que chamam RpcServerSubscribeForNotification no mesmo identificador de associação.
Chamar RpcServerSubscribeForNotification e RpcServerUnsubscribeForNotification no mesmo identificador de associação é thread-safe. Para notificações atuais, o RPC notificará o servidor no máximo uma vez por chamada.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows Vista, Windows XP com SP2 [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008, Windows Server 2003 com SP1 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | rpcasync.h (inclua Rpc.h) |
| Biblioteca | Rpcrt4.lib |
| DLL | Rpcrt4.dll |