context_handle属性
[context_handle] 属性は、リモート プロシージャ 呼び出しの間にサーバー上のコンテキスト (状態情報) を保持するバインディング ハンドルを識別します。
typedef [context_handle [ , type-attribute-list ] ] type-specifier declarator-list;
[context_handle [, function-attr-list ] ] type-specifier [ptr-decl] function-name(
[ [parameter-attribute-list] ] type-specifier [declarator], ...);
[ [ function-attr-list ] ] type-specifier [ ptr-decl ] function-name(
[context_handle [ , parameter-attribute-list ] ] type-specifier [declarator], ...);
[ void __RPC_USER context-handle-type_rundown (
context-handle-type); ]
パラメーター
-
type-attribute-list
-
型に適用される 1 つ以上の属性を指定します。
-
type-specifier
-
ポインター型または型識別子を指定します。 省略可能なストレージ仕様は 、型指定子の前に置くことができます。
-
declarator と declarator-list
-
識別子、ポインター宣言子、配列宣言子など、標準の C 宣言子を指定します。 コンテキスト ハンドルの宣言子には、少なくとも 1 つのポインター宣言子を含める必要があります。 詳細については、「 配列とSized-Pointer属性、 配列、および 配列とポインター」を参照してください。 declarator-list は、コンマで区切られた 1 つ以上の宣言子で構成されます。 関数宣言子のパラメーター名識別子は省略可能です。
-
function-attr-list
-
関数に適用される 0 個以上の属性を指定します。 有効な関数属性は [callback], [local];ポインター属性 [ref]、 [unique]、または [ptr];と usage 属性 [string]、 [ignore]、および [context_handle]。
-
ptr-decl
-
0 個以上のポインター宣言子を指定します。 ポインター宣言子は、C で使用されるポインター宣言子と同じです。これは、指定子、far などの修飾子、および修飾子 const から*構築されます。
-
function-name
-
リモート プロシージャの名前を指定します。
-
parameter-attribute-list
-
0 個以上の方向属性、フィールド属性、使用法属性、および指定したパラメーター型に適したポインター属性を指定します。 複数の属性をコンマで区切ります。
-
context-handle-type
-
[context_handle] 属性を受け取る typedef 宣言で定義されているコンテキスト ハンドル型を指定する識別子を指定します。 ランダウン ルーチンは省略可能です。
Windows Server 2003 および Windows XP: 1 つのインターフェイスは、シリアル化されたコンテキスト ハンドルと非シリアル化されたコンテキスト ハンドルの両方に対応でき、インターフェイス上の 1 つのメソッドが排他的に (シリアル化された) コンテキスト ハンドルにアクセスできるのに対し、他のメソッドは共有モード (非シリアル化) でそのコンテキスト ハンドルにアクセスできます。 これらのアクセス機能は、読み取り/書き込みロックメカニズムに相当します。シリアル化されたコンテキスト ハンドルを使用するメソッドは排他的ユーザー (ライター) ですが、非シリアル化されたコンテキスト ハンドルを使用するメソッドは共有ユーザー (リーダー) です。 コンテキスト ハンドルの状態を破棄または変更するメソッドはシリアル化する必要があります。 コンテキスト ハンドルの状態を変更しないメソッド (単にコンテキスト ハンドルから読み取るメソッドなど) は、非正規化できます。 作成方法は暗黙的にシリアル化されることに注意してください。
解説
[context_handle] 属性は、IDL typedef 型属性として、関数の戻り値の型属性として、またはパラメーター属性として使用できます。 [context_handle] 属性を型定義に適用する場合は、コンテキスト ランダウン ルーチンも指定する必要があります。 詳細については、「 サーバー コンテキストの実行ルーチン 」を参照してください。
MIDL コンパイラを既定の (/ms_ext) モードで使用する場合、コンテキスト ハンドルは、ここで説明するコンテキスト ハンドルの要件に準拠している限り、ユーザーが選択した任意のポインター型にすることができます。 このようなコンテキスト ハンドルの種類に関連付けられているデータはネットワーク上で送信されず、サーバー アプリケーションによってのみ操作する必要があります。 DCE IDL コンパイラは、コンテキスト ハンドルを void* 型のポインターに制限します。 したがって、MIDL コンパイラ /osf スイッチを使用する場合、この機能は使用できません。
他のハンドル型と同様に、コンテキスト ハンドルはクライアント アプリケーションに対して不透明であり、それに関連付けられているデータは送信されません。 サーバーでは、コンテキスト ハンドルはアクティブなコンテキストのハンドルとして機能し、コンテキスト ハンドルの種類に関連付けられているすべてのデータにアクセスできます。
コンテキスト ハンドルを作成するために、クライアントはコンテキスト ハンドルへの [out]、 [ref] ポインターをサーバーに渡します。 (コンテキスト ハンドル自体は、値がポインター属性と一致している限り、 NULL 値または NULL 以外の値を持つことができます。たとえば、コンテキスト ハンドル型に [ref] 属性が適用されている場合、 NULL 値を持つことはできません)。コンテキスト ハンドルが作成されるまで、バインドを実行するには、別のバインド ハンドルを指定する必要があります。 明示的なハンドルが指定されていない場合は、暗黙的なバインディングが使用されます。 [implicit_handle] 属性が存在しない場合は、自動ハンドルが使用されます。
サーバー上のリモート プロシージャによって、アクティブなコンテキスト ハンドルが作成されます。 クライアントは、後続の呼び出しで、そのコンテキスト ハンドルを [in] または [in, out] パラメーターとして使用する必要があります。 [in]専用コンテキスト ハンドルはバインド ハンドルとして使用できるため、NULL 以外の値が必要です。 [入力] のみのコンテキスト ハンドルには、サーバー上の状態の変更は反映されません。
サーバーでは、呼び出されたプロシージャは、必要に応じてコンテキスト ハンドルを解釈できます。 たとえば、呼び出されたプロシージャはヒープ ストレージを割り当て、コンテキスト ハンドルをこのストレージへのポインターとして使用できます。
コンテキスト ハンドルを閉じるには、クライアントはコンテキスト ハンドルを [in]、 [out] 引数として渡します。 サーバーは、呼び出し元の代わりにコンテキストを維持しなくなった場合に NULL コンテキスト ハンドルを返す必要があります。 たとえば、コンテキスト ハンドルが開いているファイルを表し、呼び出しによってファイルが閉じる場合、サーバーはコンテキスト ハンドルを NULL に設定し、クライアントに返す必要があります。 NULL 値は、後続の呼び出しのバインディング ハンドルとして無効です。
コンテキスト ハンドルは、1 つのサーバーに対してのみ有効です。 関数に 2 つのハンドル パラメーターがあり、コンテキスト ハンドルが NULL でない場合、バインド ハンドルは同じアドレス空間を参照する必要があります。
関数に [in] または [in, out] コンテキスト ハンドルがある場合、そのコンテキスト ハンドルをバインド ハンドルとして使用できます。 この場合、暗黙的なバインディングは使用されず、[implicit_handle] 属性または [auto_handle] 属性は無視されます。
コンテキスト ハンドルには、次の制限が適用されます。
- コンテキスト ハンドルは、配列要素、構造体メンバー、または共用体メンバーにすることはできません。 パラメーターのみを指定できます。
- コンテキスト ハンドルに [transmit_as] 属性または [represent_as] 属性を指定することはできません。
- [out] コンテキスト ハンドルへのポインターであるパラメーターは、[ref] ポインターである必要があります。
- [in] コンテキスト ハンドルはバインド ハンドルとして使用でき、NULL にすることはできません。
- [in, out context handle can be NULL on input, but only if the procedure has another explicit handle parameter. NULL 以外の明示的なコンテキスト ハンドル パラメーターが他に存在しない場合、[ in, out] コンテキスト ハンドルを NULL にすることはできません。
- コンテキスト ハンドルはコールバックと共に使用できません。
例
typedef [context_handle] void * PCONTEXT_HANDLE_TYPE;
short RemoteFunc1([out] PCONTEXT_HANDLE_TYPE * pCxHandle);
short RemoteFunc2([in, out] PCONTEXT_HANDLE_TYPE * pCxHandle);
void __RPC_USER PCONTEXT_HANDLE_TYPE_rundown (PCONTEXT_HANDLE_TYPE);
関連項目