IMoniker

COM オブジェクトを一意に識別する情報を保持する moniker オブジェクトを利用できるようにします。

ファイルシステムにおけるファイルへのパスと同様に、moniker には COM オブジェクトを特定してアクティブ化するための情報が含まれます。moniker は、ファイルに格納されたドキュメントオブジェクトから、埋め込みオブジェクト内の選択範囲まで、あらゆる種類の COM オブジェクトを識別できます。COM は、システム内で最も一般的に見られるオブジェクトを識別する moniker オブジェクトを作成するための一連の moniker クラスを提供します。たとえば、ファイルに格納されたテキストドキュメントに埋め込まれたスプレッドシート内のセル範囲を表すオブジェクトが存在する場合があります。分散システムでは、このオブジェクトの moniker は、オブジェクトのシステムの場所、そのシステム上のファイルの物理的な場所、そのファイル内の埋め込みオブジェクトのストレージ、そして最後に埋め込みオブジェクト内のセル範囲の場所を識別します。

moniker オブジェクトは IMoniker インターフェイスをサポートします。このインターフェイスは IPersistStream インターフェイスから派生しており、システム内の単一のオブジェクトを一意に識別します。moniker を提供するオブジェクトが moniker オブジェクトを作成した後は、その情報をオブジェクト内で変更することはできません。moniker プロバイダーが情報を変更するには、新しい moniker オブジェクトを作成するしかありません。新しい moniker オブジェクトが、対象のオブジェクトを一意に識別することになります。

moniker には次の 2 つの重要な機能があります。

• moniker は永続ストレージに保存できます。moniker がメモリに読み込み直されても、同じオブジェクトを識別し続けます。
• moniker はバインドと呼ばれる操作をサポートします。これは、moniker が指定するオブジェクトを特定し、まだアクティブでない場合はアクティブ化(メモリに読み込み)し、そのオブジェクトの要求されたインターフェイスへのポインターを返す処理です。

Anti-Moniker の実装

moniker クライアントの場合、通常 anti-moniker を使用する必要はありません。moniker の逆が必要な場合は、IMoniker::Inverse を呼び出してください。たとえば、複合 moniker の最後の要素を削除するために逆が必要な場合は、IMoniker::Enum を使用して moniker の各要素を列挙し、最も右側の要素に対して Inverse を呼び出します。複合 moniker の最も右側の要素が anti-moniker を自身の逆とみなすとは限らないため、この目的で anti-moniker を使用しないでください。

anti-moniker を明示的に使用すべき唯一の状況は、新しい moniker クラスを作成していて、その moniker の逆を構築するための特別な要件がない場合です。その場合は、Inverse の実装から anti-moniker を返すことができます。そして IMoniker::ComposeWith の実装では、遭遇した anti-moniker ごとに自身の moniker の 1 つを打ち消す必要があります。

これらの moniker を作成するには、CreateAntiMoniker 関数を使用します。

Class Moniker の実装

class moniker は、ファイル moniker や item moniker などの他の種類の moniker との合成において最も有用です。class moniker は、IClassActivator インターフェイスへのバインドをサポートする moniker の右側に合成することもできます。これにより、IClassActivator はクラスオブジェクトおよびクラスのインスタンスへのアクセスを提供できます。

class moniker を使用するには、CreateClassMoniker 関数を使用してこれらの moniker を作成する必要があります。

File Moniker の実装

なお、anti-moniker はファイル moniker 全体の逆であり、moniker が表すパスの一部の逆ではありません。つまり、ファイル moniker の右側に anti-moniker を合成すると、ファイル moniker 全体が削除されます。ファイル moniker が表すパスの最も右側の要素だけを削除したい場合は、".." パスに基づく別のファイル moniker を作成し、それをファイル moniker の末尾に合成する必要があります。

moniker クライアント(moniker を使用してオブジェクトへのインターフェイスポインターを取得する側)は、通常、moniker のクラスを知る必要はありません。単に IMoniker インターフェイスポインターを使用してメソッドを呼び出せます。

moniker プロバイダー(自身のオブジェクトを識別する moniker を配布して、moniker クライアントからアクセスできるようにする側)は、識別するオブジェクトがファイルに格納されている場合、ファイル moniker を使用する必要があります。各オブジェクトが独自のファイルに存在する場合、必要なのはファイル moniker のみです。識別するオブジェクトがファイルより小さい場合は、ファイル moniker に加えて別の種類の moniker(たとえば item moniker)を使用する必要があります。

ファイル moniker を使用するには、CreateFileMoniker 関数を使用して moniker を作成する必要があります。ファイル moniker がバインドされたときにオブジェクトを読み込めるようにするには、オブジェクトが IPersistFile インターフェイスを実装している必要があります。

moniker プロバイダーの最も一般的な例は、リンクをサポートする COM サーバーアプリケーションです。COM サーバーアプリケーションがファイルベースのドキュメント全体へのリンクのみをサポートする場合、必要な moniker はファイル moniker のみです。COM サーバーアプリケーションがドキュメントより小さいオブジェクト(ドキュメントの一部や埋め込みオブジェクトなど)へのリンクをサポートする場合は、ファイル moniker に加えて item moniker も使用する必要があります。

Generic Composite Moniker の実装

合成とは、2 つの moniker を結合する処理です。特定のクラスの 2 つの moniker が特別な方法で結合できる場合があります。たとえば、不完全なパスを表すファイル moniker と相対パスを表す別のファイル moniker を結合して、完全なパスを表す単一のファイル moniker を形成できます。これは非汎用合成の例です。一方、汎用合成は、クラスに関係なく任意の 2 つの moniker を接続できます。非汎用合成は関与する moniker のクラスに依存するため、特定のクラスによる IMoniker::ComposeWith メソッドの実装によってのみ実行できます。新しい moniker クラスを作成する場合、新しい種類の非汎用合成を定義できます。これに対して、汎用合成は CreateGenericComposite 関数によって実行されます。

moniker クライアント(moniker を使用してオブジェクトへのインターフェイスポインターを取得する側)は、通常、moniker のクラスや、それが汎用複合か非汎用複合かを知る必要はありません。単に IMoniker インターフェイスポインターを使用してメソッドを呼び出せます。

moniker プロバイダー(自身のオブジェクトを識別する moniker を配布して、moniker クライアントからアクセスできるようにする側)は、2 つの moniker を合成する必要がある場合があります。(たとえば、item moniker を使用してオブジェクトを識別する場合、それを配布する前にオブジェクトのコンテナーを識別する moniker と合成する必要があります。) これを行うには IMoniker::ComposeWith メソッドを使用し、最初の moniker に対してメソッドを呼び出して 2 番目の moniker をパラメーターとして渡します。このメソッドは、汎用複合または非汎用複合のいずれかを生成することがあります。

generic composite moniker を明示的に作成すべき唯一の場面は、独自の moniker クラスを作成しているときです。IMoniker::ComposeWith の実装では、可能な限り非汎用合成を実行するよう試みるべきです。非汎用合成を実行できず、汎用合成が許容される場合は、CreateGenericComposite 関数を呼び出して generic composite moniker を作成できます。

Item Moniker の実装

item moniker にはテキスト文字列が含まれます。この文字列は、コンテナーオブジェクトが含まれる項目を他の項目と区別するために使用されます。コンテナーオブジェクトは IOleItemContainer インターフェイスを実装している必要があります。このインターフェイスにより、item moniker のコードは、オブジェクトを識別する文字列だけをもとにオブジェクトへのポインターを取得できます。

moniker クライアント(moniker を使用してオブジェクトへのインターフェイスポインターを取得する側)は、通常、moniker のクラスを知る必要はありません。単に IMoniker インターフェイスポインターを使用してメソッドを呼び出せます。

moniker プロバイダー(自身のオブジェクトを識別する moniker を配布して、moniker クライアントからアクセスできるようにする側)は、識別するオブジェクトが別のオブジェクト内に含まれ、文字列を使用して個別に識別できる場合、item moniker を使用する必要があります。コンテナーオブジェクトを識別するには、別の種類の moniker(たとえばファイル moniker)を使用します。

item moniker を使用するには、CreateItemMoniker 関数を使用して moniker を作成する必要があります。item moniker がバインドされたときにオブジェクトを読み込めるようにするには、オブジェクトのコンテナーが IOleItemContainer インターフェイスを実装している必要があります。

moniker プロバイダーの最も一般的な例は、リンクをサポートする COM アプリケーションです。COM アプリケーションがファイルベースのドキュメントより小さいオブジェクトへのリンクをサポートする場合、item moniker を使用する必要があります。ドキュメント内の選択範囲へのリンクを許可するサーバーアプリケーションでは、item moniker を使用してそれらのオブジェクトを識別します。埋め込みオブジェクトへのリンクを許可するコンテナーアプリケーションでは、item moniker を使用して埋め込みオブジェクトを識別します。

OBJREF Moniker の実装

OBJREF moniker は多くの点でポインター moniker に似ていますが、実行中のオブジェクトがアウトオブプロセスである点が異なります。クライアントは OBJREF moniker に対して IMoniker::BindToObject を呼び出し、取得したポインターを使用して、場所に関係なく実行中のオブジェクトにアクセスできます。

ポインター moniker との重要な違いは、OBJREF moniker の表示名を HTML ページに埋め込むことができ、moniker が表す実行中のオブジェクトをクライアントスクリプト、アプレット、または ActiveX コントロールからバインドできる点です。

OBJREF moniker の主な用途は、インターネット経由で実行中のオブジェクトインスタンスへのアクセスを取得することです。アクティブサーバーページやその他の動的 HTML コンテンツ生成手段が、OBJREF moniker の表示名をアプレットまたは ActiveX コントロールのパラメーターに配置します。アプレットまたはコントロールのコードは CreateObjrefMoniker 関数を呼び出して表示名に基づく OBJREF moniker を作成し、続いてその OBJREF moniker に対して IMoniker::BindToObject を呼び出して、実行中のオブジェクトインスタンスへのアクセスを取得します。その後、アクティブサーバーページは、実行中のオブジェクトへのポインターをページのクライアントにマーシャリングして返します。

Pointer Moniker の実装

ポインター moniker のインスタンスはシリアル化を拒否します。つまり、IPersistStream::Save はエラーを返します。ただし、これらの moniker は RPC 呼び出しで別のプロセスにマーシャリングできます。内部的には、システムはインターフェイスポインターをマーシャリングする標準的なパラダイムを使用してポインターをマーシャリングおよびアンマーシャリングします。

ポインター moniker が必要になることはまれです。永続的な表現を持たないオブジェクトを識別する moniker が必要な場合にのみ、ポインター moniker を使用します。ポインター moniker により、そのようなオブジェクトが moniker バインド操作に参加できるようになります。

URL Moniker の実装

IAsyncMoniker インターフェイスは単なる IUnknown です。(追加のメソッドはありません。) これは、moniker が非同期バインドをサポートするかどうかをクライアントが判断できるようにするために使用されます。

このオブジェクトの IMoniker インターフェイスへのポインターを取得するには、CreateURLMonikerEx 関数を呼び出します。

moniker クライアント(moniker を使用してオブジェクトへのインターフェイスポインターを取得する側)は、通常、使用している moniker のクラスを知る必要はありません。単に IMoniker インターフェイスポインターを使用してメソッドを呼び出せます。

moniker プロバイダー(自身のオブジェクトを識別する moniker を配布して、moniker クライアントからアクセスできるようにする側)は、識別するオブジェクトが別のオブジェクト内に含まれ、文字列を使用して個別に識別できる場合、item moniker を使用する必要があります。また、コンテナーオブジェクトを識別するために別の種類の moniker(たとえばファイル moniker)も使用する必要があります。

item moniker を使用するには、CreateItemMoniker 関数を使用して moniker を作成する必要があります。item moniker がバインドされたときにオブジェクトを読み込めるようにするには、オブジェクトのコンテナーが IOleItemContainer インターフェイスを実装している必要があります。

moniker プロバイダーの最も一般的な例は、リンクをサポートする COM アプリケーションです。COM アプリケーションがファイルベースのドキュメントより小さいオブジェクトへのリンクをサポートする場合、item moniker を使用する必要があります。ドキュメント内の選択範囲へのリンクを許可するサーバーアプリケーションでは、item moniker を使用してそれらのオブジェクトを識別します。埋め込みオブジェクトへのリンクを許可するコンテナーアプリケーションでは、item moniker を使用して埋め込みオブジェクトを識別します。

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

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

このメソッドは、IOleItemContainer::GetObject メソッドに関連するエラーを返すこともあります。

BindToObject は moniker の主要な機能を実装します。すなわち、moniker が識別するオブジェクトを特定し、そのインターフェイスの 1 つへのポインターを返すことです。

呼び出し元への注意

通常、次の手順で BindToObject を呼び出します。

1. CreateBindCtx 関数を呼び出してバインドコンテキストオブジェクトを作成します。
2. moniker を使用して 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 コンテナーは、moniker を使用してリンク先のオブジェクトを特定してアクセスしますが、通常は BindToObject を直接呼び出しません。代わりに、ユーザーがコンテナー内のリンクをアクティブ化すると、リンクコンテナーは通常、リンクハンドラーの実装を使用して IOleObject::DoVerb を呼び出します。この実装は、(自身で動詞を処理できない場合)リンクされたオブジェクトに格納された moniker に対して BindToObject を呼び出します。

実装者への注意

moniker にプレフィックスがないと想定する場合、BindToObject の実装ではまず実行中オブジェクトテーブル(ROT)を確認して、オブジェクトが既に実行中かどうかを調べるべきです。ROT へのポインターを取得するには、pbc パラメーターに対して IBindCtx::GetRunningObjectTable を呼び出します。次に IRunningObjectTable::GetObject メソッドを呼び出して、現在の moniker が ROT に登録されているかどうかを確認できます。登録されている場合は、直ちに QueryInterface を呼び出して、呼び出し元が要求したインターフェイスへのポインターを取得できます。

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

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

実装固有の注意

URL moniker のバインド操作のセマンティクスは、同期使用か非同期使用かに関係なく同一であり、次のとおりです。

1. URL moniker は、バインド操作のためのさらなる情報をバインドコンテキストから取得します。たとえば、moniker はバインドコンテキストに登録された IBindStatusCallback および IEnumFORMATETC インターフェイスへのポインターを取得できます。さらなる情報には、IBindCtx::SetBindOptions を通じてバインドコンテキストに指定された追加のバインドオプション(dwTickCountDeadline パラメーターや BIND_MAYBOTHERUSER の grfFlags 値など)が含まれる場合があります。
2. 次に moniker は、バインドコンテキストの ROT を確認して、参照先のオブジェクトが既に実行中かどうかを判断します。moniker は次の呼び出しでこの情報を取得できます。

   IBindCtx::GetRunningObjectTable(&prot)
   prot->IsRunning(this)
   

3. オブジェクトが既に実行中の場合、moniker は次の呼び出しで実行中のオブジェクトを取得します。

   prot->GetObject(this, &punk)
   

4. その後、moniker は要求されたインターフェイスに対して QueryInterface を呼び出します。
5. そうでない場合、moniker は IBindStatusCallback::GetBindInfo を呼び出してクライアントに問い合わせ、追加のバインド情報を取得します。次に moniker はバインド操作を開始し、結果として得られる IBinding インターフェイスを IBindStatusCallback::OnStartBinding を呼び出してクライアントに返します。
6. 手順 1 でこれが非同期バインドであると判断された場合、BindToObject はこの時点で ppv に NULL を格納して MK_S_ASYNCHRONOUS を返します。呼び出し元は、後の時点で IBindStatusCallback::OnObjectAvailable メソッド中に実際のオブジェクトポインターを受け取ります。以降の手順は、通常は別の実行スレッド上で、呼び出し元に対して非同期に実行されます。
7. URL Moniker が指定するリソースのクラスは、次のいずれかの方法で決定されます。
   • URL moniker はデータのメディアタイプを調べます。メディアタイプが application/x-oleobject の場合、実際のデータ(Content-Body)の先頭 16 バイトにはリソースの CLSID が含まれ、後続のデータはクラス自身によって解釈されます。それ以外のすべてのメディアタイプについては、URL Moniker はシステムレジストリの HKEY_CLASSES_ROOT\MIME\Database\Content-Type\<media-type>\CLSID キーを調べます。なお、application/oleobject が承認されるまでは application/x-oleobject が使用されます。
   • URL moniker は、到着したデータの一部を、システムレジストリの HKEY_CLASSES_ROOT\FileTypes に登録されたパターンと照合します。
   • 最後に、他のすべてが失敗した場合、URL Moniker は、GetClassFile やシェルが行うのと同様に、システムレジストリの HKEY_CLASSES_ROOT\.??? キーを使用して、リソースの末尾の拡張子(存在する場合)を CLSID に対応付けます。
8. クラスを決定した後、URL moniker は IUnknown インターフェイスを要求して CLSCTX_SERVER の CoCreateInstance を使用してインスタンスを作成します。
9. 次に URL moniker は、新しく作成したオブジェクトの QueryInterface メソッドを呼び出して IPersistMoniker インターフェイスを取得しようとします。QueryInterface が成功した場合、URL moniker は自身(this)を moniker パラメーターとして渡して IPersistMoniker::Load を呼び出します。オブジェクトは通常、関心のあるストレージインターフェイスを求めて BindToStorage を呼び出します。
10. そうでない場合、URL moniker は IPersistStream に対して QueryInterface を呼び出し、成功した場合は IPersistStream::Load を呼び出して、トランスポートによって非同期に満たされるストリームオブジェクトの IStream ポインターをオブジェクトに渡します。

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

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

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

指定されたオブジェクトのストレージにバインドします。IMoniker::BindToObject メソッドとは異なり、このメソッドは moniker が識別するオブジェクトをアクティブ化しません。

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、次の値を返すことがあります。

このメソッドは、IOleItemContainer::GetObject メソッドに関連するエラーを返すこともあります。

BindToObject メソッドと BindToStorage メソッドには重要な違いがあります。たとえば、スプレッドシートオブジェクトを識別する moniker がある場合、BindToObject を呼び出すとスプレッドシートオブジェクト自体へのアクセスが提供されるのに対し、BindToStorage を呼び出すとスプレッドシートが存在するストレージオブジェクトへのアクセスが提供されます。

呼び出し元への注意

moniker が識別するオブジェクトのストレージを読み取れるクライアントも、このメソッドを呼び出すことができます。

実装者への注意

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

実装固有の注意

moniker を最も単純な形式に簡約します。

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

このメソッドは、次の用途を想定しています。

• ユーザー定義のマクロやエイリアスを、新しい種類の moniker クラスとして構築できるようにします。簡約されると、マクロが評価される先の moniker が返されます。
• データが移動するのを追跡する種類の moniker を構築できるようにします。簡約されると、現在の場所にあるデータの moniker が返されます。
• ファイル名に依存しない識別子ベースのファイルアクセス方法をサポートするファイルシステムでは、ファイル moniker をこれらの識別子の 1 つを含む moniker に簡約できます。

呼び出し元への注意

2 つの moniker を IMoniker::IsEqual メソッドで比較する前に Reduce を呼び出すべきです。簡約された moniker は最も具体的な形式になっているためです。IsEqual は、簡約前の 2 つの moniker に対して S_FALSE を返し、簡約後には S_OK を返すことがあります。

実装者への注意

実装固有の注意

現在の moniker を指定された moniker と結合して、新しい複合 moniker を作成します。

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

2 つの moniker を結合することを合成と呼びます。同じクラスの 2 つの moniker が、非汎用合成と呼ばれる方法で結合できる場合があります。たとえば、不完全なパスを表すファイル moniker と相対パスを表す別のファイル moniker を結合して、完全なパスを表す単一のファイル moniker を形成できます。特定の moniker クラスの非汎用合成は、その moniker クラスの ComposeWith の実装でのみ処理できます。

任意のクラスの 2 つの moniker を結合することを汎用合成と呼びます。これは CreateGenericComposite 関数を呼び出すことで実現できます。

moniker の合成は結合的な操作です。つまり、A、B、C が moniker であるとき、Comp() が合成操作を表すとすると、Comp( Comp( A, B ), C ) は常に Comp( A, Comp( B, C ) ) と等しくなります。

呼び出し元への注意

自身のオブジェクトを識別するために item moniker を提供するオブジェクトは、オブジェクトの場所を完全に識別する moniker を提供するために ComposeWith を呼び出します。これは、たとえばドキュメントの一部へのリンクをサポートするサーバーや、ドキュメント内の埋め込みオブジェクトへのリンクをサポートするコンテナーに当てはまります。そのような場合は、次のようにします。

1. オブジェクトを識別する item moniker を作成します。
2. オブジェクトのコンテナーを識別する moniker を取得します。
3. コンテナーを識別する moniker に対して ComposeWith を呼び出し、item moniker を pmkRight パラメーターとして渡します。

実装者への注意

新しい moniker クラスを作成する場合、自身のクラスまたは別のクラスのいずれであっても、特別な扱いをしたい moniker の種類があるかどうかを判断する必要があります。ある場合は、pmkRight がその扱いを受けるべき種類の moniker であるかどうかをチェックするように ComposeWith を実装します。これを行うには、moniker の IPersist::GetClassID メソッドを呼び出すか、カスタムインターフェイスをサポートする moniker オブジェクトを定義している場合は、そのインターフェイスに対して moniker の QueryInterface を呼び出します。特別な扱いの例としては、絶対ファイル moniker と相対ファイル moniker の非汎用合成があります。特別な moniker の最も一般的なケースは、自身の moniker クラスの逆(IMoniker::Inverse の実装から返すもの)です。

pmkRight が受け手を完全に打ち消し、結果の複合が空になる場合は、ppmkComposite に NULL を返し、状態コード S_OK を返すべきです。

pmkRight パラメーターが特別な扱いをするクラスでない場合は、fOnlyIfNotGeneric を調べて次にどうするかを判断します。fOnlyIfNotGeneric が TRUE の場合は、ppmkComposite に NULL を返し、状態コード MK_E_NEEDGENERIC を返します。fOnlyIfNotGeneric が FALSE の場合は、CreateGenericComposite 関数を呼び出して汎用的に合成を実行します。

実装固有の注意

複合 moniker の構成要素の列挙子へのポインターを取得します。

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

このメソッドは、moniker の構成要素を列挙できる列挙子への IEnumMoniker ポインターを提供する必要があります。たとえば、generic composite moniker の IMoniker::Enum メソッドの実装は、複合を構成する個々の moniker を判別できる列挙子を作成します。一方、ファイル moniker の IMoniker::Enum メソッドは、パス内の各構成要素を表す moniker を返す列挙子を作成します。

呼び出し元への注意

実装者への注意

実装固有の注意

この moniker が指定された moniker と同一かどうかを判定します。

このメソッドは、2 つの moniker が同一であることを示す場合は S_OK を返し、そうでない場合は S_FALSE を返します。

以前の実行中オブジェクトテーブル(ROT)の実装は、このメソッドを呼び出していました。現在の ROT の実装では、代わりに IROTData インターフェイスを使用します。

呼び出し元への注意

実装者への注意

等しいと比較される 2 つの moniker は、IMoniker::Hash を使用したときに同じ値にハッシュされる必要があります。

実装固有の注意

moniker の内部状態を使用してハッシュ値を作成します。

このメソッドは、ハッシュ値が正常に取得されたことを示す S_OK を返します。

呼び出し元への注意

実装者への注意

moniker をマーシャリングしてからアンマーシャリングしても、そのハッシュ値に影響を与えてはなりません。したがって、IMoniker::Hash の実装は、moniker のメモリアドレスではなく、moniker の内部状態のみに依存すべきです。

実装固有の注意

この moniker が識別するオブジェクトが現在読み込まれて実行中かどうかを判定します。

このメソッドは、標準の戻り値 E_UNEXPECTED のほか、次の値を返すことがあります。

呼び出し元への注意

リンクされたオブジェクト内に格納された moniker については、IsRunning は主に既定のハンドラーによる IOleLink::BindIfRunning の実装から呼び出されます。

実装者への注意

実装固有の注意

この moniker が識別するオブジェクトが最後に変更された時刻を取得します。

このメソッドは、標準の戻り値 E_OUTOFMEMORY のほか、次の値を返すことがあります。

正確には、返される時刻は、それ以降に変更が発生していないと COM が識別できる最も早い時刻です。したがって、この時刻はオブジェクトへの最終変更時刻より後になる場合があります。

呼び出し元への注意

リンクされたオブジェクト内に格納された moniker については、GetTimeOfLastChange は主に既定のハンドラーによる IOleObject::IsUpToDate の実装から呼び出されます。コンテナーアプリケーションは IOleObject::IsUpToDate を呼び出して、リンクされたオブジェクト(またはリンクされたオブジェクトを含む埋め込みオブジェクト)が、実際にオブジェクトにバインドすることなく最新かどうかを判定します。これにより、アプリケーションはエンドユーザーがドキュメントを開いたときに、どのリンクされたオブジェクトを更新する必要があるかを素早く判断できます。その後、アプリケーションは、ドキュメント内のすべてのリンクされたオブジェクトをバインドする代わりに、(更新すべきかどうかをエンドユーザーに確認した後で)更新が必要なリンクされたオブジェクトだけをバインドできます。

実装者への注意

実装で使用できる方針をいくつか示します。

• 多くの種類の moniker では、pmkToLeft パラメーターがこの moniker が識別するオブジェクトのコンテナーを識別します。moniker クラスでこれが当てはまる場合、オブジェクトはコンテナーより後の日付で変更されることはないため、単に pmkToLeft パラメーターに対して GetTimeOfLastChange を呼び出すことができます。
• pbc パラメーターに対して IBindCtx::GetRunningObjectTable を呼び出して実行中オブジェクトテーブル(ROT)へのポインターを取得し、次に IRunningObjectTable::GetTimeOfLastChange を呼び出すことができます。ROT は通常、最終変更時刻を記録しているためです。
• この moniker(または pmkToLeft moniker)に関連付けられたストレージを取得し、IStorage::Stat を呼び出してストレージの最終変更時刻を返すことができます。

実装固有の注意

この moniker の逆となる moniker を作成します。この moniker または類似の構造を持つ moniker の右側に合成されると、その moniker は何も残らないように合成されます。

このメソッドは、標準の戻り値 E_OUTOFMEMORY のほか、次の値を返すことがあります。

moniker の逆は、MS-DOS ファイルシステムにおける ".." ディレクトリに似ています。".." ディレクトリは、他の任意のディレクトリ名に対する逆として機能します。ディレクトリ名に ".." を追加すると空のパスになるためです。同様に、moniker の逆は通常、同じクラスのすべての moniker の逆でもあります。ただし、必ずしも別のクラスの moniker の逆であるとは限りません。

複合 moniker の逆は、元の moniker の構成要素の逆を逆順に並べた複合です。たとえば、A の逆を Inv( A )、A、B、C の複合を Comp( A, B, C ) とすると、Inv( Comp( A, B, C ) ) は Comp( Inv( C ), Inv( B ), Inv( A ) ) と等しくなります。

すべての moniker が逆を持つわけではありません。anti-moniker のように、それ自体が逆である moniker のほとんどは逆を持ちません。逆を持たない moniker では、それが識別するオブジェクトの内部から、外部の他のオブジェクトへの相対 moniker を形成することはできません。

呼び出し元への注意

Inverse メソッドは、相対 moniker の構築を支援するために、IMoniker::RelativePathTo メソッドの実装からも呼び出されます。

実装者への注意

実装固有の注意

この moniker が指定された moniker と共通に持つプレフィックスに基づいて、新しい moniker を作成します。

このメソッドは、標準の戻り値 E_OUTOFMEMORY のほか、次の値を返すことがあります。

CommonPrefixWith は、この moniker オブジェクトの moniker と別の moniker の共通プレフィックスからなる新しい moniker を作成します。たとえば、一方の moniker がパス "c:\projects\secret\art\pict1.bmp" を表し、もう一方の moniker がパス "c:\projects\secret\docs\chap1.txt" を表す場合、これら 2 つの moniker の共通プレフィックスは、パス "c:\projects\secret" を表す moniker になります。

呼び出し元への注意

このメソッドは、pmkOther とこの moniker の両方が絶対 moniker である場合にのみ呼び出してください。絶対 moniker とは、ファイル moniker、または最も左側の構成要素が絶対パスを表すファイル moniker である generic composite のいずれかです。相対 moniker に対してこのメソッドを呼び出さないでください。意味のある結果が得られないためです。

実装者への注意

実装固有の注意

この moniker と指定された moniker の間の相対 moniker を作成します。

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

相対 moniker は、相対パス(たとえば "..\backup")に似ています。たとえば、パス "c:\projects\secret\art\pict1.bmp" を表す moniker と、パス "c:\projects\secret\docs\chap1.txt" を表す別の moniker があるとします。最初の moniker に対して RelativePathTo を呼び出し、2 番目の moniker を pmkOther パラメーターとして渡すと、パス "..\docs\chap1.txt" を表す相対 moniker が作成されます。

呼び出し元への注意

RelativePathTo を呼び出す場合は、絶対 moniker(たとえば、ファイル moniker、または最も左側の構成要素がファイル moniker であり、そのファイル moniker が絶対パスを表す複合 moniker)に対してのみ呼び出してください。相対 moniker に対してこのメソッドを呼び出さないでください。

実装者への注意

相対パスを判定する最初のステップは、この moniker と pmkOther の共通プレフィックスを判定することです。次のステップは、この moniker と pmkOther をそれぞれ 2 つの部分、すなわち (P, myTail) と (P, otherTail) に分割することです。ここで P は共通プレフィックスです。正しい相対パスは、myTail の逆と otherTail を合成したものです。

Comp( Inv( myTail ), otherTail )

ここで Comp() は合成操作を、Inv() は逆操作を表します。

特定の種類の moniker では、myTail の逆を構築するために IMoniker::Inverse メソッドを使用できません。たとえば、ファイル moniker は逆として anti-moniker を返しますが、その RelativePathTo メソッドは、myTail の逆を構築するために、それぞれパス ".." を表す 1 つ以上のファイル moniker を使用する必要があります。

実装固有の注意

moniker の表示名を取得します。

このメソッドは、標準の戻り値 E_OUTOFMEMORY のほか、次の値を返すことがあります。

GetDisplayName は、moniker の表示可能な表現である文字列を提供します。表示名は moniker の内部状態の完全な表現ではなく、単にユーザーが読める形式です。そのため、まれに 2 つの異なる moniker が同じ表示名を持つことがあります。moniker の表示名を MkParseDisplayName 関数に渡してその moniker に解析し直せる保証はありませんが、解析できないことはまれです。

呼び出し元への注意

実装者への注意

generic composite moniker の一部となることを意図した moniker は、先行する区切り文字(たとえば '')を表示名の一部として含めるべきです。たとえば、item moniker が返す表示名には、CreateItemMoniker 関数で作成されたときに指定された区切り文字が含まれます。ファイル moniker の表示名には区切り文字は含まれません。ファイル moniker は常に複合の最も左側の構成要素であることが期待されるためです。

実装固有の注意

表示名を moniker に変換します。

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

このメソッドは、IMoniker::BindToObject メソッドに関連するエラーを返すこともあります。

呼び出し元への注意

次に、作成したばかりの moniker に対して ParseDisplayName を呼び出し、表示名の残りを渡して、新しい moniker を返してもらいます。このステップは、表示名全体が解析されるまで繰り返されます。

実装者への注意

IParseDisplayName ポインターを取得するには、次のようにいくつかの方針があります。

• オブジェクトの CLSID を(オブジェクトに対して IPersist::GetClassID を呼び出して)取得し、その CLSID に関連付けられたクラスファクトリの IParseDisplayName インターフェイスを要求して CoGetClassObject 関数を呼び出すことができます。
• オブジェクト自体にバインドして IParseDisplayName ポインターを取得することができます。
• pmkToLeft が識別するオブジェクトにバインドして IOleItemContainer ポインターを取得し、IOleItemContainer::GetObject を呼び出して項目の IParseDisplayName ポインターを取得することができます。

実装固有の注意

  hr = BindToObject(pbc, pmkToLeft, IID_IParseDisplayName, (void**)&ppdn);
  if (SUCCEEDED(hr)) {
    hr = ppdn->ParseDisplayName(pbc, lpszDisplayName, pchEaten, ppmkOut);
    ppdn->Release();
  }
  return hr;

この moniker がシステム提供の moniker クラスの 1 つであるかどうかを判定します。

このメソッドは、moniker がシステム moniker であることを示す場合は S_OK を返し、そうでない場合は S_FALSE を返します。

呼び出し元への注意

実装者への注意

実装固有の注意