ICallFrame
COM公式ドキュメント
スタックフレームなどの呼び出しフレームを操作できるようにします。
メソッド 19
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
呼び出しフレームに関する情報を取得します。
| pInfo | CALLFRAMEINFO* | out | CALLFRAMEINFO 構造体へのポインター。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
インターフェース ID またはメソッド番号を取得します。
| pIID | GUID* | out | インターフェース ID へのポインター。 |
| piMethod | DWORD* | out | メソッド番号へのポインター。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
この呼び出しのメソッド名またはインターフェース名を取得します。
| pwszInterface | LPWSTR* | out | インターフェース名へのポインター。 |
| pwszMethod | LPWSTR* | out | メソッド名へのポインター。 |
戻り値
要求された名前が利用できない場合、戻り値は null 文字列になります。このメソッドは次の値を返すこともあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
この呼び出しフレームがバインドされているスタック位置を取得します。
戻り値
このメソッドは要求されたスタック位置を返します。
この呼び出しフレームがバインドされるスタック位置を設定します。
| pvStack | void* | in | スタック位置へのポインター。 |
呼び出しフレーム内の戻り値を設定します。
| hr | HRESULT | in | 新しい戻り値。 |
呼び出しフレームに格納されている戻り値を取得します。
戻り値
このメソッドは、呼び出しフレームに格納されている HRESULT 値を返します。
指定した引数の情報を取得します。
| iparam | DWORD | in | 引数の番号。 |
| pInfo | CALLFRAMEPARAMINFO* | out | CALLFRAMEPARAMINFO 構造体へのポインター。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
呼び出しフレーム内の指定した引数の値を設定します。
| iparam | DWORD | in | 引数の番号。 |
| pvar | VARIANT* | in | 引数の新しい値。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
呼び出しフレーム内の指定した引数の値を取得します。
| iparam | DWORD | in | 引数の番号。 |
| pvar | VARIANT* | out | 引数の値。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
この呼び出しフレームと、それに関連するすべてのデータのコピーを作成します。
| copyControl | CALLFRAME_COPY | in | コピーされた呼び出しフレームのデータを親フレームのデータと共有できるかどうかを、親フレームへの有効期間の依存関係によって決定します。値の一覧については、CALLFRAME_COPY 列挙型を参照してください。CALLFRAME_COPY_NESTED フラグが設定されている場合、クライアントは、コピーされた呼び出しフレームの有効期間が親フレームの有効期間内に入れ子になるように使用する責任を負い、これによりデータが共有可能になります。CALLFRAME_COPY_INDEPENDENT が設定されている場合、コピーされたフレームの有効期間は親から独立します。 |
| pWalker | ICallFrameWalker* | in | ICallFrameWalker インターフェースのインスタンスへのポインター。コピーされるインターフェースポインターごとに OnWalkInterface メソッドが呼び出されます。この引数を指定しない場合、コピーされるインターフェースポインターは AddRef に渡されます。 |
| ppFrame | ICallFrame** | out | 呼び出しフレームのコピーを指す ICallFrame ポインターへのポインター。 |
戻り値
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
フレームのコピーは、マーシャリングされたフレームをアンマーシャリングすることに似ています。呼び出しフレームは、入力引数を持つ場合にのみコピーできます。呼び出しフレームが既に呼び出されている場合はコピーできません。Copy メソッドはインターフェースポインターをバイナリ値としてコピーし、参照カウントの調整は行いません。ただし、そのような動作が必要な場合は、ICallFrameWalker へのポインターを使用できます。
メモリリークを避けるためにフレームのコピーを解放します。
| pframeArgsDest | ICallFrame* | in | ICallFrame インターフェースのインスタンスへのポインター。フレームのコピーを解放する前に出力引数のコピー先となる呼び出しフレームのスタックポインターを表します。コピー先のフレームは通常、そのフレームのコピー元となった親フレームです。この引数は省略可能です。 フレームを解放する際に、受信側フレームと同じメモリ空間にある pframeArgsDest 引数を指定した場合は、各インターフェースポインターに対して pWalkerCopy 引数のみが呼び出されます。 |
| pWalkerDestFree | ICallFrameWalker* | in | ICallFrameWalker インターフェースのインスタンスへのポインター。pframeArgsDest に入出力両方の引数が存在する場合、伝播を行うにはそれらの値を解放する必要があります。pWalkerDestFree オブジェクトを指定することで、インターフェースポインターが解放されます。pframeArgsDest が NULL の場合、この引数も NULL でなければならず、インターフェースポインターは Release メソッドを呼び出して解放する必要があります。 |
| pWalkerCopy | ICallFrameWalker* | in | ICallFrameWalker インターフェースのインスタンスへのポインター。pframeArgsDest 内の入出力引数が解放されるときに、出力引数の伝播が実行されます。この引数を指定しない場合、インターフェースポインターは AddRef に渡されます。この引数は省略可能です。 |
| freeFlags | DWORD | in | CALLFRAME_FREE 列挙型のフラグ。 |
| pWalkerFree | ICallFrameWalker* | in | ICallFrameWalker インターフェースのインスタンスへのポインター。指定した場合、解放時に検出された各インターフェースポインターに対してコールバックが行われます。この引数を指定しない場合、インターフェースポインターは Release メソッドによって解放されます。 |
| nullFlags | DWORD | in | CALLFRAME_NULL 列挙型のフラグ。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
フレーム内の指定した引数を解放します。
| iparam | DWORD | in | 解放する引数の番号。 |
| freeFlags | DWORD | in | CALLFRAME_FREE 列挙型のフラグを表します。 |
| pWalkerFree | ICallFrameWalker* | in | ICallFrameWalker インターフェースのインスタンスへのポインター。指定した場合、解放時に検出された各インターフェースポインターに対してコールバックが行われます。この引数を指定しない場合、インターフェースポインターは Release メソッドによって解放されます。 |
| nullFlags | DWORD | in | CALLFRAME_NULL 列挙型のフラグを表します。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
フレームの [in]、[in, out]、または [out] 引数から到達可能なインターフェースポインターを検索します。
| walkWhat | DWORD | in | CALLFRAME_WALK 列挙型のフラグ。 |
| pWalker | ICallFrameWalker* | in | ICallFrameWalker インターフェースのインスタンスへのポインター。指定した場合、検出された各インターフェースポインターに対してコールバックが行われます。この引数は省略可能です。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
呼び出しフレームのマーシャリングに必要なバイト数の上限を取得します。
| pmshlContext | CALLFRAME_MARSHALCONTEXT* | in | マーシャリングの実行方法に関するコンテキスト情報を含む CALLFRAME_MARSHALCONTEXT 構造体へのポインター。 |
| mshlflags | MSHLFLAGS | in | マーシャリングするデータを、クライアントプロセスに送り返すか (通常のケース)、複数のクライアントから取得できるグローバルテーブルに書き込むかを示します。値の一覧については、MSHLFLAGS 列挙型を参照してください。 |
| pcbBufferNeeded | DWORD* | out | 呼び出しフレームのマーシャリングに必要となるバッファーのサイズ (バイト単位) へのポインター。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
フレームを乱すことなく、到達可能なデータをフラットなバッファーに変換して呼び出しフレームをマーシャリングします。
| pmshlContext | CALLFRAME_MARSHALCONTEXT* | in | マーシャリングの実行方法に関するコンテキスト情報を含む CALLFRAME_MARSHALCONTEXT 構造体へのポインター。 |
| mshlflags | MSHLFLAGS | in | マーシャリングするデータを、クライアントプロセスに送り返すか (通常のケース)、複数のクライアントから取得できるグローバルテーブルに書き込むかを示すフラグ。指定可能な値は MSHLFLAGS 列挙型のものです。 |
| pBuffer | void* | in | マーシャリングされたデータを格納するバッファーへのポインター。 |
| cbBuffer | DWORD | in | バッファーのサイズ (バイト単位)。 |
| pcbBufferUsed | DWORD* | out | 実際に使用されたバッファーのサイズを受け取ります。この引数は省略可能です。 |
| pdataRep | DWORD* | out | データのマーシャリングに使用された NDR データ表現を受け取ります。この引数は省略可能です。詳細については、IRpcChannelBuffer::GetBuffer を参照してください。 |
| prpcFlags | DWORD* | out | 呼び出しに関連付けられた RPC フラグを受け取ります。この引数は省略可能です。詳細については、IRpcChannelBuffer::GetBuffer を参照してください。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
解説(Remarks)
マーシャリング時には、[in, out] 引数の [In] 側の値が存在し、[out] 側の値は未定義です。[out] 引数をマーシャリングする場合、その値は有効です。
このメソッドがエラーを返した場合、呼び出し元はそれをクリーンアップできません。マーシャリングの試行中に一時的に割り当てられたメモリなどのリソースは、既に解放されています。
以前にマーシャリングされた呼び出しの [out] 引数を含むデータパケットを、既存のアクティベーションレコードにアンマーシャリングします。
| pBuffer | void* | in | マーシャリングされた [out] 値を含むバッファーへのポインター。 |
| cbBuffer | DWORD | in | バッファーのサイズ (バイト単位)。 |
| dataRep | DWORD | in | データのマーシャリングに使用された NDR データ表現。詳細については、IRpcChannelBuffer::GetBuffer を参照してください。 |
| pcontext | CALLFRAME_MARSHALCONTEXT* | in | アンマーシャリングの実行方法に関するコンテキスト情報を含む CALLFRAME_MARSHALCONTEXT 構造体へのポインター。 |
| pcbUnmarshalled | DWORD* | out | 正常にアンマーシャリングされたバイト数を受け取ります。この引数はエラー時にも返されます。この引数は省略可能です。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
解説(Remarks)
アンマーシャリング時には、[in, out] 引数の [in] 側の値が解放され、インターフェースポインターは解放されて [out] 側の値に置き換えられます。すべての [in, out] および [out] 引数は常に妥当な値、すなわち [in]、[in, out] の値、返されたデータから正常にアンマーシャリングされた [out] の値、または明示的に NULL に初期化された値のいずれかに設定されます。失敗が返された場合、呼び出し元は通常、NULL ではない値をクリーンアップするために ICallFrame::Free を呼び出すことになります。
マーシャリングされたデータのパケット内に存在するインターフェースポインターが保持しているリソースを解放します。このメソッドはパケット内のすべてのインターフェースポインターを検索し、それぞれに対して CoReleaseMarshalData 関数を呼び出します。
| pBuffer | void* | in | マーシャリングされた [out] 値を含むバッファーへのポインター。 |
| cbBuffer | DWORD | in | バッファーのサイズ (バイト単位)。 |
| ibFirstRelease | DWORD | in | バッファー内で解放を開始する最初のバイト。値が 0 の場合は、バッファー全体のインターフェースポインターが解放されることを意味します。マーシャリングされたインターフェースポインターは、他の何らかの仕組みによって既に解放されているものとみなされます。 |
| dataRep | DWORD | in | データのマーシャリングに使用されたデータ表現。 |
| pcontext | CALLFRAME_MARSHALCONTEXT* | in | アンマーシャリングの実行方法に関するコンテキスト情報を含む CALLFRAME_MARSHALCONTEXT 構造体へのポインター。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| 予期しないエラーが発生しました。 |
解説(Remarks)
マーシャリングされたバッファーが保持するリソースをクリーンアップするには、ReleaseMarshalData メソッドをちょうど 1 回呼び出す必要があります。ただし、MSHLFLAGS 列挙型が MSHLFLAGS_NORMAL に設定されている場合、これはアンマーシャリング時に自動的に行われるため、明示的に実行する必要はありません。
このメソッドは、マーシャリングされた [in] 引数と [out] 引数のどちらに対しても正しく機能します。
このアクティベーションレコードをオブジェクトに適用します。マーシャリングを伴う状況では、通常これはサーバー側で実行され、実際のオブジェクトの処理を実行する手段となります。
| pvReceiver | void* | in | 呼び出しを行う対象のインターフェース。このインターフェースが適切な IID のものであることを保証する責任は呼び出し元にあります。実装は単にキャストを行い、そうであるものとみなします。 |
戻り値
このメソッドは次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
|
このフレームからは既に呼び出しが行われています。 |
| 予期しないエラーが発生しました。 |
解説(Remarks)
一般に、呼び出しの実行では、新しいスタックフレームを割り当て、元のフレームのデータを浅くコピーしてから、指定されたオブジェクトの適切なメソッドを呼び出します。呼び出されたオブジェクトは、その呼び出しの適切なセマンティクスに従って、コピーされたフレームから到達可能な [out] 引数を変更することができます。オブジェクトから呼び出しが戻ると、呼び出しフレームは ICallFrame::SetReturnValue による戻り値を自動的に取得します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_ICallFrame "{D573B4B0-894E-11D2-B8B6-00C04FB9618A}" #usecom global ICallFrame IID_ICallFrame "{}" #comfunc global ICallFrame_GetInfo 3 var #comfunc global ICallFrame_GetIIDAndMethod 4 var,var #comfunc global ICallFrame_GetNames 5 var,var #comfunc global ICallFrame_GetStackLocation 6 #comfunc global ICallFrame_SetStackLocation 7 sptr #comfunc global ICallFrame_SetReturnValue 8 int #comfunc global ICallFrame_GetReturnValue 9 #comfunc global ICallFrame_GetParamInfo 10 int,var #comfunc global ICallFrame_SetParam 11 int,var #comfunc global ICallFrame_GetParam 12 int,var #comfunc global ICallFrame_Copy 13 int,sptr,sptr #comfunc global ICallFrame_Free 14 sptr,sptr,sptr,int,sptr,int #comfunc global ICallFrame_FreeParam 15 int,int,sptr,int #comfunc global ICallFrame_WalkFrame 16 int,sptr #comfunc global ICallFrame_GetMarshalSizeMax 17 var,int,var #comfunc global ICallFrame_Marshal 18 var,int,sptr,int,var,var,var #comfunc global ICallFrame_Unmarshal 19 sptr,int,int,var,var #comfunc global ICallFrame_ReleaseMarshalData 20 sptr,int,int,int,var #comfunc global ICallFrame_Invoke 21 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ICallFrame "{D573B4B0-894E-11D2-B8B6-00C04FB9618A}" #usecom global ICallFrame IID_ICallFrame "{}" #comfunc global ICallFrame_GetInfo 3 sptr #comfunc global ICallFrame_GetIIDAndMethod 4 sptr,sptr #comfunc global ICallFrame_GetNames 5 sptr,sptr #comfunc global ICallFrame_GetStackLocation 6 #comfunc global ICallFrame_SetStackLocation 7 sptr #comfunc global ICallFrame_SetReturnValue 8 int #comfunc global ICallFrame_GetReturnValue 9 #comfunc global ICallFrame_GetParamInfo 10 int,sptr #comfunc global ICallFrame_SetParam 11 int,sptr #comfunc global ICallFrame_GetParam 12 int,sptr #comfunc global ICallFrame_Copy 13 int,sptr,sptr #comfunc global ICallFrame_Free 14 sptr,sptr,sptr,int,sptr,int #comfunc global ICallFrame_FreeParam 15 int,int,sptr,int #comfunc global ICallFrame_WalkFrame 16 int,sptr #comfunc global ICallFrame_GetMarshalSizeMax 17 sptr,int,sptr #comfunc global ICallFrame_Marshal 18 sptr,int,sptr,int,sptr,sptr,sptr #comfunc global ICallFrame_Unmarshal 19 sptr,int,int,sptr,sptr #comfunc global ICallFrame_ReleaseMarshalData 20 sptr,int,int,int,sptr #comfunc global ICallFrame_Invoke 21 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。