Win32 API 日本語リファレンス
ホームSystem.Com.CallObj › ICallFrame

ICallFrame

COM
IIDd573b4b0-894e-11d2-b8b6-00c04fb9618a継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

スタックフレームなどの呼び出しフレームを操作できるようにします。

メソッド 19

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetInfo(CALLFRAMEINFO* pInfo)

呼び出しフレームに関する情報を取得します。

pInfoCALLFRAMEINFO*outCALLFRAMEINFO 構造体へのポインター。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。
vtbl 4 HRESULT GetIIDAndMethod(GUID* pIID, DWORD* piMethod)

インターフェース ID またはメソッド番号を取得します。

pIIDGUID*outインターフェース ID へのポインター。
piMethodDWORD*outメソッド番号へのポインター。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。
vtbl 5 HRESULT GetNames(LPWSTR* pwszInterface, LPWSTR* pwszMethod)

この呼び出しのメソッド名またはインターフェース名を取得します。

pwszInterfaceLPWSTR*outインターフェース名へのポインター。
pwszMethodLPWSTR*outメソッド名へのポインター。

戻り値

要求された名前が利用できない場合、戻り値は null 文字列になります。このメソッドは次の値を返すこともあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。
vtbl 6 void* GetStackLocation()

この呼び出しフレームがバインドされているスタック位置を取得します。

戻り値

このメソッドは要求されたスタック位置を返します。

vtbl 7 void SetStackLocation(void* pvStack)

この呼び出しフレームがバインドされるスタック位置を設定します。

pvStackvoid*inスタック位置へのポインター。
vtbl 8 void SetReturnValue(HRESULT hr)

呼び出しフレーム内の戻り値を設定します。

hrHRESULTin新しい戻り値。
vtbl 9 HRESULT GetReturnValue()

呼び出しフレームに格納されている戻り値を取得します。

戻り値

このメソッドは、呼び出しフレームに格納されている HRESULT 値を返します。

vtbl 10 HRESULT GetParamInfo(DWORD iparam, CALLFRAMEPARAMINFO* pInfo)

指定した引数の情報を取得します。

iparamDWORDin引数の番号。
pInfoCALLFRAMEPARAMINFO*outCALLFRAMEPARAMINFO 構造体へのポインター。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。
vtbl 11 HRESULT SetParam(DWORD iparam, VARIANT* pvar)

呼び出しフレーム内の指定した引数の値を設定します。

iparamDWORDin引数の番号。
pvarVARIANT*in引数の新しい値。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。
vtbl 12 HRESULT GetParam(DWORD iparam, VARIANT* pvar)

呼び出しフレーム内の指定した引数の値を取得します。

iparamDWORDin引数の番号。
pvarVARIANT*out引数の値。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。
vtbl 13 HRESULT Copy(CALLFRAME_COPY copyControl, ICallFrameWalker* pWalker, ICallFrame** ppFrame)

この呼び出しフレームと、それに関連するすべてのデータのコピーを作成します。

copyControlCALLFRAME_COPYinコピーされた呼び出しフレームのデータを親フレームのデータと共有できるかどうかを、親フレームへの有効期間の依存関係によって決定します。値の一覧については、CALLFRAME_COPY 列挙型を参照してください。CALLFRAME_COPY_NESTED フラグが設定されている場合、クライアントは、コピーされた呼び出しフレームの有効期間が親フレームの有効期間内に入れ子になるように使用する責任を負い、これによりデータが共有可能になります。CALLFRAME_COPY_INDEPENDENT が設定されている場合、コピーされたフレームの有効期間は親から独立します。
pWalkerICallFrameWalker*inICallFrameWalker インターフェースのインスタンスへのポインター。コピーされるインターフェースポインターごとに OnWalkInterface メソッドが呼び出されます。この引数を指定しない場合、コピーされるインターフェースポインターは AddRef に渡されます。
ppFrameICallFrame**out呼び出しフレームのコピーを指す ICallFrame ポインターへのポインター。

戻り値

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

フレームのコピーは、マーシャリングされたフレームをアンマーシャリングすることに似ています。呼び出しフレームは、入力引数を持つ場合にのみコピーできます。呼び出しフレームが既に呼び出されている場合はコピーできません。Copy メソッドはインターフェースポインターをバイナリ値としてコピーし、参照カウントの調整は行いません。ただし、そのような動作が必要な場合は、ICallFrameWalker へのポインターを使用できます。

vtbl 14 HRESULT Free(ICallFrame* pframeArgsDest, ICallFrameWalker* pWalkerDestFree, ICallFrameWalker* pWalkerCopy, DWORD freeFlags, ICallFrameWalker* pWalkerFree, DWORD nullFlags)

メモリリークを避けるためにフレームのコピーを解放します。

pframeArgsDestICallFrame*in

ICallFrame インターフェースのインスタンスへのポインター。フレームのコピーを解放する前に出力引数のコピー先となる呼び出しフレームのスタックポインターを表します。コピー先のフレームは通常、そのフレームのコピー元となった親フレームです。この引数は省略可能です。

フレームを解放する際に、受信側フレームと同じメモリ空間にある pframeArgsDest 引数を指定した場合は、各インターフェースポインターに対して pWalkerCopy 引数のみが呼び出されます。

pWalkerDestFreeICallFrameWalker*inICallFrameWalker インターフェースのインスタンスへのポインター。pframeArgsDest に入出力両方の引数が存在する場合、伝播を行うにはそれらの値を解放する必要があります。pWalkerDestFree オブジェクトを指定することで、インターフェースポインターが解放されます。pframeArgsDestNULL の場合、この引数も NULL でなければならず、インターフェースポインターは Release メソッドを呼び出して解放する必要があります。
pWalkerCopyICallFrameWalker*inICallFrameWalker インターフェースのインスタンスへのポインター。pframeArgsDest 内の入出力引数が解放されるときに、出力引数の伝播が実行されます。この引数を指定しない場合、インターフェースポインターは AddRef に渡されます。この引数は省略可能です。
freeFlagsDWORDinCALLFRAME_FREE 列挙型のフラグ。
pWalkerFreeICallFrameWalker*inICallFrameWalker インターフェースのインスタンスへのポインター。指定した場合、解放時に検出された各インターフェースポインターに対してコールバックが行われます。この引数を指定しない場合、インターフェースポインターは Release メソッドによって解放されます。
nullFlagsDWORDinCALLFRAME_NULL 列挙型のフラグ。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。
vtbl 15 HRESULT FreeParam(DWORD iparam, DWORD freeFlags, ICallFrameWalker* pWalkerFree, DWORD nullFlags)

フレーム内の指定した引数を解放します。

iparamDWORDin解放する引数の番号。
freeFlagsDWORDinCALLFRAME_FREE 列挙型のフラグを表します。
pWalkerFreeICallFrameWalker*inICallFrameWalker インターフェースのインスタンスへのポインター。指定した場合、解放時に検出された各インターフェースポインターに対してコールバックが行われます。この引数を指定しない場合、インターフェースポインターは Release メソッドによって解放されます。
nullFlagsDWORDinCALLFRAME_NULL 列挙型のフラグを表します。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。
vtbl 16 HRESULT WalkFrame(DWORD walkWhat, ICallFrameWalker* pWalker)

フレームの [in]、[in, out]、または [out] 引数から到達可能なインターフェースポインターを検索します。

walkWhatDWORDinCALLFRAME_WALK 列挙型のフラグ。
pWalkerICallFrameWalker*inICallFrameWalker インターフェースのインスタンスへのポインター。指定した場合、検出された各インターフェースポインターに対してコールバックが行われます。この引数は省略可能です。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。
vtbl 17 HRESULT GetMarshalSizeMax(CALLFRAME_MARSHALCONTEXT* pmshlContext, MSHLFLAGS mshlflags, DWORD* pcbBufferNeeded)

呼び出しフレームのマーシャリングに必要なバイト数の上限を取得します。

pmshlContextCALLFRAME_MARSHALCONTEXT*inマーシャリングの実行方法に関するコンテキスト情報を含む CALLFRAME_MARSHALCONTEXT 構造体へのポインター。
mshlflagsMSHLFLAGSinマーシャリングするデータを、クライアントプロセスに送り返すか (通常のケース)、複数のクライアントから取得できるグローバルテーブルに書き込むかを示します。値の一覧については、MSHLFLAGS 列挙型を参照してください。
pcbBufferNeededDWORD*out呼び出しフレームのマーシャリングに必要となるバッファーのサイズ (バイト単位) へのポインター。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。
vtbl 18 HRESULT Marshal(CALLFRAME_MARSHALCONTEXT* pmshlContext, MSHLFLAGS mshlflags, void* pBuffer, DWORD cbBuffer, DWORD* pcbBufferUsed, DWORD* pdataRep, DWORD* prpcFlags)

フレームを乱すことなく、到達可能なデータをフラットなバッファーに変換して呼び出しフレームをマーシャリングします。

pmshlContextCALLFRAME_MARSHALCONTEXT*inマーシャリングの実行方法に関するコンテキスト情報を含む CALLFRAME_MARSHALCONTEXT 構造体へのポインター。
mshlflagsMSHLFLAGSinマーシャリングするデータを、クライアントプロセスに送り返すか (通常のケース)、複数のクライアントから取得できるグローバルテーブルに書き込むかを示すフラグ。指定可能な値は MSHLFLAGS 列挙型のものです。
pBuffervoid*inマーシャリングされたデータを格納するバッファーへのポインター。
cbBufferDWORDinバッファーのサイズ (バイト単位)。
pcbBufferUsedDWORD*out実際に使用されたバッファーのサイズを受け取ります。この引数は省略可能です。
pdataRepDWORD*outデータのマーシャリングに使用された NDR データ表現を受け取ります。この引数は省略可能です。詳細については、IRpcChannelBuffer::GetBuffer を参照してください。
prpcFlagsDWORD*out呼び出しに関連付けられた RPC フラグを受け取ります。この引数は省略可能です。詳細については、IRpcChannelBuffer::GetBuffer を参照してください。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。

解説(Remarks)

マーシャリング時には、[in, out] 引数の [In] 側の値が存在し、[out] 側の値は未定義です。[out] 引数をマーシャリングする場合、その値は有効です。

このメソッドがエラーを返した場合、呼び出し元はそれをクリーンアップできません。マーシャリングの試行中に一時的に割り当てられたメモリなどのリソースは、既に解放されています。

vtbl 19 HRESULT Unmarshal(void* pBuffer, DWORD cbBuffer, DWORD dataRep, CALLFRAME_MARSHALCONTEXT* pcontext, DWORD* pcbUnmarshalled)

以前にマーシャリングされた呼び出しの [out] 引数を含むデータパケットを、既存のアクティベーションレコードにアンマーシャリングします。

pBuffervoid*inマーシャリングされた [out] 値を含むバッファーへのポインター。
cbBufferDWORDinバッファーのサイズ (バイト単位)。
dataRepDWORDinデータのマーシャリングに使用された NDR データ表現。詳細については、IRpcChannelBuffer::GetBuffer を参照してください。
pcontextCALLFRAME_MARSHALCONTEXT*inアンマーシャリングの実行方法に関するコンテキスト情報を含む CALLFRAME_MARSHALCONTEXT 構造体へのポインター。
pcbUnmarshalledDWORD*out正常にアンマーシャリングされたバイト数を受け取ります。この引数はエラー時にも返されます。この引数は省略可能です。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。

解説(Remarks)

アンマーシャリング時には、[in, out] 引数の [in] 側の値が解放され、インターフェースポインターは解放されて [out] 側の値に置き換えられます。すべての [in, out] および [out] 引数は常に妥当な値、すなわち [in]、[in, out] の値、返されたデータから正常にアンマーシャリングされた [out] の値、または明示的に NULL に初期化された値のいずれかに設定されます。失敗が返された場合、呼び出し元は通常、NULL ではない値をクリーンアップするために ICallFrame::Free を呼び出すことになります。

vtbl 20 HRESULT ReleaseMarshalData(void* pBuffer, DWORD cbBuffer, DWORD ibFirstRelease, DWORD dataRep, CALLFRAME_MARSHALCONTEXT* pcontext)

マーシャリングされたデータのパケット内に存在するインターフェースポインターが保持しているリソースを解放します。このメソッドはパケット内のすべてのインターフェースポインターを検索し、それぞれに対して CoReleaseMarshalData 関数を呼び出します。

pBuffervoid*inマーシャリングされた [out] 値を含むバッファーへのポインター。
cbBufferDWORDinバッファーのサイズ (バイト単位)。
ibFirstReleaseDWORDinバッファー内で解放を開始する最初のバイト。値が 0 の場合は、バッファー全体のインターフェースポインターが解放されることを意味します。マーシャリングされたインターフェースポインターは、他の何らかの仕組みによって既に解放されているものとみなされます。
dataRepDWORDinデータのマーシャリングに使用されたデータ表現。
pcontextCALLFRAME_MARSHALCONTEXT*inアンマーシャリングの実行方法に関するコンテキスト情報を含む CALLFRAME_MARSHALCONTEXT 構造体へのポインター。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
E_UNEXPECTED
予期しないエラーが発生しました。

解説(Remarks)

マーシャリングされたバッファーが保持するリソースをクリーンアップするには、ReleaseMarshalData メソッドをちょうど 1 回呼び出す必要があります。ただし、MSHLFLAGS 列挙型が MSHLFLAGS_NORMAL に設定されている場合、これはアンマーシャリング時に自動的に行われるため、明示的に実行する必要はありません。

このメソッドは、マーシャリングされた [in] 引数と [out] 引数のどちらに対しても正しく機能します。

vtbl 21 HRESULT Invoke(void* pvReceiver)

このアクティベーションレコードをオブジェクトに適用します。マーシャリングを伴う状況では、通常これはサーバー側で実行され、実際のオブジェクトの処理を実行する手段となります。

pvReceivervoid*in呼び出しを行う対象のインターフェース。このインターフェースが適切な IID のものであることを保証する責任は呼び出し元にあります。実装は単にキャストを行い、そうであるものとみなします。

戻り値

このメソッドは次の値を返すことがあります。

戻り値 説明
S_OK
メソッドは正常に完了しました。
CALLFRAME_E_ALREADYINVOKED
このフレームからは既に呼び出しが行われています。
E_UNEXPECTED
予期しないエラーが発生しました。

解説(Remarks)

一般に、呼び出しの実行では、新しいスタックフレームを割り当て、元のフレームのデータを浅くコピーしてから、指定されたオブジェクトの適切なメソッドを呼び出します。呼び出されたオブジェクトは、その呼び出しの適切なセマンティクスに従って、コピーされたフレームから到達可能な [out] 引数を変更することができます。オブジェクトから呼び出しが戻ると、呼び出しフレームは ICallFrame::SetReturnValue による戻り値を自動的に取得します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
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 指定が可能。