IOleItemContainer
COM公式ドキュメント
アイテムモニカーが、識別対象のオブジェクトにバインドされる際に使用されます。
メソッド 3
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
指定したオブジェクトへのポインターを取得します。
| pszItem | LPWSTR | in | 要求するオブジェクトに対するコンテナー内での名前です。 |
| dwSpeedNeeded | DWORD | in | 呼び出し側がオブジェクトを取得するためにおおよそどの程度待機するかを示します。指定可能な値は列挙体 BINDSPEED から取得します。 |
| pbc | IBindCtx* | in | このバインド操作で使用するバインドコンテキストオブジェクト上の IBindCtx インターフェイスへのポインターです。バインドコンテキストは、バインド処理中にバインドされたオブジェクトをキャッシュし、そのバインドコンテキストを使用するすべての操作に適用されるパラメーターを保持します。また、バインドの実装が自身の実行環境に関する情報を取得するための手段を提供します。 |
| riid | GUID* | in | 要求するインターフェイスポインターの識別子への参照です。 |
| ppvObject | void** | out | riid で要求したインターフェイスポインターを受け取るポインター変数のアドレスです。正常に返された場合、*ppvObject には pszItem で指定した名前のオブジェクトに対する、要求したインターフェイスポインターが格納されます。成功時には、実装は *ppvObject に対して AddRef を呼び出す必要があります。Release を呼び出すのは呼び出し側の責任です。エラーが発生した場合、実装は *ppvObject を NULL に設定します。 |
戻り値
このメソッドは、標準的な戻り値 E_OUTOFMEMORY のほか、次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
| バインド操作を、バインドコンテキストの BIND_OPTS 構造体で指定された制限時間内、または dwSpeedNeeded パラメーターで示された速度で完了できませんでした。 | |
| pszItem パラメーターは、このコンテナー内のオブジェクトを識別していません。 | |
| 要求したインターフェイスは利用できませんでした。 |
解説(Remarks)
アイテムモニカーによる IMoniker::BindToObject の実装は、アイテムモニカー内に格納された名前を pszItem パラメーターとして渡し、このメソッドを呼び出します。
実装者への注意
IOleItemContainer::GetObject の実装では、まず pszItem がコンテナーのオブジェクトのいずれかに対する有効な名前であるかどうかを判定してください。有効でない場合は MK_E_NOOBJECT を返す必要があります。pszItem が埋め込みオブジェクトまたはリンクオブジェクトを指す場合、実装は dwSpeedNeeded パラメーターの値を確認する必要があります。値が BINDSPEED_IMMEDIATE で、かつオブジェクトがまだ読み込まれていない場合は、MK_E_EXCEEDEDDEADLINE を返す必要があります。オブジェクトが読み込まれている場合、実装は(たとえば OleIsRunning 関数を呼び出すなどして)オブジェクトが実行中かどうかを判定してください。実行中でなく、dwSpeedNeeded の値が BINDSPEED_MODERATE の場合、実装は MK_E_EXCEEDEDDEADLINE を返す必要があります。オブジェクトが実行中でなく、dwSpeedNeeded が BINDSPEED_INDEFINITE の場合、実装は OleRun 関数を呼び出してオブジェクトを実行状態にする必要があります。その後、要求されたインターフェイスをオブジェクトに対してクエリできます。インターフェイスをクエリする前にオブジェクトが実行中であることが重要である点に注意してください。
pszItem が擬似オブジェクトを指す場合、擬似オブジェクトはコンテナーが実行中であればつねに実行中であるため、実装は dwSpeedNeeded パラメーターを無視できます。この場合、実装は要求されたインターフェイスを単純にクエリできます。
dwSpeedNeeded で示される情報よりも制限時間について詳しい情報が必要な場合は、pbc パラメーターに対して IBindCtx::GetBindOptions を呼び出して、実際のデッドラインパラメーターを取得できます。
指定したオブジェクトのストレージへのポインターを取得します。
| pszItem | LPWSTR | in | ストレージを要求する対象のオブジェクトに対する、複合ドキュメント内での名前です。 |
| pbc | IBindCtx* | in | このバインド操作で使用するバインドコンテキスト上の IBindCtx インターフェイスへのポインターです。バインドコンテキストは、バインド処理中にバインドされたオブジェクトをキャッシュし、そのバインドコンテキストを使用するすべての操作に適用されるパラメーターを保持します。また、バインドの実装が自身の実行環境に関する情報を取得するための手段を提供します。 |
| riid | GUID* | in | オブジェクトとの通信に使用するインターフェイスの識別子への参照で、通常は IStorage です。 |
| ppvStorage | void** | out | riid で要求したインターフェイスポインターを受け取るポインター変数のアドレスです。正常に返された場合、*ppvStorage には pszItem で指定した名前のオブジェクトのストレージに対する、要求したインターフェイスポインターが格納されます。成功時には、実装は ppvStorage に対して AddRef を呼び出す必要があります。Release を呼び出すのは呼び出し側の責任です。エラーが発生した場合、ppvStorage は NULL に設定されます。 |
戻り値
このメソッドは、標準的な戻り値 E_OUTOFMEMORY のほか、次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| メソッドは正常に完了しました。 | |
|
pszItem パラメーターは、このコンテナー内のオブジェクトを識別していません。 |
| オブジェクトは独自の独立したストレージを持っていません。 | |
| 要求したインターフェイスは利用できません。 |
解説(Remarks)
アイテムモニカーによる IMoniker::BindToStorage の実装は、このメソッドを呼び出します。
実装者への注意
pszItem が擬似オブジェクトを指す場合、擬似オブジェクトは独自の独立したストレージを持たないため、IOleItemContainer::GetObjectStorage の実装は MK_E_NOSTORAGE を返す必要があります。pszItem が埋め込みオブジェクト、または独自のストレージを持つドキュメントの一部分を指す場合、実装は適切なストレージオブジェクト上の、指定されたインターフェイスポインターを返す必要があります。指定したオブジェクトが実行中かどうかを判定します。
| pszItem | LPWSTR | in | オブジェクトに対するコンテナー内での名前です。 |
戻り値
このメソッドは、次の値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| オブジェクトは実行中です。 | |
| オブジェクトは実行中ではありません。 | |
| パラメーターは、このコンテナー内のオブジェクトを識別していません。 |
解説(Remarks)
アイテムモニカーによる IMoniker::IsRunning の実装は、このメソッドを呼び出します。
実装者への注意
IOleItemContainer::IsRunning の実装では、まず pszItem がコンテナーのオブジェクトのいずれかを識別しているかどうかを判定してください。識別していない場合、実装は MK_E_NOOBJECT を返す必要があります。オブジェクトが読み込まれていない場合、実装は S_FALSE を返す必要があります。読み込まれている場合、実装は OleIsRunning 関数を呼び出して、実行中かどうかを判定できます。pszItem が擬似オブジェクトを指す場合、擬似オブジェクトはコンテナーが実行中であればつねに実行中であるため、実装は単純に S_OK を返すことができます。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IOleItemContainer "{0000011C-0000-0000-C000-000000000046}" #usecom global IOleItemContainer IID_IOleItemContainer "{}" #comfunc global IOleItemContainer_GetObject 6 wstr,int,sptr,var,sptr #comfunc global IOleItemContainer_GetObjectStorage 7 wstr,sptr,var,sptr #comfunc global IOleItemContainer_IsRunning 8 wstr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IOleItemContainer "{0000011C-0000-0000-C000-000000000046}" #usecom global IOleItemContainer IID_IOleItemContainer "{}" #comfunc global IOleItemContainer_GetObject 6 wstr,int,sptr,sptr,sptr #comfunc global IOleItemContainer_GetObjectStorage 7 wstr,sptr,sptr,sptr #comfunc global IOleItemContainer_IsRunning 8 wstr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。