ホーム › System.Com › IBindCtx

IBindCtx

COM

📘 Microsoft Learn (日本語) · English

IID0000000e-0000-0000-c000-000000000046継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

バインドコンテキストへのアクセスを提供します。バインドコンテキストとは、特定のモニカーバインド操作に関する情報を格納するオブジェクトです。

解説(Remarks)

バインドコンテキストには、次の情報が含まれます。

バインド操作中に変化しない一連のパラメーターを保持する BIND_OPTS 構造体。合成モニカーがバインドされる際、各構成要素は同じバインドコンテキストを使用するため、これは合成モニカーの各構成要素に同じパラメーターを渡すためのしくみとして機能します。
バインド操作によってアクティブ化されたオブジェクトへのポインターの集合。バインドコンテキストはこれらのバインド済みオブジェクトへのポインターを保持し、それらをロードされた状態に保ちます。これにより、後続のバインド操作で同じオブジェクトが再び必要になった場合に、冗長なアクティブ化を回避できます。
バインド操作を開始したプロセスと同じコンピューター上にある実行中オブジェクトテーブル (ROT) へのポインター。ROT にアクセスする必要があるモニカー実装では、GetRunningObjectTable 関数ではなく IBindCtx::GetRunningObjectTable メソッドを使用してください。これにより、将来システムの IBindCtx 実装が拡張されてバインド動作が変更された場合にも対応できます。
それぞれ文字列キーに関連付けられたインターフェイスポインターのテーブル。この機能により、モニカー実装は既知の文字列の下にインターフェイスポインターを格納し、後でバインドコンテキストから取得できます。たとえば OLE は、バインド操作中にエラーを引き起こしたオブジェクトへのポインターを格納するために使用できるいくつかの文字列キー ("ExceededDeadline"、"ConnectManually" など) を定義しています。

メソッド 10

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

vtbl 3 HRESULT RegisterObjectBound(IUnknown* punk)

オブジェクトをバインドコンテキストに登録し、バインドコンテキストが解放されるまでそのオブジェクトがアクティブなまま維持されるようにします。

punk

IUnknown*

バインド済みとして登録されるオブジェクト上の IUnknown インターフェイスへのポインター。

戻り値

このメソッドは、標準の戻り値 E_OUTOFMEMORY および S_OK を返すことができます。

解説(Remarks)

新しいモニカークラスを (IMoniker インターフェイスの実装を通じて) 作成する場合、実装がオブジェクトをアクティブ化するたびにこのメソッドを呼び出してください。これはモニカーのバインド処理中に発生することが最も多いですが、モニカーの表示名を取得する際、表示名をモニカーに解析する際、あるいはオブジェクトが最後に変更された時刻を取得する際にも発生します。

RegisterObjectBound は AddRef を呼び出して、オブジェクトへの参照を追加で作成します。ただし、呼び出し側は自身が保持するポインターのコピーを引き続き解放する必要があります。同じオブジェクトに対してこのメソッドを 2 回呼び出すと、そのオブジェクトへの参照が 2 つ作成されます。このメソッドの呼び出しによって取得した参照は、IBindCtx::RevokeObjectBound を呼び出すことで解放できます。バインドコンテキストが保持するすべての参照は、バインドコンテキスト自体が解放されるときに解放されます。

RegisterObjectBound を呼び出してオブジェクトをバインドコンテキストに登録すると、バインドコンテキストが解放されるまでそのオブジェクトはアクティブなまま維持されます。後続のバインド操作 (同じ合成モニカーの別の部分に対するものでも、別のモニカーに対するものでも) でバインドコンテキストを再利用すると、そのオブジェクトを再ロードする必要がないため、後続のバインド操作をより効率的にできます。ただし、これによって性能が向上するのは、後続のバインド操作が元の操作と同じオブジェクトの一部を必要とする場合に限られます。したがって、バインドコンテキストを再利用することによる性能向上の可能性と、オブジェクトを不必要にアクティブなまま維持するコストとを比較検討する必要があります。

IBindCtx は、RegisterObjectBound を使用して登録されたオブジェクトへのポインターを取得するメソッドを提供していません。オブジェクトが実行中オブジェクトテーブルに自身を登録していれば、モニカー実装は IRunningObjectTable::GetObject を呼び出してそのオブジェクトへのポインターを取得できます。

vtbl 4 HRESULT RevokeObjectBound(IUnknown* punk)

バインドコンテキストからオブジェクトを削除し、以前の RegisterObjectBound の呼び出しを取り消します。

punk

IUnknown*

削除するオブジェクト上の IUnknown インターフェイスへのポインター。

戻り値

このメソッドは、次の値を返すことができます。

戻り値	説明
S_OK	オブジェクトは正常に解放されました。
MK_E_NOTBOUND	オブジェクトは以前に登録されていませんでした。

解説(Remarks)

このメソッドを呼び出すことはめったにありません。主に完全性のためにドキュメント化されています。

vtbl 5 HRESULT ReleaseBoundObjects()

RegisterObjectBound の呼び出しによって以前に登録されたすべてのオブジェクトへのすべてのポインターを解放します。

戻り値

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

解説(Remarks)

このメソッドを直接呼び出すことはめったにありません。システムの IBindCtx 実装は、バインドコンテキスト上の IBindCtx インターフェイスへのポインターが解放される (バインドコンテキストが解放される) ときに、このメソッドを呼び出します。バインドコンテキストが解放されない場合、登録されたすべてのオブジェクトはアクティブなまま残ります。

同じオブジェクトが複数回登録されている場合、このメソッドはそのオブジェクトの Release メソッドを、登録された回数だけ呼び出します。

vtbl 6 HRESULT SetBindOptions(BIND_OPTS* pbindopts)

バインドコンテキストに格納されているバインドパラメーターに新しい値を設定します。

pbindopts

BIND_OPTS*

バインドパラメーターを保持する BIND_OPTS3 構造体へのポインター。

戻り値

このメソッドは、標準の戻り値 E_OUTOFMEMORY および S_OK を返すことができます。

解説(Remarks)

バインドコンテキストには、ほとんどの IMoniker 操作に共通するパラメーターのブロックが含まれます。これらのパラメーターは、操作が合成モニカーのある部分から別の部分へ移っても変化しません。

後続のバインド操作では、IBindCtx::GetBindOptions を呼び出してこれらのパラメーターを取得できます。

呼び出し側への注意

このメソッドは、モニカークライアント (モニカーを使用してオブジェクトへのインターフェイスポインターを取得する側) が呼び出すことができます。

CreateBindCtx 関数を使用してバインドコンテキストを最初に作成したとき、BIND_OPTS 構造体のフィールドは次の値に初期化されます。

    cbStruct = sizeof(BIND_OPTS); 
    grfFlags = 0; 
    grfMode = STGM_READWRITE; 
    dwTickCountDeadline = 0;

バインドコンテキストを使用する前に、既定値以外の値を使用したい場合は、IBindCtx::SetBindOptions メソッドを使用してこれらの値を変更できます。

SetBindOptions は指定された構造体のメンバーをコピーしますが、COSERVERINFO 構造体とそれが含むポインターはコピーしません。呼び出し側は、バインドコンテキストが解放されるまでこれらのポインターを解放してはなりません。

vtbl 7 HRESULT GetBindOptions(BIND_OPTS* pbindopts)

このバインドコンテキストに格納されているバインドオプションを取得します。

pbindopts

BIND_OPTS*

inout

戻り時に現在のバインドパラメーターを受け取る、初期化済みの構造体へのポインター。BIND_OPTS3 を参照してください。

戻り値

このメソッドは、標準の戻り値 E_UNEXPECTED および S_OK を返すことができます。

解説(Remarks)

バインドコンテキストには、ほとんどの IMoniker 操作に共通し、操作が合成モニカーのある部分から別の部分へ移っても変化しないパラメーターのブロックが含まれます。

呼び出し側への注意

通常、このメソッドは独自のモニカークラスを記述している場合に呼び出します。(これには IMoniker インターフェイスの実装が必要です。) このメソッドを呼び出して、モニカークライアントが指定したパラメーターを取得します。

このメソッドによって埋められる構造体を初期化しておく必要があります。このメソッドを呼び出す前に、cbStruct メンバーを構造体のサイズに初期化しておく必要があります。

vtbl 8 HRESULT GetRunningObjectTable(IRunningObjectTable** pprot)

このバインドコンテキストが実行されているコンピューターの、実行中オブジェクトテーブル (ROT) へのインターフェイスポインターを取得します。

pprot

IRunningObjectTable**

out

実行中オブジェクトテーブルへのインターフェイスポインターを受け取る IRunningObjectTable* ポインター変数のアドレス。エラーが発生した場合、pprot は NULL に設定されます。pprot が NULL 以外の場合、実装は実行中テーブルオブジェクトに対して AddRef を呼び出します。Release を呼び出すのは呼び出し側の責任です。

戻り値

このメソッドは、標準の戻り値 E_OUTOFMEMORY、E_UNEXPECTED、および S_OK を返すことができます。

解説(Remarks)

実行中オブジェクトテーブルは、各コンピューター上でグローバルにアクセス可能なテーブルです。コンピューター上で現在実行中のすべてのオブジェクトを追跡します。

呼び出し側への注意

通常、GetRunningObjectTable を呼び出すのは、新しいモニカークラスを (IMoniker インターフェイスの実装を通じて) 実装する側です。オブジェクトが現在実行中かどうかを確認するために、IMoniker::BindToObject や IMoniker::IsRunning の実装でこのメソッドを呼び出すと便利です。また、IMoniker::GetTimeOfLastChange の実装でこのメソッドを呼び出して、実行中のオブジェクトが最後に変更された時刻を知ることもできます。

モニカー実装では、GetRunningObjectTable 関数を使用する代わりにこのメソッドを呼び出してください。これにより、将来の IBindCtx 実装がバインド動作を変更できるようになります。

vtbl 9 HRESULT RegisterObjectParam(LPWSTR pszKey, IUnknown* punk)

バインドコンテキストの文字列キー付きポインターテーブルにおいて、オブジェクトを文字列キーに関連付けます。

pszKey

LPWSTR

オブジェクトを登録する対象のバインドコンテキスト文字列キー。キー文字列の比較は大文字と小文字を区別します。

punk

IUnknown*

登録するオブジェクト上の IUnknown インターフェイスへのポインター。

このメソッドは、そのポインターに対して AddRef を呼び出します。

戻り値

このメソッドは、標準の戻り値 E_OUTOFMEMORY および S_OK を返すことができます。

解説(Remarks)

バインドコンテキストは、それぞれ文字列キーに関連付けられたインターフェイスポインターのテーブルを保持します。これにより、モニカー実装とバインド操作を開始した呼び出し側との間の通信が可能になります。一方がインターフェイスポインターを両者に既知の文字列の下に格納しておくと、もう一方が後でそれをバインドコンテキストから取得できます。

このメソッドの使用後のバインド操作では、IBindCtx::GetObjectParam を使用して、格納されたポインターを取得できます。

呼び出し側への注意

RegisterObjectParam は、新しいモニカークラスを (IMoniker の実装を通じて) 実装する側と、モニカークライアント (モニカーを使用してオブジェクトにバインドする側) の両方にとって有用です。

新しいモニカークラスを実装する場合、モニカーのバインド中にエラーが発生したときにこのメソッドを呼び出して、エラーの原因を呼び出し側に伝えます。このメソッドの呼び出しで指定するキーは、エラー条件によって異なります。以下は、一般的なモニカーのバインドエラーの一覧であり、それぞれに対して適切なキーを説明しています。

MK_E_EXCEEDEDDEADLINE: 指定されたオブジェクトが実行されていないためにバインド操作が期限を超過した場合、次の一覧から最初の未使用キーを使用してオブジェクトのモニカーを登録してください: "ExceededDeadline"、"ExceededDeadline1"、"ExceededDeadline2" など。呼び出し側が後でそのモニカーを実行中オブジェクトテーブル内で見つけた場合、バインド操作を再試行できます。
MK_E_CONNECTMANUALLY: "ConnectManually" キーは、バインドにエンドユーザーの支援を必要とするモニカーを示します。エンドユーザーにオブジェクトへの手動接続を要求するために、呼び出し側はモニカーの表示名を表示した後でバインド操作を再試行できます。このエラーの一般的な原因は、パスワードが必要である、またはフロッピーディスクをマウントする必要があることです。
E_CLASSNOTFOUND: "ClassNotFound" キーは、クラスが見つからなかったモニカーを示します。(このモニカーが識別するオブジェクトのサーバーが見つかりませんでした。) このキーが OLE 複合ドキュメントオブジェクトに対して使用された場合、呼び出し側は IMoniker::BindToStorage を使用してオブジェクトにバインドし、その後 Treat As... または Convert To... 操作を試みて、オブジェクトを別のサーバーに関連付けることができます。これが成功すれば、呼び出し側はバインド操作を再試行できます。

モニカーの実装に関する詳細な知識を持つモニカークライアントは、このメソッドを呼び出してその実装にプライベートな情報を渡すこともできます。

ポインターを格納するためのキーとして、新しい文字列を定義できます。慣例として、モニカークラスの CLSID の文字列形式で始まるキー名を使用してください。(StringFromCLSID 関数を参照してください。)

pszKey パラメーターがバインドコンテキストのテーブル内の既存のキー名と一致する場合、新しいオブジェクトがテーブル内の既存のオブジェクトを置き換えます。

このメソッドを使用してオブジェクトを登録した場合、次のいずれかが発生するまでオブジェクトは解放されません。

同じキーを持つ別のオブジェクトによってテーブル内で置き換えられる。
IBindCtx::RevokeObjectParam の呼び出しによってテーブルから削除される。
バインドコンテキストが解放される。登録されたすべてのオブジェクトは、バインドコンテキストが解放されるときに解放されます。

vtbl 10 HRESULT GetObjectParam(LPWSTR pszKey, IUnknown** ppunk)

バインドコンテキストの文字列キー付きポインターテーブルにおいて、指定されたキーに関連付けられたオブジェクトへのインターフェイスポインターを取得します。

pszKey	LPWSTR	in	検索対象のバインドコンテキスト文字列キー。キー文字列の比較は大文字と小文字を区別します。
ppunk	IUnknown**	out	pszKey に関連付けられたオブジェクトへのインターフェイスポインターを受け取る IUnknown* ポインター変数のアドレス。成功した場合、実装は *ppunk に対して AddRef を呼び出します。Release を呼び出すのは呼び出し側の責任です。エラーが発生した場合、実装は *ppunk を NULL に設定します。

戻り値

このメソッドが成功した場合、戻り値は S_OK です。それ以外の場合は E_FAIL です。

解説(Remarks)

このメソッドが取得するポインターは、事前に IBindCtx::RegisterObjectParam メソッドを使用してテーブルに挿入されている必要があります。

呼び出し側への注意

モニカーを使用して他のオブジェクトを見つけるオブジェクトは、バインド操作が失敗したときにこのメソッドを呼び出して、発生したエラーに関する具体的な情報を取得できます。エラーによっては、状況を修正してバインド操作を再試行できる場合があります。詳細については IBindCtx::RegisterObjectParam を参照してください。

モニカー実装では、呼び出し側がバインド操作を開始して具体的な情報を要求する状況を処理するために、このメソッドを呼び出すことができます。慣例として、実装側はモニカークラスの CLSID の文字列形式で始まるキー名を使用してください。(StringFromCLSID 関数を参照してください。)

vtbl 11 HRESULT EnumObjectParam(IEnumString** ppenum)

バインドコンテキストの文字列キー付きポインターテーブルのキーを列挙するために使用できるインターフェイスへのポインターを取得します。

ppenum

IEnumString**

out

列挙子へのインターフェイスポインターを受け取る IEnumString* ポインター変数のアドレス。エラーが発生した場合、ppenum は NULL に設定されます。ppenum が NULL 以外の場合、実装は *ppenum に対して AddRef を呼び出します。Release を呼び出すのは呼び出し側の責任です。

戻り値

このメソッドは、標準の戻り値 E_OUTOFMEMORY および S_OK を返すことができます。

解説(Remarks)

列挙子が返すキーは、事前に IBindCtx::RegisterObjectParam の呼び出しで指定されたものです。

呼び出し側への注意

システムの IBindCtx インターフェイスの実装では、このメソッドは実装されていません。したがって、このメソッドを呼び出すと戻り値 E_NOTIMPL が返されます。

vtbl 12 HRESULT RevokeObjectParam(LPWSTR pszKey)

指定されたキーとそれに関連付けられたポインターを、バインドコンテキストの文字列キー付きオブジェクトテーブルから削除します。このキーは、事前に RegisterObjectParam の呼び出しでテーブルに挿入されている必要があります。

pszKey

LPWSTR

削除対象のバインドコンテキスト文字列キー。キー文字列の比較は大文字と小文字を区別します。

戻り値

このメソッドは、次の値を返すことができます。

戻り値	説明
S_OK	指定されたキーは正常に削除されました。
S_FALSE	オブジェクトは以前に登録されていませんでした。

解説(Remarks)

このメソッドは、テーブルからエントリを削除するために使用されます。指定されたキーが見つかった場合、バインドコンテキストはそのオブジェクトへの参照も解放します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IBindCtx "{0000000E-0000-0000-C000-000000000046}"
#usecom global IBindCtx IID_IBindCtx "{}"
#comfunc global IBindCtx_RegisterObjectBound    3 sptr
#comfunc global IBindCtx_RevokeObjectBound      4 sptr
#comfunc global IBindCtx_ReleaseBoundObjects    5
#comfunc global IBindCtx_SetBindOptions         6 var
#comfunc global IBindCtx_GetBindOptions         7 var
#comfunc global IBindCtx_GetRunningObjectTable  8 sptr
#comfunc global IBindCtx_RegisterObjectParam    9 wstr,sptr
#comfunc global IBindCtx_GetObjectParam         10 wstr,sptr
#comfunc global IBindCtx_EnumObjectParam        11 sptr
#comfunc global IBindCtx_RevokeObjectParam      12 wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IBindCtx "{0000000E-0000-0000-C000-000000000046}"
#usecom global IBindCtx IID_IBindCtx "{}"
#comfunc global IBindCtx_RegisterObjectBound    3 sptr
#comfunc global IBindCtx_RevokeObjectBound      4 sptr
#comfunc global IBindCtx_ReleaseBoundObjects    5
#comfunc global IBindCtx_SetBindOptions         6 sptr
#comfunc global IBindCtx_GetBindOptions         7 sptr
#comfunc global IBindCtx_GetRunningObjectTable  8 sptr
#comfunc global IBindCtx_RegisterObjectParam    9 wstr,sptr
#comfunc global IBindCtx_GetObjectParam         10 wstr,sptr
#comfunc global IBindCtx_EnumObjectParam        11 sptr
#comfunc global IBindCtx_RevokeObjectParam      12 wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。