IMoniker::CommonPrefixWith method (objidl.h)
Creates a new moniker based on the prefix that this moniker has in common with the specified moniker.
HRESULT CommonPrefixWith(
[in] IMoniker *pmkOther,
[out] IMoniker **ppmkPrefix
);
[in] pmkOther
A pointer to the IMoniker interface on another moniker to be compared with this one to determine whether there is a common prefix.
[out] ppmkPrefix
The address of an IMoniker* pointer variable that receives the interface pointer to the moniker that is the common prefix of this moniker and pmkOther. When successful, the implementation must call AddRef on the resulting moniker; it is the caller's responsibility to call Release. If an error occurs or if there is no common prefix, the implementation should set *ppmkPrefix to NULL.
This method can return the standard return values E_OUTOFMEMORY, as well as the following values.
Return code | Description |
---|---|
|
A common prefix exists that is neither this moniker nor pmkOther. |
|
No common prefix exists. |
|
The entire pmkOther is a prefix of this moniker. |
|
The two monikers are identical. |
|
This moniker is a prefix of the pmkOther moniker. |
|
This method was called on a relative moniker. It is not meaningful to take the common prefix on a relative moniker. |
CommonPrefixWith creates a new moniker that consists of the common prefixes of the moniker on this moniker object and another moniker. For example, if one moniker represents the path "c:\projects\secret\art\pict1.bmp" and another moniker represents the path "c:\projects\secret\docs\chap1.txt", the common prefix of these two monikers would be a moniker representing the path "c:\projects\secret".
The CommonPrefixWith method is primarily called in the implementation of the IMoniker::RelativePathTo method. Clients using a moniker to locate an object rarely need to call this method.Call this method only if pmkOther and this moniker are both absolute monikers. An absolute moniker is either a file moniker or a generic composite whose leftmost component is a file moniker that represents an absolute path. Do not call this method on relative monikers because it would not produce meaningful results.
Your implementation should first determine whether pmkOther is a moniker of a class that you recognize and for which you can provide special handling (for example, if it is of the same class as this moniker). If so, your implementation should determine the common prefix of the two monikers. Otherwise, it should pass both monikers in a call to the MonikerCommonPrefixWith function, which correctly handles the generic case.Implementation | Notes |
---|---|
Anti-moniker | If the other moniker is also an anti-moniker, the method returns MK_S_US and sets ppmkPrefix to this moniker. Otherwise, the method calls the MonikerCommonPrefixWith function. This function correctly handles the case where the other moniker is a generic composite. |
Class moniker | If pmkOther is equal to this moniker, retrieves a pointer to this moniker and returns MK_S_US. If pmkOther is a class moniker but is not equal to this moniker, returns MK_E_NOPREFIX. Otherwise, returns the result of calling MonikerCommonPrefixWith with itself as pmkThis, pmkOther, and ppmkPrefix, which handles the case where pmkOther is a generic composite moniker. |
File moniker |
If both monikers are file monikers, this method returns a file moniker that is based on the common components at the beginning of two file monikers. Components of a file moniker can be of the following types:
This method returns MK_E_NOPREFIX if there is no common prefix. |
Generic composite moniker |
If the other moniker is a composite, this method compares the components of each composite from left to right. The returned common prefix moniker might also be a composite moniker, depending on how many of the leftmost components were common to both monikers. If the other moniker is not a composite, the method simply compares it to the leftmost component of this moniker.
If the monikers are equal, the method returns MK_S_US and sets ppmkPrefix to this moniker. If the other moniker is a prefix of this moniker, the method returns MK_S_HIM and sets ppmkPrefix to the other moniker. If this moniker is a prefix of the other, this method returns MK_S_ME and sets ppmkPrefix to this moniker. If there is no common prefix, this method returns MK_E_NOPREFIX and sets ppmkPrefix to NULL. |
Item moniker | If the other moniker is an item moniker that is equal to this moniker, this method sets *ppmkPrefix to this moniker and returns MK_S_US; otherwise, the method calls the MonikerCommonPrefixWith function. This function correctly handles the case where the other moniker is a generic composite. |
OBJREF moniker |
If the two monikers are equal, this method returns MK_S_US and sets *ppmkPrefix to NULL. If the other moniker is not an OBJREF moniker, this method passes both monikers to the MonikerCommonPrefixWith function. This function correctly handles the case where the other moniker is a generic composite.
If there is no common prefix, this method returns MK_E_NOPREFIX. |
Pointer moniker | If the two monikers are equal, this method returns MK_S_US and sets *ppmkPrefix to this moniker. Otherwise, the method returns MK_E_NOPREFIX and sets *ppmkPrefix to NULL. |
URL moniker | This method returns E_NOTIMPL. |
Requirement | Value |
---|---|
Minimum supported client | Windows 2000 Professional [desktop apps only] |
Minimum supported server | Windows 2000 Server [desktop apps only] |
Target Platform | Windows |
Header | objidl.h |