Funzione RpcServerSubscribeForNotification (rpcasync.h)
La funzione RpcServerSubscribeForNotification sottoscrive il server per le notifiche RPC.
Sintassi
RPC_STATUS RpcServerSubscribeForNotification(
[in] RPC_BINDING_HANDLE Binding,
[in] RPC_NOTIFICATIONS Notification,
[in] RPC_NOTIFICATION_TYPES NotificationType,
[in] RPC_ASYNC_NOTIFICATION_INFO *NotificationInfo
);
Parametri
[in] Binding
RPC_BINDING_HANDLE struttura che contiene l'handle di associazione per la chiamata corrente. Se questa funzione viene chiamata nello stesso thread in cui RPC ha inviato una chiamata, questo parametro può essere impostato su NULL; in caso contrario, è necessario passare un handle di associazione esplicito in questo parametro.
[in] Notification
Combinazione bit per bit dei valori di enumerazione RPC_NOTIFICATIONS che specifica il tipo di notifica richiesto da RPC dal server.
Windows Vista: Attualmente sono supportati solo RpcNotificationClientDisconnect e RpcNotificationCallCancel . Se per questo parametro viene specificato qualsiasi altro valore, viene restituito il codice di errore RPC_S_CANNOT_SUPPORT.
[in] NotificationType
RPC_NOTIFICATION_TYPES valore di enumerazione che specifica il metodo in base al quale RPC notificherà il server.
Windows Vista: RpcNotificationTypeNone non è supportato. Se questo valore viene specificato, viene restituito il codice di errore RPC_S_INVALID_ARG.
[in] NotificationInfo
Puntatore a un'unione RPC_ASYNC_NOTIFICATION_INFO contenente le informazioni specifiche necessarie per RPC per contattare il server per la notifica. I dati contenuti in questa unione sono specifici del metodo passato al parametro NotificationType .
Se il metodo RpcNotificationTypeCallback viene specificato in NotificationTypes, il membro NotificationRoutine del ramo corrispondente dell'unione viene impostato sul handle di associazione per le chiamate sincrone e l'handle asincrono per le chiamate asincrone.
RPC esegue una copia di questo parametro durante una chiamata riuscita a questa funzione. Il chiamante può liberare o aggiornare questo parametro quando l'API restituisce.
Valore restituito
Questa funzione restituisce RPC_S_OK in caso di esito positivo; in caso contrario, viene restituito un codice di errore RPC_S_* .
Commenti
Se il chiamante specifica qualsiasi tipo di notifica diverso da RpcNotificationTypeEvent, può sottoscrivere sia le notifiche RpcNotificationClientDisconnect che RpcNotificationCallCancel con una singola chiamata. Per gli eventi, sono necessarie due chiamate separate a questa API.
L'applicazione server deve annullare la sottoscrizione per la notifica prima del completamento della chiamata RPC. Se la chiamata RPC è sincrona, viene completata quando il server invia un valore restituito a RPC. Se la chiamata RPC è asincrona, viene completata quando il server chiama RpcAsyncCompleteCall o RpcAsyncAbortCall o genera un'eccezione dalla routine di gestione. Se il server non riesce a annullare la sottoscrizione per le notifiche di modifica dello stato della chiamata, i risultati non sono definiti e il server potrebbe arrestarsi in un secondo momento. Si noti che la sottoscrizione si applica solo per una chiamata RPC. Se l'applicazione server deve monitorare più chiamate, deve sottoscrivere ogni chiamata in modo specifico.
L'applicazione server può prevedere che non venga segnalato per le notifiche per cui non è stato sottoscritto. Se ha sottoscritto più di una notifica, ogni notifica viene comunicata al metodo di completamento se il metodo di completamento selezionato lo consente. Se non consente la comunicazione delle notifiche, l'applicazione server può chiamare le API del server RPC per verificare se il client è stato annullato o disconnesso. La tabella seguente indica come viene comunicato il tipo di notifica (annullamento chiamata o disconnessione client) a ogni metodo di notifica:
| Metodo di notifica | Tipo di evento/notifica |
|---|---|
| RpcNotificationTypeNone | Non consentito per la sottoscrizione. |
| RpcNotificationTypeEvent | Il tipo di notifica non è disponibile. |
| RpcNotificationTypeApc | Il tipo di notifica viene trovato nel parametro Event della funzione APC. |
| RpcNotificationTypeIoc | Il tipo di notifica non è disponibile. |
| RpcNotificationTypeCallback | Il tipo di notifica viene trovato nel parametro Event della funzione di callback. |
Si noti che la tabella non implica se un chiamante può sottoscrivere le notifiche usando il metodo di notifica specificato; invece indica semplicemente le informazioni che il chiamante può ottenere quando viene ricevuta la notifica, ad esempio il tipo di notifica.
Il chiamante deve sincronizzare tra RpcServerSubscribeForNotification e RpcServerUnsubscribeForNotification nello stesso handle di associazione. Se vengono chiamati simultaneamente, i risultati non sono definiti e potrebbero comportare notifiche perse, notifiche aggiuntive, un conteggio di notifiche non corretto, arresti anomali dei processi, danneggiamento dei dati e perdite di memoria. Lo stesso problema si applica ai thread che chiamano RpcServerSubscribeForNotification nello stesso handle di associazione.
La chiamata di RpcServerSubscribeForNotification e RpcServerUnsubscribeForNotification nello stesso handle di associazione è thread safe. Per le notifiche correnti, RPC notifica il server non più di una volta per chiamata.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista, Windows XP con SP2 [solo app desktop] |
| Server minimo supportato | Windows Server 2008, Windows Server 2003 con SP1 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | rpcasync.h (include Rpc.h) |
| Libreria | Rpcrt4.lib |
| DLL | Rpcrt4.dll |