ホーム › System.Rpc › RpcServerSubscribeForNotification

RpcServerSubscribeForNotification

関数

RPCサーバーが指定イベントの通知を購読する。

DLLRPCRT4.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// RPCRT4.dll
#include <windows.h>

RPC_STATUS RpcServerSubscribeForNotification(
    void* Binding,   // optional
    RPC_NOTIFICATIONS Notification,
    RPC_NOTIFICATION_TYPES NotificationType,
    RPC_ASYNC_NOTIFICATION_INFO* NotificationInfo
);

パラメーター

名前	型	方向	説明
Binding	void*	inoptional	現在の呼び出しのバインディングハンドルを格納する RPC_BINDING_HANDLE 構造体です。RPC が呼び出しをディスパッチしたスレッドと同じスレッドでこの関数を呼び出す場合、このパラメーターには NULL を指定できます。それ以外の場合は、明示的なバインディングハンドルをこのパラメーターに渡す必要があります。
Notification	RPC_NOTIFICATIONS	in	サーバーが RPC に要求する通知の種類を指定する RPC_NOTIFICATIONS 列挙値のビット単位の組み合わせです。 Windows Vista: 現在、サポートされているのは RpcNotificationClientDisconnect と RpcNotificationCallCancel のみです。このパラメーターにこれら以外の値を指定した場合、RPC_S_CANNOT_SUPPORT エラーコードが返されます。
NotificationType	RPC_NOTIFICATION_TYPES	in	RPC がサーバーに通知する方法を指定する RPC_NOTIFICATION_TYPES 列挙値です。 Windows Vista: RpcNotificationTypeNone はサポートされていません。この値を指定した場合、RPC_S_INVALID_ARG エラーコードが返されます。
NotificationInfo	RPC_ASYNC_NOTIFICATION_INFO*	in	RPC が通知のためにサーバーへ連絡するのに必要な固有の情報を格納する RPC_ASYNC_NOTIFICATION_INFO 共用体へのポインターです。この共用体に格納されるデータは、NotificationType パラメーターに渡された方法に固有のものです。 NotificationTypes に RpcNotificationTypeCallback の方法を指定した場合、共用体の対応するブランチの NotificationRoutine メンバーには、同期呼び出しの場合はバインディングハンドルが、非同期呼び出しの場合は非同期ハンドルが設定されます。 RPC は、この関数の呼び出しが成功した時点でこのパラメーターのコピーを作成します。呼び出し元は、API から制御が戻った後にこのパラメーターを解放または更新できます。

戻り値の型: RPC_STATUS

公式ドキュメント

RPC 通知に対してサーバーをサブスクライブします。

戻り値

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

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

解説(Remarks)

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

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

サーバーアプリケーションは、サブスクライブしていない通知についてシグナルを受け取ることはないと想定できます。複数の通知をサブスクライブしている場合、選択した完了方法が許可していれば、各通知はその完了方法を通じて伝えられます。通知の伝達が許可されていない場合、サーバーアプリケーションは RPC サーバー API のいずれかを呼び出して、クライアントが呼び出しをキャンセルしたか切断したかをテストできます。次の表は、通知の種類 (呼び出しのキャンセルまたはクライアントの切断) が各通知方法にどのように伝えられるかを示しています。

通知方法	イベント/通知の種類
RpcNotificationTypeNone	サブスクリプションには使用できません。
RpcNotificationTypeEvent	通知の種類は利用できません。
RpcNotificationTypeApc	通知の種類は APC 関数の Event パラメーターで取得できます。
RpcNotificationTypeIoc	通知の種類は利用できません。
RpcNotificationTypeCallback	通知の種類はコールバック関数の Event パラメーターで取得できます。

この表は、指定した通知方法を使用して呼び出し元が通知をサブスクライブできるかどうかを示すものではありません。あくまで、通知を受け取ったときに呼び出し元が取得できる情報 (通知の種類など) を示しているだけです。

呼び出し元は、同じバインディングハンドルに対する RpcServerSubscribeForNotification と RpcServerUnsubscribeForNotification の間で同期を取る必要があります。これらが同時に呼び出された場合、結果は未定義となり、通知の消失、余分な通知、通知数の不整合、プロセスのクラッシュ、データの破損、メモリリークが発生する可能性があります。同じバインディングハンドルに対して RpcServerSubscribeForNotification を呼び出すスレッドについても同様の注意が必要です。

同じバインディングハンドルに対して RpcServerSubscribeForNotification と RpcServerUnsubscribeForNotification を呼び出すことはスレッドセーフです。現行の通知では、RPC は 1 回の呼び出しにつき最大 1 回だけサーバーに通知します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// RPCRT4.dll
#include <windows.h>

RPC_STATUS RpcServerSubscribeForNotification(
    void* Binding,   // optional
    RPC_NOTIFICATIONS Notification,
    RPC_NOTIFICATION_TYPES NotificationType,
    RPC_ASYNC_NOTIFICATION_INFO* NotificationInfo
);

[DllImport("RPCRT4.dll", ExactSpelling = true)]
static extern int RpcServerSubscribeForNotification(
    IntPtr Binding,   // void* optional
    int Notification,   // RPC_NOTIFICATIONS
    int NotificationType,   // RPC_NOTIFICATION_TYPES
    IntPtr NotificationInfo   // RPC_ASYNC_NOTIFICATION_INFO*
);

<DllImport("RPCRT4.dll", ExactSpelling:=True)>
Public Shared Function RpcServerSubscribeForNotification(
    Binding As IntPtr,   ' void* optional
    Notification As Integer,   ' RPC_NOTIFICATIONS
    NotificationType As Integer,   ' RPC_NOTIFICATION_TYPES
    NotificationInfo As IntPtr   ' RPC_ASYNC_NOTIFICATION_INFO*
) As Integer
End Function

' Binding : void* optional
' Notification : RPC_NOTIFICATIONS
' NotificationType : RPC_NOTIFICATION_TYPES
' NotificationInfo : RPC_ASYNC_NOTIFICATION_INFO*
Declare PtrSafe Function RpcServerSubscribeForNotification Lib "rpcrt4" ( _
    ByVal Binding As LongPtr, _
    ByVal Notification As Long, _
    ByVal NotificationType As Long, _
    ByVal NotificationInfo As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

RpcServerSubscribeForNotification = ctypes.windll.rpcrt4.RpcServerSubscribeForNotification
RpcServerSubscribeForNotification.restype = ctypes.c_int
RpcServerSubscribeForNotification.argtypes = [
    ctypes.POINTER(None),  # Binding : void* optional
    ctypes.c_int,  # Notification : RPC_NOTIFICATIONS
    ctypes.c_int,  # NotificationType : RPC_NOTIFICATION_TYPES
    ctypes.c_void_p,  # NotificationInfo : RPC_ASYNC_NOTIFICATION_INFO*
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('RPCRT4.dll')
RpcServerSubscribeForNotification = Fiddle::Function.new(
  lib['RpcServerSubscribeForNotification'],
  [
    Fiddle::TYPE_VOIDP,  # Binding : void* optional
    Fiddle::TYPE_INT,  # Notification : RPC_NOTIFICATIONS
    Fiddle::TYPE_INT,  # NotificationType : RPC_NOTIFICATION_TYPES
    Fiddle::TYPE_VOIDP,  # NotificationInfo : RPC_ASYNC_NOTIFICATION_INFO*
  ],
  Fiddle::TYPE_INT)

#[link(name = "rpcrt4")]
extern "system" {
    fn RpcServerSubscribeForNotification(
        Binding: *mut (),  // void* optional
        Notification: i32,  // RPC_NOTIFICATIONS
        NotificationType: i32,  // RPC_NOTIFICATION_TYPES
        NotificationInfo: *mut RPC_ASYNC_NOTIFICATION_INFO  // RPC_ASYNC_NOTIFICATION_INFO*
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("RPCRT4.dll")]
public static extern int RpcServerSubscribeForNotification(IntPtr Binding, int Notification, int NotificationType, IntPtr NotificationInfo);
"@
$api = Add-Type -MemberDefinition $sig -Name 'RPCRT4_RpcServerSubscribeForNotification' -Namespace Win32 -PassThru
# $api::RpcServerSubscribeForNotification(Binding, Notification, NotificationType, NotificationInfo)

#uselib "RPCRT4.dll"
#func global RpcServerSubscribeForNotification "RpcServerSubscribeForNotification" sptr, sptr, sptr, sptr
; RpcServerSubscribeForNotification Binding, Notification, NotificationType, varptr(NotificationInfo)   ; 戻り値は stat
; Binding : void* optional -> "sptr"
; Notification : RPC_NOTIFICATIONS -> "sptr"
; NotificationType : RPC_NOTIFICATION_TYPES -> "sptr"
; NotificationInfo : RPC_ASYNC_NOTIFICATION_INFO* -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "RPCRT4.dll"
#cfunc global RpcServerSubscribeForNotification "RpcServerSubscribeForNotification" sptr, int, int, var
; res = RpcServerSubscribeForNotification(Binding, Notification, NotificationType, NotificationInfo)
; Binding : void* optional -> "sptr"
; Notification : RPC_NOTIFICATIONS -> "int"
; NotificationType : RPC_NOTIFICATION_TYPES -> "int"
; NotificationInfo : RPC_ASYNC_NOTIFICATION_INFO* -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "RPCRT4.dll"
#cfunc global RpcServerSubscribeForNotification "RpcServerSubscribeForNotification" sptr, int, int, sptr
; res = RpcServerSubscribeForNotification(Binding, Notification, NotificationType, varptr(NotificationInfo))
; Binding : void* optional -> "sptr"
; Notification : RPC_NOTIFICATIONS -> "int"
; NotificationType : RPC_NOTIFICATION_TYPES -> "int"
; NotificationInfo : RPC_ASYNC_NOTIFICATION_INFO* -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。