IMoniker::ComposeWith

Combines the current moniker with another moniker, creating a new, composite moniker.

HRESULT ComposeWith(

IMoniker *pmkRight,	//Moniker to be composed onto this one
BOOL fOnlyIfNotGeneric,	//Indicates if generic composition permissible
IMoniker **ppmkComposite	//Receives the composite
);

Parameters
pmkRight

[in] Points to the moniker to compose onto the end of this moniker.

fOnlyIfNotGeneric

[in] Indicates whether the method must perform a non-generic composition. If TRUE, the caller requires a non-generic composition, so the operation should proceed only if pmkRight is 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] Receives a pointer to the resulting composite moniker. If an error occurs or if the monikers compose to nothing (e.g., composing an anti-moniker with an item moniker or a file moniker), the implementation sets *ppmkComposite to NULL. If *ppmkComposite is non-NULL, the implementation must call IUnknown::AddRef on the parameter; it is the caller's responsibility to call IUnknown::Release.

Return Values
S_OK

Indicates that the monikers were successfully combined.

MK_E_NEEDGENERIC

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

E_OUTOFMEMORY

Indicates insufficient memory.

E_UNEXPECTED

Indicates an unexpected error.

Comments
The process of joining two monikers together is called composition. Sometimes two monikers of specific classes can be combined in a special manner; 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. This is an example of "non-generic" composition. "Generic" composition, on the other hand, can connect any two monikers, no matter what their classes. Because a non-generic composition depends on the class of the monikers involved, it can be performed only by an particular class's implementation of the IMoniker::ComposeWith method. You can define new types of non-generic compositions if you write a new moniker class. By contrast, generic compositions are performed by the CreateGenericComposite API function.

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

Comp( Comp( A, B ), C )

is always equal to

Comp( A, Comp( B, C ) )

where Comp() represents the composition operation.

Notes to Callers
If you want to combine two monikers, you should call the IMoniker::ComposeWith method rather than calling CreateGenericComposite API function; this gives the first moniker a chance to perform a non-generic composition.

A common situation in which you would combine two monikers is if you are a moniker provider using item monikers to identify your objects; for example, if your application is a server that supports linking to portions of a document, or if it's a container that supports linking to embedded objects within its documents. In such a situation, you would do the following:

Create an item moniker identifying an object.
Get a moniker that identifies the object's container.
Call IMoniker::ComposeWith on the moniker identifying the container, passing the item moniker as the pmkRight parameter.

Most callers of IMoniker::ComposeWith should set the fOnlyIfNotGeneric parameter to FALSE.

Notes to Implementors
As described above, there are two ways to compose pmkRight to your moniker: by performing a generic composition, or by performing a non-generic composition. The latter means seeing if you recognize the pmkRight parameter's class and if so, using the contents of pmkRight to perform a more intelligent composition.

When writing your moniker class, you must decide if there are any kinds of monikers to which you want to give special treatment (as described above in the example of the file monikers); these don't have to be monikers of your own class. You then implement IMoniker::ComposeWith to examine pmkRight to check whether it is such a special moniker; possible ways of doing this are to ask pmkRight for its class or call IUnknown::QueryInterface on it. The most common case of a special moniker is the inverse for your moniker class (that is, whatever you return from your implementation of IMoniker::Inverse).

If the pmkRight parameter is a moniker of a class that you give special treatment, your implementation of IMoniker::ComposeWith should do whatever is appropriate for that special case. If pmkRight completely negates the receiver so that the resulting composite is empty, you should pass back NULL in ppmkComposite and return the status code S_OK.

If the pmkRight parameter is not of a class to which you give special treatment, examine fOnlyIfNotGeneric to determine what to do next. If fOnlyIfNotGeneric is TRUE, pass back NULL through ppmkComposite and return the status code MK_E_NEEDGENERIC. If fOnlyIfNotGeneric is FALSE, call the CreateGenericComposite API to perform the composition generically.

See Also
CreateGenericComposite, IMoniker::Inverse

Software for developers: Delphi Components
.Net Components
Software for Android Developers
More information resources: MegaDetailed.Net
Unix Manual Pages
Delphi Examples
Databases for Amazon shops developers: Amazon Categories Database
Browse Nodes Database