Export (0) Print
Expand All

IMoniker::CommonPrefixWith method

Creates a new moniker based on the prefix that this moniker has in common with the specified moniker.

Syntax


HRESULT CommonPrefixWith(
  [in]   IMoniker *pmkOther,
  [out]  IMoniker **ppmkPrefix
);

Parameters

pmkOther [in]

A pointer to the IMoniker interface on another moniker to be compared with this one to determine whether there is a common prefix.

ppmkPrefix [out]

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.

Return value

This method can return the standard return values E_OUTOFMEMORY, as well as the following values.

Return codeDescription
S_OK

A common prefix exists that is neither this moniker nor pmkOther.

MK_S_NOPREFIX

No common prefix exists.

MK_S_HIM

The entire pmkOther is a prefix of this moniker.

MK_S_US

The two monikers are identical.

MK_S_ME

This moniker is a prefix of the pmkOther moniker.

MK_S_NOTBINDABLE

This method was called on a relative moniker. It is not meaningful to take the common prefix on a relative moniker.

 

Remarks

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".

Notes to Callers

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.

Notes to Implementers

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-specific Notes

ImplementationNotes
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:

  • A computer name of the form \\server\share. A computer name is treated as a single component, so two monikers representing the paths "\\myserver\public\work" and "\\myserver\private\games" do not have "\\myserver" as a common prefix.
  • A drive designation (for example, "C:").
  • A directory or file name.

If the other moniker is not a file moniker, this method passes both monikers in a call to the MonikerCommonPrefixWith function. This function correctly handles the case where the other moniker is a generic composite.

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.

 

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

ObjIdl.h

IDL

ObjIdl.idl

IID

IID_IMoniker is defined as 0000000f-0000-0000-C000-000000000046

See also

IMoniker
MonikerCommonPrefixWith

 

 

Community Additions

ADD
Show:
© 2014 Microsoft