Combines the current moniker with another moniker, creating a new, composite
| IMoniker *pmkRight,
||//Moniker to be composed onto this one
| BOOL fOnlyIfNotGeneric,
||//Indicates if generic composition permissible
| IMoniker **ppmkComposite
||//Receives the composite
[in] Points to the moniker to compose onto the end of this moniker.
[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.
[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
Indicates that the monikers were successfully combined.
Indicates that fOnlyIfNotGeneric
was TRUE, but the monikers could not be composed together without creating a
generic composite moniker.
Indicates insufficient memory.
Indicates an unexpected error.
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
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
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
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.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages