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 から要求される通知の種類を指定する RPC_NOTIFICATIONS 列挙値のビットごとの組み合わせ。

Windows Vista: 現時点では、 RpcNotificationClientDisconnect と RpcNotificationCallCancel のみがサポートされています。 このパラメーターに他の値が指定されている場合は、RPC_S_CANNOT_SUPPORTエラー コードが返されます。

[in] NotificationType

RPC_NOTIFICATION_TYPES RPC がサーバーに通知するメソッドを指定する列挙値です。

Windows Vista: RpcNotificationTypeNone はサポートされていません。 この値を指定すると、RPC_S_INVALID_ARGエラー コードが返されます。

[in] NotificationInfo

RPC が通知のためにサーバーに接続するために必要な特定の情報を含む、 RPC_ASYNC_NOTIFICATION_INFO 共用体へのポインター。 この共用体に含まれるデータは、 NotificationType パラメーターに渡されるメソッドに固有です。

NotificationTypes で RpcNotificationTypeCallback メソッドが指定されている場合、共用体の対応するブランチの NotificationRoutine メンバーは、同期呼び出しのバインド ハンドルと非同期呼び出しの非同期ハンドルに設定されます。

RPC は、この関数の正常な呼び出し中にこのパラメーターのコピーを作成します。 呼び出し元は、API が戻ったときにこのパラメーターを解放または更新できます。

戻り値

この関数は、成功したRPC_S_OKを返します。それ以外の場合は、RPC_S_* エラー コードが返されます。

メモ 有効なエラー コードの一覧については、「 RPC 戻り値」を参照してください。
 

注釈

呼び出し元が RpcNotificationTypeEvent 以外の通知の種類を指定した場合、1 回の呼び出しで RpcNotificationClientDisconnect 通知と RpcNotificationCallCancel 通知の両方をサブスクライブできます。 イベントの場合は、この API の 2 つの個別の呼び出しが必要です。

サーバー アプリケーションは、RPC 呼び出しが完了する前に、通知の登録を解除する必要があります。 RPC 呼び出しが同期的な場合、サーバーが RPC に戻り値を送信すると完了します。 RPC 呼び出しが非同期の場合、サーバーが RpcAsyncCompleteCall または RpcAsyncAbortCall を呼び出すか、マネージャー ルーチンから例外をスローしたときに完了します。 サーバーが通話状態変更通知の登録解除に失敗した場合、結果は未定義になり、後でサーバーがクラッシュする可能性があります。 サブスクリプションは 1 つの RPC 呼び出しにのみ適用されることに注意してください。 サーバー アプリケーションで複数の呼び出しを監視する必要がある場合は、呼び出しごとに特にサブスクライブする必要があります。

サーバー アプリケーションは、サブスクライブしていない通知に対して通知されないことを期待できます。 複数の通知をサブスクライブしている場合、選択した完了メソッドで許可されている場合、各通知は完了メソッドに通知されます。 通知の通信が許可されない場合、サーバー アプリケーションは RPC サーバー API の を呼び出して、クライアントが取り消されたか切断されたかをテストできます。 次の表は、通知の種類 (通話キャンセルまたはクライアント切断) が各通知方法にどのように通信されるかを示しています。

Notification メソッド イベント/通知の種類
RpcNotificationTypeNone サブスクリプションに対しては許可されていません。
RpcNotificationTypeEvent 通知の種類は使用できません。
RpcNotificationTypeApc 通知の種類は、APC 関数の Event パラメーターにあります。
RpcNotificationTypeIoc 通知の種類は使用できません。
RpcNotificationTypeCallback 通知の種類は、コールバック関数の Event パラメーターにあります。
 

テーブルは、呼び出し元が指定された通知メソッドを使用して通知をサブスクライブできるかどうかを示すものではありません。むしろ、通知の種類など、通知を受信したときに呼び出し元が取得できる情報を示すだけです。

呼び出し元は、同じバインド ハンドルで RpcServerSubscribeForNotification と RpcServerUnsubscribeForNotification の間で同期する必要があります。 同時に呼び出されると、結果は未定義になり、失われた通知、追加の通知、正しくない通知数、プロセス クラッシュ、データ破損、メモリ リークが発生する可能性があります。 同じバインディング ハンドルで RpcServerSubscribeForNotification を 呼び出すスレッドにも同じ問題が適用されます。

同じバインド ハンドル で RpcServerSubscribeForNotification と RpcServerUnsubscribeForNotification を呼び出すことはスレッド セーフです。 現在の通知の場合、RPC は呼び出しごとに 1 回以上サーバーに通知しません。

要件

要件 値
サポートされている最小のクライアント Windows Vista、SP2 を使用した Windows XP [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008、Windows Server 2003 SP1 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー rpcasync.h (Rpc.h を含む)
Library Rpcrt4.lib
[DLL] Rpcrt4.dll

こちらもご覧ください

RpcServerUnsubscribeForNotification