RpcServerSubscribeForNotification-Funktion (rpcasync.h)
Die RpcServerSubscribeForNotification-Funktion abonniert den Server für RPC-Benachrichtigungen.
Syntax
RPC_STATUS RpcServerSubscribeForNotification(
[in] RPC_BINDING_HANDLE Binding,
[in] RPC_NOTIFICATIONS Notification,
[in] RPC_NOTIFICATION_TYPES NotificationType,
[in] RPC_ASYNC_NOTIFICATION_INFO *NotificationInfo
);
Parameter
[in] Binding
RPC_BINDING_HANDLE Struktur, die das Bindungshandle für den aktuellen Aufruf enthält. Wenn diese Funktion im selben Thread aufgerufen wird, für den RPC einen Aufruf ausgelöst hat, kann dieser Parameter auf NULL festgelegt werden. Andernfalls muss in diesem Parameter ein explizites Bindungshandle übergeben werden.
[in] Notification
Bitweise Kombination der RPC_NOTIFICATIONS Enumerationswerte, die den Typ der vom RPC vom Server angeforderten Benachrichtigung angibt.
Windows Vista: Derzeit werden nur RpcNotificationClientDisconnect und RpcNotificationCallCancel unterstützt. Wenn für diesen Parameter ein anderer Wert angegeben wird, wird der RPC_S_CANNOT_SUPPORT Fehlercode zurückgegeben.
[in] NotificationType
RPC_NOTIFICATION_TYPES Enumerationswert, der die Methode angibt, mit der RPC den Server benachrichtigt.
Windows Vista: RpcNotificationTypeNone wird nicht unterstützt. Wenn dieser Wert angegeben wird, wird der RPC_S_INVALID_ARG Fehlercode zurückgegeben.
[in] NotificationInfo
Zeiger auf eine RPC_ASYNC_NOTIFICATION_INFO Union, die die spezifischen Informationen enthält, die für RPC erforderlich sind, um den Server zur Benachrichtigung zu kontaktieren. Die in dieser Union enthaltenen Daten sind spezifisch für die Methode, die an den NotificationType-Parameter übergeben wird.
Wenn die RpcNotificationTypeCallback-Methode in NotificationTypes angegeben wird, wird das NotificationRoutine-Member des entsprechenden Branchs der Union auf das Bindungshandle für synchrone Aufrufe und das asynchrone Handle für asynchrone Aufrufe festgelegt.
RPC erstellt eine Kopie dieses Parameters während eines erfolgreichen Aufrufs dieser Funktion. Der Aufrufer kann diesen Parameter freigeben oder aktualisieren, wenn die API zurückgibt.
Rückgabewert
Diese Funktion gibt bei Erfolg RPC_S_OK zurück. Andernfalls wird ein RPC_S_*-Fehlercode zurückgegeben.
Hinweise
Wenn der Aufrufer einen anderen Benachrichtigungstyp als RpcNotificationTypeEvent angibt, kann er sowohl die RpcNotificationClientDisconnect - als auch die RpcNotificationCallCancel-Benachrichtigung mit einem einzelnen Aufruf abonnieren. Für Ereignisse sind zwei separate Aufrufe dieser API erforderlich.
Die Serveranwendung muss sich für eine Benachrichtigung abmelden, bevor der RPC-Aufruf abgeschlossen ist. Wenn der RPC-Aufruf synchron ist, wird er abgeschlossen, wenn der Server einen Rückgabewert an RPC sendet. Wenn der RPC-Aufruf asynchron ist, wird er abgeschlossen, wenn der Server RpcAsyncCompleteCall oder RpcAsyncAbortCall aufruft oder eine Ausnahme aus der Managerroutine auslöst. Wenn sich der Server nicht für Anruf- status Änderungsbenachrichtigungen abmelden kann, sind die Ergebnisse nicht definiert, und der Server kann zu einem späteren Zeitpunkt abstürzen. Beachten Sie, dass das Abonnement nur für einen RPC-Aufruf gilt. Wenn die Serveranwendung mehrere Aufrufe überwachen muss, muss sie jeden Anruf speziell abonnieren.
Die Serveranwendung kann davon ausgehen, dass sie nicht für Benachrichtigungen signalisiert wird, die sie nicht abonniert hat. Wenn sie mehrere Benachrichtigungen abonniert hat, wird jede Benachrichtigung an die Vervollständigungsmethode übermittelt, sofern dies von der ausgewählten Vervollständigungsmethode zulässt. Wenn die Kommunikation von Benachrichtigungen nicht zulässt, kann die Serveranwendung die RPC-Server-APIs aufrufen, um zu testen, ob der Client abgebrochen oder getrennt wurde. Die folgende Tabelle gibt an, wie der Benachrichtigungstyp (Aufrufabbruch oder Clienttrennung) an jede Benachrichtigungsmethode kommuniziert wird:
| Benachrichtigungsmethode | Ereignis-/Benachrichtigungstyp |
|---|---|
| RpcNotificationTypeNone | Für das Abonnement nicht zulässig. |
| RpcNotificationTypeEvent | Der Benachrichtigungstyp ist nicht verfügbar. |
| RpcNotificationTypeApc | Der Benachrichtigungstyp befindet sich im Ereignisparameter der APC-Funktion. |
| RpcNotificationTypeIoc | Der Benachrichtigungstyp ist nicht verfügbar. |
| RpcNotificationTypeCallback | Der Benachrichtigungstyp befindet sich im Ereignisparameter der Rückruffunktion. |
Beachten Sie, dass die Tabelle nicht impliziert, ob ein Aufrufer Benachrichtigungen mit der angegebenen Benachrichtigungsmethode abonnieren kann oder nicht. Stattdessen werden lediglich die Informationen angegeben, die der Aufrufer erhalten kann, wenn die Benachrichtigung empfangen wird, z. B. den Benachrichtigungstyp.
Der Aufrufer muss zwischen RpcServerSubscribeForNotification und RpcServerUnsubscribeForNotification für das gleiche Bindungshandle synchronisiert werden. Wenn sie gleichzeitig aufgerufen werden, sind die Ergebnisse nicht definiert und können zu Verlustbenachrichtigungen, zusätzlichen Benachrichtigungen, einer falschen Benachrichtigungsanzahl, Prozessabstürzen, Datenbeschädigungen und Speicherverlusten führen. Das gleiche Problem gilt für Threads, die RpcServerSubscribeForNotification für dasselbe Bindungshandle aufrufen.
Das Aufrufen von RpcServerSubscribeForNotification und RpcServerUnsubscribeForNotification für dasselbe Bindungshandle ist threadsicher. Bei aktuellen Benachrichtigungen benachrichtigt RPC den Server nicht mehr als einmal pro Anruf.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista, Windows XP mit SP2 [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008, Windows Server 2003 mit SP1 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | rpcasync.h (include Rpc.h) |
| Bibliothek | Rpcrt4.lib |
| DLL | Rpcrt4.dll |