Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method composes with another moniker.

Syntax 

HRESULT ComposeWith( 
  IMoniker* 
pmkRight, 
  BOOL 
fOnlyIfNotGeneric, 
  IMoniker** 
ppmkComposite
);

Parameters

pmkRight

[in] Pointer to the IMonikerinterface on the moniker to compose onto the end of this moniker.

fOnlyIfNotGeneric

[in] Boolean that is set to TRUE if the caller requires a non-generic composition.

The operation should proceed only if pmkRightis a moniker class that this moniker can compose with in some way other than forming a generic composite.

If FALSE, the method can create a generic composite if necessary.

ppmkComposite

[out] Address of IMoniker* pointer variable that receives the interface pointer to the resulting composite moniker pointer.

When successful, the implementation must call the IUnknown::AddRefmethod on the resulting moniker; it is the caller's responsibility to call the IUnknown::Releasemethod.

If an error occurs or if the monikers compose to nothing (for example, composing an anti-moniker with an item moniker or a file moniker), * ppmkCompositeshould be set to NULL.

Return Value

The method supports the standard return values E_OUTOFMEMORY and E_UNEXPECTED.

The following table shows the additional return values for this method.

Value Description

S_OK

The monikers were successfully combined.

MK_E_NEEDGENERIC

Indicates that fOnlyIfNotGenericwas TRUE, but the monikers could not be composed together without creating a generic composite moniker.

Remarks

Joining two monikers together is called composition. Sometimes two monikers of the same class can be combined in what is called non-generic composition.

For example, a file moniker representing an incomplete path and another file moniker representing a relative path can be combined to form a single file moniker representing the complete path.

Nongeneric composition for a given moniker class can be handled only in the implementation of IMoniker::ComposeWithfor that moniker class.

Composition of monikers is an associative operation. That is, if A, B, and C are monikers, then, where Comp() represents the composition operation.

Copy Code 
Comp( Comp( A, B ), C )
	is always equal to
Comp( A, Comp( B, C ) )

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Notes to Callers

To combine two monikers, call IMoniker::ComposeWithto give the first moniker a chance to perform a non-generic composition.

An object that provides item monikers to identify its objects would call IMoniker::ComposeWithto provide a moniker that completely identifies the location of the object.

This would apply, for example, to a server that supports linking to portions of a document, or a container that supports linking to embedded objects within its documents.

In such a situation, do the following:

  1. Create an item moniker identifying an object.

  2. Get a moniker that identifies the object's container.

  3. Call IMoniker::ComposeWithon the moniker identifying the container, passing the item moniker as the pmkRightparameter.

Most callers of IMoniker::ComposeWithshould set the fOnlyIfNotGenericparameter to FALSE.

Notes to Implementers

You can use either non-generic or generic composition to compose the current moniker with the moniker that pmkRightpoints to. If the class of the moniker indicated by pmkRightis the same as that of the current moniker, it is possible to use the contents of pmkRightto perform a more intelligent non-generic composition.

In writing a new moniker class, you must decide if there are any kinds of monikers, whether of your own class or another class, to which you want to give special treatment.

If so, implement IMoniker::ComposeWithto check whether pmkRightis a moniker of the type that should have this treatment. To do this, you can call the moniker's IPersist::GetClassIDmethod (derived from the IPersistinterface), or, if you have defined a moniker object that supports a custom interface, you can call the IUnknown::QueryInterfacemethod on the moniker for that interface.

An example of special treatment would be the non-generic composition of an absolute file moniker with a relative file moniker. The most common case of a special moniker is the inverse for your moniker class (whatever you return from your implementation of the IMoniker::Inversemethod).

If pmkRightcompletely negates the receiver so the resulting composite is empty, you should pass back NULLin ppmkCompositeand return the status code S_OK.

If the pmkRightparameter is not of a class to which you give special treatment, examine fOnlyIfNotGenericto determine what to do next.

If fOnlyIfNotGenericis TRUE, pass back NULL through ppmkCompositeand return the status code MK_E_NEEDGENERIC.

If fOnlyIfNotGenericis FALSE, call the CreateGenericCompositefunction to perform the composition generically.

Requirements

Header objidl.h, objidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also