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

[アーティクル]
03/05/2024

現在のモニカーと指定したモニカーを組み合わせて、新しい複合モニカーを作成します。

構文

HRESULT ComposeWith(
  [in]  IMoniker *pmkRight,
  [in]  BOOL     fOnlyIfNotGeneric,
  [out] IMoniker **ppmkComposite
);

パラメーター

[in] pmkRight

このモニカーの末尾に作成するモニカーの IMoniker インターフェイスへのポインター。

[in] fOnlyIfNotGeneric

TRUE の場合、呼び出し元は非一般的なコンポジションを必要とするため、pmkRight がこのモニカーが汎用複合を形成する以外の何らかの方法で構成できるモニカークラスである場合にのみ、操作を続行する必要があります。 FALSE の場合、メソッドは必要に応じてジェネリック複合を作成できます。ほとんどの呼び出し元は、このパラメーターを FALSE に設定する必要があります。

[out] ppmkComposite

複合モニカーポインターを受け取る IMoniker ポインター変数へのポインター。成功した場合、実装では、結果のモニカーで AddRef を呼び出す必要があります。 Release を呼び出すのは呼び出し元の責任です。エラーが発生した場合、またはモニカーが何も作成しない場合 (たとえば、アイテムモニカーまたはファイルモニカーを使用してアンチモニカーを作成する場合)、*ppmkComposite を NULL に設定する必要があります。

戻り値

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

リターンコード	説明
S_OK	モニカーは正常に組み合わされました。
MK_E_NEEDGENERIC	fOnlyIfNotGeneric が TRUE であったが、汎用複合モニカーを作成しないとモニカーを一緒に構成できなかったことを示します。

注釈

2つのモニカーを一緒に結合することは コンポジションと呼ばれます。場合によっては、同じクラスの 2 つのモニカーを非ジェネリックコンポジションと呼ばれるものに組み合わせることができます。たとえば、不完全なパスを表すファイルモニカーと、相対パスを表す別のファイルモニカーを組み合わせて、完全なパスを表す単一のファイルモニカーを形成できます。特定のモニカークラスの非ジェネリックコンポジションは、そのモニカークラスの ComposeWith の実装でのみ処理できます。

任意のクラスの 2 つのモニカーを組み合わせることは 汎用コンポジションと呼ばれ、 CreateGenericComposite 関数の呼び出しを通じて実現できます。

モニカーの構成は連想演算です。つまり、A、B、C がモニカーの場合、Comp() はコンポジション演算を表します。Comp( A, B ), C )

は常に Comp( A, Comp( B, C ) と等しくなります。

呼び出し元へのメモ

2 つのモニカーを組み合わせるには、CreateGenericComposite 関数を呼び出す代わりに ComposeWith を呼び出して、最初のモニカーに非一般的なコンポジションを実行する機会を与える必要があります。

オブジェクトを識別するアイテムモニカーを提供するオブジェクトは ComposeWith を呼び出して、オブジェクトの場所を完全に識別するモニカーを提供します。これは、たとえば、ドキュメントの一部へのリンクをサポートするサーバーや、ドキュメント内の埋め込みオブジェクトへのリンクをサポートするコンテナーに適用されます。このような状況では、次の操作を行います。

オブジェクトを識別する項目モニカーを作成します。
オブジェクトのコンテナーを識別するモニカーを取得します。
コンテナーを識別するモニカーで ComposeWith を呼び出し、 pmkRight パラメーターとして項目モニカーを渡します。

実装者へのメモ

pmkRight が指すモニカーを使用して現在のモニカーを作成するには、非ジェネリックコンポジションまたはジェネリックコンポジションを使用できます。 pmkRight で示されるモニカーのクラスが現在のモニカーのクラスと同じである場合は、pmkRight の内容を使用して、よりインテリジェントな非ジェネリックコンポジションを実行できます。

新しいモニカークラスを作成する際には、独自のクラスか別のクラスかに関係なく、特別な処理を行うモニカーの種類があるかどうかを決定する必要があります。その場合は、ComposeWith を実装して、pmkRight がこの処理を行う必要がある型のモニカーであるかどうかをチェックします。これを行うには、モニカーの IPersist::GetClassID メソッドを呼び出すか、カスタムインターフェイスをサポートするモニカーオブジェクトを定義している場合は、そのインターフェイスのモニカーで QueryInterface を呼び出すことができます。特別な処理の例としては、相対ファイルモニカーを使用した絶対ファイルモニカーの非一般的な構成があります。特殊モニカーの最も一般的なケースは、モニカークラスの逆関数 ( IMoniker::Inverse の実装から返されるもの) です。

pmkRight がレシーバーを完全に否定して、結果の複合が空の場合は、ppmkComposite で NULL を返し、状態コードS_OK返す必要があります。

pmkRight パラメーターが特別な処理を行うクラスではない場合は、fOnlyIfNotGeneric を調べて、次に何を行うかを判断します。 fOnlyIfNotGeneric が TRUE の場合は、ppmkComposite を介して NULL を渡し、状態コードMK_E_NEEDGENERICを返します。 fOnlyIfNotGeneric が FALSE の場合は、CreateGenericComposite 関数を呼び出して、コンポジションを汎用的に実行します。

実装固有の注意事項

実装	メモ
アンチモニカー	fOnlyIfNotGeneric が TRUE の場合、このメソッドは ppmkComposite を NULL モニカーに設定し、MK_E_NEEDGENERICを返します。それ以外の場合、メソッドは 2 つのモニカーをジェネリック複合に結合した結果を返します。反モニカーの右側にファイル、項目、またはポインターモニカーを作成すると、コンポジションの順序が逆の場合と同様に、何も作成せずに汎用複合が生成されることに注意してください。
クラスモニカー	コントラクトに従い、E_INVALIDARGやMK_E_NEEDGENERICなどを返すことができるという点で、アイテムモニカーのように動作します。
ファイルモニカー	pmkRight がアンチモニカーの場合、返されるモニカーは NULL です。 pmkRight が、左端のコンポーネントがアンチモニカーである複合の場合、返されるモニカーは、左端のアンチモニカーが削除された複合です。 pmkRight がファイルモニカーの場合、このメソッドは可能であれば、2 つのモニカーを 1 つのファイルモニカーに折りたたみます。可能でない場合 (たとえば、d:\work や e:\reports のように、両方のファイルモニカーが絶対パスを表している場合)、返されるモニカーは NULL で、戻り値はMK_E_SYNTAX。 pmkRight がアンチモニカーでもファイルモニカーでもない場合、メソッドは fOnlyIfNotGeneric パラメーターをチェックします。FALSE の場合、メソッドは 2 つのモニカーをジェネリック複合に結合します。TRUE の場合、メソッドは *ppmkComposite を NULL に設定し、MK_E_NEEDGENERICを返します。
汎用複合モニカー	fOnlyIfNotGeneric が TRUE の場合、このメソッドは *pmkComposite を NULL に設定し、MK_E_NEEDGENERICを返します。それ以外の場合、メソッドは CreateGenericComposite 関数を呼び出して 2 つのモニカーを組み合わせた結果を返します。
アイテムモニカー	pmkRight がアンチモニカーの場合、返されるモニカーは NULL です。 pmkRight が、左端のコンポーネントがアンチモニカーである複合の場合、返されるモニカーは、左端のアンチモニカーが削除された後の複合です。 pmkRight がアンチモニカーでない場合、fOnlyIfNotGeneric が FALSE の場合、メソッドは 2 つのモニカーをジェネリック複合に結合します。fOnlyIfNotGeneric が TRUE の場合、メソッドは NULL モニカーとMK_E_NEEDGENERICの戻り値を返します。
OBJREF モニカー	pmkRight がアンチモニカーの場合、返されるモニカーは NULL です。 pmkRight が、左端のコンポーネントがアンチモニカーである複合の場合、返されるモニカーは、左端のアンチモニカーが削除された複合です。 pmkRight がアンチモニカーでも複合モニカーでもなく、左端のコンポーネントがアンチモニカーである場合、メソッドは fOnlyIfNotGeneric パラメーターをチェックします。 FALSE の場合、メソッドは 2 つのモニカーをジェネリック複合に結合します。TRUE の場合、メソッドは *ppmkComposite を NULL に設定し、MK_E_NEEDGENERICを返します。
ポインターモニカー	pmkRight がアンチモニカーの場合、返されるモニカーは NULL です。 pmkRight が、左端のコンポーネントがアンチモニカーである複合の場合、返されるモニカーは、左端のアンチモニカーが削除された後の複合です。 fOnlyIfNotGeneric が FALSE の場合、返されるモニカーは 2 つのモニカーのジェネリック複合です。それ以外の場合、メソッドは *ppmkComposite を NULL に設定し、MK_E_NEEDGENERICを返します。
URL モニカー	URL モニカーは、相対 URL で構成されたベース URL という 2 つの URL の構成をサポートします。この構成は、相対 URL の RFC に従って行われます。 fOnlyIfNotGeneric が TRUE の場合、メソッドはMK_E_NEEDGENERICを返します。それ以外の場合、このメソッドは単に CreateGenericComposite (this, pmkRight, ppmkComposite) を返します。

要件

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

こちらもご覧ください

CreateGenericComposite

Imoniker