IMoniker::ComposeWith

HRESULT IMoniker::ComposeWith(pmkRight, fOnlyIfNotGeneric, ppmkComposite)

Return a new moniker which is a composite formed with this moniker on the left and pmkRight on the right. It is using this operation that the pieces of the path to an object are cobbled together to form the overall full path.

There are two distinct kinds of composite monikers: those that know nothing about their pieces other than that they are monikers, and those that know more. We have been terming the former a generic composite; we have seen several examples above. An example of the latter might be that of the result of composing a File Moniker containing a relative path on to the end of another File Moniker: the result could be a new File Moniker containing the complete path.3. There is only a need for one implementation of a Generic Composite Moniker, and this has been provided; see CreateGenericComposite().

Non-generic composition is useful for monikers that are capable of collapsing a path within a storage domain to a more efficient representation in a subsequent IMoniker::Reduce operation. None of the core monikers on Win32 are capable of this, but an implementation of File Moniker which could collapse down to a inode-like file ID might be an example of such a behavior.

Each moniker class in general will have a (possibly empty) set of other kinds of special monikers that can be composed onto the end of it in a non-generic way; the moniker class has some sort of intimate knowledge about the semantics of these special monikers, more than simply that they are monikers. Each IMoniker::ComposeWith implementation will examine pmkRight to see if it is such a special moniker for this implementation. Often, it will ask pmkRight for its class, but other possibilities exist, such as using QueryInterface. A very common case of such special monikers are Anti-monikers.

If pmkRight is special, then the IMoniker::ComposeWith implementation does whatever is appropriate for that special case. If it is not, then fOnlyIfNotGeneric controls what should occur. If fOnlyIfNotGeneric is true, then NULL should be passed back through ppmkComposite and the status MK_E_NEEDGENERIC returned; if fOnlyIfNotGeneric is false, then a generic composite should be returned using CreateGenericComposite. Most callers of IMoniker::ComposeWith should set fOnlyIfNotGeneric to false.4.

In any situation that pmkRight completely annihilates the receiver (for example, irrespective of fOnlyIfNotGeneric), and so the resulting composite is empty, NULL should be passed back through ppmkComposite and the status S_OK returned.

The pieces of a moniker that have been composed together can be picked apart using IMoniker::Enum. On a generic composite, this enumerates the monikers contained within it. On other monikers, which particular pieces are returned is implementation-defined.

Composition of monikers is an associative operation. That is, if A, B, and C are monikers, then

     (A +  B) + C

is always equal to

     A +  (B + C)

where+ represents the composition operation. Each implementation of IMoniker::ComposeWith must maintain this invariant.

Argument	Type	Description
pmkRight	IMoniker*	The moniker to compose onto the end of the receiver.
fOnlyIfNotGeneric	BOOL	Controls what should be done in the case that the way for form a composite is to use a generic one.
ppmkComposite	IMoniker*	On exit, the resulting composite moniker. Possibly NULL.
return value	HRESULT	S_OK, MK_E_NEEDGENERIC