IMoniker::BindToObject メソッド (objidl.h)

  • [アーティクル]

指定したオブジェクトにバインドします。 バインド プロセスでは、オブジェクトを見つけ、必要に応じて実行状態にし、識別されたオブジェクトの指定されたインターフェイスへのポインターを呼び出し元に提供します。

構文

HRESULT BindToObject(
  [in]  IBindCtx *pbc,
  [in]  IMoniker *pmkToLeft,
  [in]  REFIID   riidResult,
  [out] void     **ppvResult
);

パラメーター

[in] pbc

バインド コンテキスト オブジェクトの IBindCtx インターフェイスへのポインター。このバインド操作で使用されます。 バインド コンテキストは、バインド プロセス中にバインドされたオブジェクトをキャッシュし、バインド コンテキストを使用するすべての操作に適用されるパラメーターを含み、モニカー実装がその環境に関する情報を取得する手段を提供します。

[in] pmkToLeft

モニカーが複合モニカーの一部である場合は、このモニカーの左側にあるモニカーへのポインター。 このパラメーターは、複合モニカーのさまざまなコンポーネント間の連携を可能にするために、モニカー実装者によって主に使用されます。 モニカー クライアントでは NULL を使用する必要があります。

[in] riidResult

モニカーが識別するオブジェクトとの通信にクライアントが使用するインターフェイスの IID。

[out] ppvResult

riid で要求されたインターフェイス ポインターを受け取るポインター変数のアドレス。 正常に戻ると、*ppvResult にはモニカーが識別するオブジェクトへの要求されたインターフェイス ポインターが含まれます。 成功した場合、実装ではモニカーで AddRef を呼び出す必要があります。 Release を呼び出すのは呼び出し元の責任です。 エラーが発生した場合、*ppvResult は NULL である必要があります。

戻り値

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

リターン コード 説明
S_OK
 バインド操作が成功しました。
MK_E_NOOBJECT
 このモニカーによって識別されるオブジェクト、またはこのモニカーが一部である複合モニカーによって識別されるオブジェクトが見つかりませんでした。
MK_E_EXCEEDEDDEADLINE
 バインド 操作は、バインド コンテキストの BIND_OPTS 構造体で指定された制限時間内 に 完了できませんでした。
MK_E_CONNECTMANUALLY
 バインド操作には、エンド ユーザーからの支援が必要です。 この値を返す最も一般的な理由は、パスワードが必要であるか、フロッピーをマウントする必要があるということです。 この値が返されたら、キー "ConnectManually" を使用して IBindCtx::GetObjectParam を呼び出してエラーの原因となったモニカーを取得します。 その後、 IMoniker::GetDisplayName を呼び出して表示名を取得し、フロッピーをマウントする手順やパスワードの要求などの目的の情報を伝えるダイアログ ボックスを表示し、バインド操作を再試行します。
MK_E_INTERMEDIATEINTERFACENOTSUPPORTED
 中間オブジェクトが見つかりましたが、バインド操作を完了するために必要なインターフェイスはサポートされていませんでした。 たとえば、項目モニカーは、コンテナーが IOleItemContainer インターフェイスをサポートしていない場合、この値を返します。
STG_E_ACCESSDENIED
 ストレージ オブジェクトにアクセスできません。
 

このメソッドは、 IOleItemContainer::GetObject メソッドに関連付けられているエラーを返すこともできます。

注釈

BindToObject はモニカーのプライマリ関数を実装します。モニカーによって識別されるオブジェクトを検索し、そのインターフェイスの 1 つへのポインターを返します。

呼び出し元へのメモ

モニカーを 2 つのオブジェクト間の永続的な接続として使用している場合は、 BindToObject を呼び出して接続をアクティブ化します。

通常、次のプロセス中に BindToObject を呼び出します。

  1. CreateBindCtx 関数を呼び出してバインド コンテキスト オブジェクトを作成します。
  2. モニカーを使用して BindToObject を呼び出し、識別されたオブジェクトの目的のインターフェイスへのポインターを取得します。
  3. バインド コンテキストを解放します。
  4. 取得したインターフェイス ポインターを使用して、オブジェクトに対して目的の操作を実行します。
  5. オブジェクトが終了したら、オブジェクトのインターフェイス ポインターを解放します。
次のコード フラグメントは、これらの手順を示しています。 
HRESULT hr;       // An error code
IMoniker * pMnk;  // A previously acquired interface moniker

// Obtain an IBindCtx interface.
IBindCtx * pbc; 
hr = CreateBindCtx(NULL, &pbc); 
if (FAILED(hr)) exit(0);  // Handle errors here. 
   
// Obtain an implementation of pCellRange. 
ICellRange * pCellRange; 
hr = pMnk->BindToObject(pbc, NULL, IID_ICellRange, &pCellRange); 
if (FAILED(hr)) exit(0);  // Handle errors here. 

// Use pCellRange here. 

// Release interfaces after use. 
pbc->Release(); 
pCellRange->Release();

バインド操作を 1 つだけ行い、バインド コンテキスト オブジェクトを保持する必要がない場合は、 BindMoniker 関数を使用することもできます。 このヘルパー関数は、バインド コンテキストの作成をカプセル化し、 BindToObject を 呼び出してバインド コンテキストを解放します。

オブジェクトへのリンクをサポートする COM コンテナーはモニカーを使用して、リンクされたオブジェクトを見つけてアクセスしますが、通常は BindToObject を直接呼び出しません。 代わりに、ユーザーがコンテナー内のリンクをアクティブ化すると、リンク コンテナーは通常、リンク ハンドラーの実装を使用して IOleObject::D oVerb を呼び出します。これは、リンク オブジェクトに格納されているモニカーで BindToObject を呼び出します (動詞を処理できない場合)。

実装者へのメモ

実装の動作は、モニカーにプレフィックスが付けられているかどうかによって異なります。つまり、 pmkToLeft パラメーターが NULL である必要があるかどうか。 たとえば、コンテナー内のオブジェクトを識別する項目モニカーは、 pmkToLeft がコンテナーを識別することを想定しています。 その結果、アイテム モニカーは pmkToLeft を使用してそのコンテナーからサービスを要求します。 モニカーにプレフィックスが必要な場合は、 pmkToLeft パラメーター (たとえば、それに 対する BindToObject の 呼び出し) を使用して、識別するオブジェクトからサービスを要求する必要があります。

モニカーにプレフィックスがない場合、BindToObject 実装では、まず実行中のオブジェクト テーブル (ROT) をチェックして、オブジェクトが既に実行されているかどうかを確認する必要があります。 ROT へのポインターを取得するには、実装で pbc パラメーターで IBindCtx::GetRunningObjectTable を呼び出す必要があります。 その後、 IRunningObjectTable::GetObject メソッドを呼び出して、現在のモニカーが ROT に登録されているかどうかを確認できます。 その場合は、 すぐに QueryInterface を 呼び出して、呼び出し元によって要求されたインターフェイスへのポインターを取得できます。

BindToObject 実装が何らかのオブジェクトにバインドする場合は、バインド コンテキストでバインドされたオブジェクトへの参照を格納するために、pbc パラメーターを使用して IBindCtx::RegisterObjectBound を呼び出す必要があります。 これにより、バインド コンテキストが解放されるまで、バインドされたオブジェクトが実行されたままになります。これにより、後続のバインド操作で後で再度読み込まれるコストを回避できます。

バインド コンテキストの BIND_OPTS 構造体で BINDFLAGS_JUSTTESTEXISTENCE フラグが指定されている場合、実装には ppvResult で NULL を返すオプションがあります (ただし、フラグを無視して完全なバインド操作を実行することもできます)。

実装固有の注意事項

実装 メモ
アンチモニカー このメソッドは実装されていません。 E_NOTIMPLを返します。
クラス モニカー pmkLeft が NULL の場合は、クラス モニカーが初期化された CLSID (CreateClassMoniker または MkParseDisplayName を使用) と現在の pbc (IBindCtx) の CLSCTX を使用して CoGetClassObject を呼び出します。

pmkLeft が NULL 以外の場合は、IClassActivator に対して pmkLeft-BindToObject> を呼び出し、初期化された CLSID と、現在の pbc (IBindCtx) の CLSCTX パラメーターとロケール パラメーターを使用して IClassActivator::GetClassObject を呼び出します。
ファイル モニカー pmkToLeft が NULL の場合、メソッドは ROT でモニカーを検索し、見つかった場合は、要求されたインターフェイス ポインターについて取得したオブジェクトに対してクエリを実行します。 モニカーが ROT に見つからない場合、メソッドはファイル システムから オブジェクトを読み込み、要求されたインターフェイス ポインターを取得します。

pmkLeft が NULL でない場合は、GetClassFile (またはその他の手段) を使用してファイル モニカーによって参照されるファイルの内容を使用してインスタンス化および初期化するクラスを決定する代わりに、iClassFactory および IClassActivator の pmkLeft-BindToObject> を呼び出し、pcf でこのポインターを取得します。 これがE_NOINTERFACEで失敗した場合は、MK_E_INTERMEDIATEINTERFACENOTSUPPORTEDを返します。

IClassFactory ポインターが正常に取得された場合は、pcf-CreateInstance>(IID_IPersistFile,(void**)&ppf) を呼び出して、初期化するクラスの新しいインスタンスを取得し、IPersistFile またはファイル モニカーの既存の初期化パスに従ったその他の適切な手段を使用して初期化します。
汎用複合モニカー pmkToLeft が NULL の場合、このメソッドは ROT 内のモニカーを検索し、見つかった場合は、要求されたインターフェイス ポインターを取得したオブジェクトに対してクエリを実行します。 pmkToLeft が NULL でない場合、メソッドは複合の右端のコンポーネントで BindToObject を再帰的に呼び出し、その呼び出しの pmkToLeft パラメーターとして複合の残りの部分を渡します。
アイテム モニカー pmkToLeft が NULL の場合、このメソッドはE_INVALIDARGを返します。 それ以外の場合、メソッドは pmkToLeft パラメーターで BindToObject を呼び出し、IOleItemContainer インターフェイス ポインターを要求します。 次に、 メソッドは IOleItemContainer::GetObject を呼び出し、モニカーに含まれる文字列を渡し、要求されたインターフェイス ポインターを返します。
OBJREF モニカー pmkToLeft パラメーターは NULL である必要があります。 OBJREF モニカーは実行中のオブジェクトを表しているため、アクティブ化は行われません。 表されたオブジェクトが実行されなくなった場合、 BindToObject はE_UNEXPECTEDで失敗します。
ポインター モニカー このメソッドは、要求されたインターフェイスのラップされたポインターに対してクエリを実行します。
URL モニカー URL モニカーは非同期バインディングをサポートしているため、 BindToObject の実際の戻り値は、バインド コンテキストで確立されたオブジェクト パラメーターによって異なる場合があります。 詳細については、以下を参照してください。
 

URL モニカーのバインド操作のセマンティクスは、同期または非同期の使用に関係なく同一であり、次のようになります。

  1. URL モニカーは、バインド 操作の詳細情報をバインド コンテキストから取得します。 たとえば、モニカーは、バインド コンテキストに登録されている IBindStatusCallback インターフェイスと IEnumFORMATETC インターフェイスへのポインターを取得できます。 詳細については、バインド コンテキストで IBindCtx::SetBindOptions を使用して指定された追加のバインド オプション ( dwTickCountDeadline パラメーター、BIND_MAYBOTHERUSERの grfFlags 値など) を含めることができます。
  2. 次に、モニカーはバインド コンテキストの ROT をチェックして、参照先オブジェクトが既に実行されているかどうかを判断します。 モニカーは、次の呼び出しでこの情報を取得できます。
    IBindCtx::GetRunningObjectTable(&prot)
prot->IsRunning(this)
  3. オブジェクトが既に実行されている場合、モニカーは次の呼び出しで実行中のオブジェクトを取得します。
    prot->GetObject(this, &punk)
  4. 次に、モニカーは、要求されたインターフェイスに対して QueryInterface を呼び出します。
  5. それ以外の場合、モニカーは IBindStatusCallback::GetBindInfo を呼び出してクライアントに対してクエリを実行し、追加のバインド情報を取得します。 その後、モニカーはバインド操作を開始し、 IBindStatusCallback::OnStartBinding を呼び出して、結果の IBinding インターフェイスをクライアントに渡します。
  6. 手順 1 でこれが非同期バインドであると判断された場合、BindToObject はこの時点で ppv の NULL でMK_S_ASYNCHRONOUSを返します。 呼び出し元は、 後で IBindStatusCallback::OnObjectAvailable メソッドの間に実際のオブジェクト ポインターを受け取ります。 次の手順は、呼び出し元 (通常は別の実行スレッド) に対して非同期的に実行されます。
  7. URL モニカーによって指定されたリソースのクラスは、次のいずれかの方法で決定されます。
    • URL モニカーは、データのメディアの種類を調べます。 メディアの種類が application/x-oleobject の場合、実際のデータの最初の 16 バイト (Content-Body) にはリソースの CLSID が含まれ、後続のデータはクラス自体によって解釈されます。 その他のすべてのメディアの種類では、URL モニカーは、HKEY_CLASSES_ROOT\MIME\Database\Content-Type\<media-type>\CLSID キーをシステム レジストリで検索します。 application/x-oleobject は、application/oleobject が承認されるまで使用されることに注意してください。
    • URL モニカーは、到着するデータの一部を、システム レジストリに登録されているパターンに一致 HKEY_CLASSES_ROOT\FileTypes。
    • 最後に、他のすべてが失敗した場合、URL モニカーはリソースの末尾の拡張機能 (存在する場合) を、HKEY_CLASSES_ROOT\.??? を使用して CLSID に関連付けます。 GetClassFile とシェルによって行われるように、システム レジストリのキー。
  8. クラスを決定すると、URL モニカーは、IUnknown インターフェイスを要求する CLSCTX_SERVER の CoCreateInstance を使用してインスタンスを作成します。
  9. URL モニカーは次に、IPersistMoniker インターフェイス用に新しく作成されたオブジェクトの QueryInterface メソッドを呼び出します。 QueryInterface が成功した場合、URL モニカーは、モニカー パラメーターとして IPersistMoniker::Load パッシング自体 (this) を呼び出します。 オブジェクトは通常 、BindToStorage を呼び出して、関心のあるストレージ インターフェイスを要求します。
  10. それ以外の場合、URL モニカーは IPersistStream の QueryInterface を呼び出し、成功した場合は IPersistStream::Load を呼び出し、トランスポートによって非同期的に塗りつぶされているストリーム オブジェクトの IStream ポインターをオブジェクトに渡します。

    呼び出されるクラスがカテゴリ CATID_AsyncAwareでマークされていない場合は、データが使用可能になるまで、まだ使用できないデータを参照する ISequentialStream::Read または ISequentialStream::Write を 呼び出します。 これらの呼び出しは、従来の COM の意味で ブロックを呼び出します。 特定のメッセージの処理を許可するメッセージ ループが入力され、スレッドの IMessageFilter が適切に呼び出されます。

    クラスがカテゴリ CATID_AsyncAwareでマークされている場合は、まだ使用できないデータを参照する ISequentialStream::Read または ISequentialStream::Write を呼び出E_PENDING。

  11. それ以外の場合、URL モニカーは IPersistFile の QueryInterface を呼び出し、成功した場合は一時ファイルへのダウンロードを完了します。 完了すると、URL モニカーは IPersistFile::Load を呼び出します。 作成されたファイルは、他のインターネットダウンロードデータと共にキャッシュされます。 クライアントは、このファイルを削除しないようにする必要があります。
  12. 前の手順で説明したさまざまな Load 呼び出しの 1 つからオブジェクトが返されると、URL モニカーは IBindStatusCallback::OnObjectAvailable メソッドを呼び出して、クライアントが BindToObject を呼び出したときにクライアントが最初に要求したインターフェイス ポインターを返します。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー objidl.h

こちらもご覧ください

BindMoniker

Imoniker