IMoniker::ComposeWith-Methode (objidl.h)

  • Artikel

Erstellt einen neuen zusammengesetzten Moniker, indem der aktuelle Moniker mit dem angegebenen Moniker kombiniert wird.

Syntax

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

Parameter

[in] pmkRight

Ein Zeiger auf die IMoniker-Schnittstelle auf dem Moniker, um am Ende dieses Monikers zu komponieren.

[in] fOnlyIfNotGeneric

Wenn TRUE, erfordert der Aufrufer eine nichtgenerische Zusammensetzung. Daher sollte der Vorgang nur fortgesetzt werden, wenn pmkRight eine Monikerklasse ist, mit der dieser Moniker in einer anderen Weise als einen generischen Verbund zusammenstellen kann. Bei FALSE kann die Methode bei Bedarf einen generischen Zusammengesetzten erstellen. Die meisten Aufrufer sollten diesen Parameter auf FALSE festlegen.

[out] ppmkComposite

Ein Zeiger auf eine IMoniker-Zeigervariable , die den zusammengesetzten Monikerzeiger empfängt. Bei erfolgreicher Implementierung muss AddRef für den resultierenden Moniker aufgerufen werden. Es liegt in der Verantwortung des Aufrufers , Release aufzurufen. Wenn ein Fehler auftritt oder die Moniker zu nichts verfassen (z. B. beim Komponieren eines Antimonikers mit einem Elementmoniker oder einem Dateimoniker), sollte *ppmkComposite auf NULL festgelegt werden.

Rückgabewert

Diese Methode kann die Standardrückgabewerte E_OUTOFMEMORY und E_UNEXPECTED sowie die folgenden Werte zurückgeben.

Rückgabecode BESCHREIBUNG
S_OK
 Die Moniker wurden erfolgreich kombiniert.
MK_E_NEEDGENERIC
 Gibt an, dass fOnlyIfNotGenericTRUE war, aber die Moniker nicht zusammen zusammengesetzt werden konnten, ohne einen generischen zusammengesetzten Moniker zu erstellen.

Hinweise

Das Verbinden von zwei Monikern wird als Komposition bezeichnet. Manchmal können zwei Moniker derselben Klasse in einer sogenannten nichtgenerischen Zusammensetzung kombiniert werden. Beispielsweise kann ein Dateimoniker, der einen unvollständigen Pfad darstellt, und ein anderer Dateimoniker, der einen relativen Pfad darstellt, kombiniert werden, um einen einzelnen Dateimoniker zu bilden, der den vollständigen Pfad darstellt. Nichtgenerische Komposition für eine bestimmte Monikerklasse kann nur in der Implementierung von ComposeWith für diese Monikerklasse behandelt werden.

Das Kombinieren von zwei Monikern einer beliebigen Klasse wird als generische Komposition bezeichnet, was durch einen Aufruf der CreateGenericComposite-Funktion erreicht werden kann.

Die Zusammensetzung von Monikern ist ein assoziativer Vorgang. Das heißt, wenn A, B und C Moniker sind, dann, wobei Comp() den Kompositionsvorgang darstellt, Comp( Comp( A, B ), C )

ist immer gleich Comp( A, Comp( B, C ).

Hinweise für Anrufer

Um zwei Moniker zu kombinieren, sollten Sie ComposeWith aufrufen, anstatt die CreateGenericComposite-Funktion aufzurufen, um dem ersten Moniker die Möglichkeit zu geben, eine nichtgenerische Komposition auszuführen.

Ein Objekt, das Elementmoniker zur Identifizierung seiner Objekte bereitstellt, ruft ComposeWith auf, um einen Moniker bereitzustellen, der die Position des Objekts vollständig identifiziert. Dies gilt beispielsweise für einen Server, der die Verknüpfung mit Teilen eines Dokuments unterstützt, oder für einen Container, der das Verknüpfen mit eingebetteten Objekten in seinen Dokumenten unterstützt. In einer solchen Situation würden Sie folgendes tun:

  1. Erstellen Sie einen Elementmoniker, der das Objekt identifiziert.
  2. Rufen Sie einen Moniker ab, der den Container des Objekts identifiziert.
  3. Rufen Sie ComposeWith auf dem Moniker auf, der den Container identifiziert, und übergeben Sie den Elementmoniker als pmkRight-Parameter .

Hinweise zu Implementierern

Sie können entweder eine nichtgenerische oder generische Komposition verwenden, um den aktuellen Moniker mit dem Moniker zu komponieren, auf den pmkRight verweist. Wenn die klasse des von pmkRight angegebenen Monikers mit der des aktuellen Monikers identisch ist, ist es möglich, den Inhalt von pmkRight zu verwenden, um eine intelligentere nichtgenerische Zusammensetzung durchzuführen.

Wenn Sie eine neue Moniker-Klasse schreiben, müssen Sie entscheiden, ob es irgendwelche Arten von Monikern gibt, unabhängig davon, ob Es sich um Ihre eigene Klasse oder eine andere Klasse handelt, die Sie speziell behandeln möchten. Wenn ja, implementieren Sie ComposeWith , um zu überprüfen, ob pmkRight ein Moniker des Typs ist, für den diese Behandlung erforderlich ist. Dazu können Sie die IPersist::GetClassID-Methode des Monikers aufrufen, oder wenn Sie ein Moniker-Objekt definiert haben, das eine benutzerdefinierte Schnittstelle unterstützt, können Sie QueryInterface auf dem Moniker für diese Schnittstelle aufrufen. Ein Beispiel für eine Sonderbehandlung wäre die nichtgenerische Zusammensetzung eines absoluten Dateimonikers mit einem relativen Dateimoniker. Der häufigste Fall eines speziellen Monikers ist die Inverse für Ihre Moniker-Klasse (was auch immer Sie von Ihrer Implementierung von IMoniker::Inverse zurückgeben).

Wenn pmkRight den Empfänger vollständig negiert, sodass der resultierende Verbund leer ist, sollten Sie NULL in ppmkComposite zurückgeben und den status Code S_OK zurückgeben.

Wenn der pmkRight-Parameter nicht von einer Klasse ist, der Sie eine spezielle Behandlung gewähren, untersuchen Sie fOnlyIfNotGeneric , um zu bestimmen, was als Nächstes zu tun ist. Wenn fOnlyIfNotGenericTRUE ist, übergeben Sie NULL über ppmkComposite, und geben Sie den status Code MK_E_NEEDGENERIC zurück. Wenn fOnlyIfNotGenericfalse ist, rufen Sie die CreateGenericComposite-Funktion auf, um die Komposition generisch auszuführen.

Implementierungsspezifische Hinweise

Implementierung Hinweise
Antimoniker Wenn fOnlyIfNotGenerictrue ist, legt diese Methode ppmkComposite auf NULL-Moniker fest und gibt MK_E_NEEDGENERIC zurück. Andernfalls gibt die Methode das Ergebnis der Kombination der beiden Moniker zu einem generischen Verbund zurück. Beachten Sie, dass das Komponieren eines Datei-, Element- oder Zeigermonikers rechts von einem Antimoniker einen generischen Verbund erzeugt, anstatt zu nichts zu komponieren, wie es der Fall wäre, wenn die Reihenfolge der Komposition umgekehrt würde.
Klassenmoniker Folgt dem Vertrag und verhält sich wie ein Elementmoniker, da er E_INVALIDARG und MK_E_NEEDGENERIC usw. zurückgeben kann.
Dateimoniker Wenn pmkRight ein Antimoniker ist, ist der zurückgegebene Moniker NULL. Wenn pmkRight ein Zusammengesetzter ist, dessen linke Komponente ein Antimoniker ist, ist der zurückgegebene Moniker der Zusammengesetzte, wobei der linksste Antimoniker entfernt wurde. Wenn pmkRight ein Dateimoniker ist, reduziert diese Methode die beiden Moniker nach Möglichkeit in einen einzelnen Dateimoniker. Wenn dies nicht möglich ist (z. B. wenn beide Dateimoniker absolute Pfade darstellen, wie in d:\work und e:\reports), ist der zurückgegebene Moniker NULL , und der Rückgabewert ist MK_E_SYNTAX. Wenn pmkRight weder ein Antimoniker noch ein Dateimoniker ist, überprüft die Methode den Parameter fOnlyIfNotGeneric . wenn es FALSE ist, kombiniert die Methode die beiden Moniker zu einem generischen Zusammengesetzten; wenn sie TRUE ist, legt die Methode *ppmkComposite auf NULL fest und gibt MK_E_NEEDGENERIC zurück.
Generischer zusammengesetzter Moniker Wenn fOnlyIfNotGenericTRUE ist, legt diese Methode *pmkComposite auf NULL fest und gibt MK_E_NEEDGENERIC zurück. Andernfalls gibt die Methode das Ergebnis der Kombination der beiden Moniker zurück, indem die CreateGenericComposite-Funktion aufgerufen wird.
Elementmoniker Wenn pmkRight ein Antimoniker ist, ist der zurückgegebene Moniker NULL. Wenn pmkRight ein Zusammengesetzter ist, dessen linke Komponente ein Antimoniker ist, ist der zurückgegebene Moniker der Zusammengesetzte, nachdem der linksste Antimoniker entfernt wurde. Wenn pmkRight kein Antimoniker ist, kombiniert die Methode die beiden Moniker zu einem generischen Verbund, wenn fOnlyIfNotGenericfalse ist; wenn fOnlyIfNotGenericTRUE ist, gibt die Methode einen NULL-Moniker und einen Rückgabewert von MK_E_NEEDGENERIC zurück.
OBJREF-Moniker Wenn pmkRight ein Antimoniker ist, ist der zurückgegebene Moniker NULL. Wenn pmkRight ein Zusammengesetzter ist, dessen linke Komponente ein Antimoniker ist, ist der zurückgegebene Moniker der Zusammengesetzte, wobei der linksste Antimoniker entfernt wurde. Wenn pmkRight weder ein Antimoniker noch ein zusammengesetzter Moniker ist, dessen linke Komponente ein Antimoniker ist, überprüft die Methode den Parameter fOnlyIfNotGeneric . Wenn es FALSE ist, kombiniert die Methode die beiden Moniker zu einem generischen Zusammengesetzten. wenn sie TRUE ist, legt die Methode *ppmkComposite auf NULL fest und gibt MK_E_NEEDGENERIC zurück.
Zeigermoniker Wenn pmkRight ein Antimoniker ist, ist der zurückgegebene Moniker NULL. Wenn pmkRight ein Zusammengesetzter ist, dessen linke Komponente ein Antimoniker ist, ist der zurückgegebene Moniker der Zusammengesetzte, nachdem der linksste Antimoniker entfernt wurde. Wenn fOnlyIfNotGenericfalse ist, ist der zurückgegebene Moniker eine generische Kombination aus den beiden Monikern. Andernfalls legt die Methode *ppmkComposite auf NULL fest und gibt MK_E_NEEDGENERIC zurück.
URL-Moniker URL-Moniker unterstützen die Komposition von zwei URLs: eine Basis-URL, die mit einer relativen URL zusammengesetzt ist. Diese Zusammensetzung erfolgt gemäß dem RFC für relative URLs. Wenn fOnlyIfNotGenerictrue ist, gibt die Methode MK_E_NEEDGENERIC zurück. Andernfalls gibt diese Methode einfach CreateGenericComposite(this, pmkRight, ppmkComposite) zurück.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile objidl.h

Weitere Informationen

CreateGenericComposite

Imoniker