IMoniker::RelativePathTo

Returns a moniker that, when composed onto the end of this moniker (or one with a similar structure), yields the specified moniker.

HRESULT RelativePathTo(

IMoniker *pmkOther,	//Moniker to which a relative path should be taken
IMoniker **ppmkRelPath	//Receives the relative moniker
);

Parameters

pmkOther

[in] Points to the moniker to which a relative path should be taken.

ppmkRelPath

[out] Receives a pointer to the relative moniker. If an error occurs, the implementation sets *ppmkRelPath to NULL. If *ppmkRelPath 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

A meaningful relative path has been returned.

MK_S_HIM

Indicates that there is no common prefix shared by the two monikers and that the moniker returned in *ppmkRelPath is pmkOther.

MK_E_NOTBINDABLE

Indicates that this moniker is a relative moniker, such as an item moniker. This moniker must be composed with the moniker of its container before a relative path can be determined.

E_OUTOFMEMORY

Indicates insufficient memory.

E_UNEXPECTED

Indicates an unexpected error.

Comments

A relative moniker is analogous to a relative path (such as "..\backup"). For example, suppose you have one moniker that represents the path "c:\projects\secret\art\pict1.bmp" and another moniker that represents the path "c:\projects\secret\docs\chap1.txt." Calling IMoniker::RelativePathTo on the first moniker, passing the second one as the pmkOther parameter, would create a relative moniker representing the path "..\docs\chap1.txt."

Notes to Callers

Moniker clients typically do not need to call IMoniker::RelativePathTo. This method is primarily called by the default handler for linked objects. Linked objects contain both an absolute and a relative moniker to identify the link source (this enables link tracking if the user moves a directory tree containing both the container and source files). The default handler calls this method to create a relative moniker from the container document to the link source (that is, it calls IMoniker::RelativePathTo on the moniker identifying the container document, passing the moniker identifying the link source as the pmkOther parameter).

If you do call IMoniker::RelativePathTo, call it only on absolute monikers; for example, a file moniker or a composite moniker whose leftmost-component is a file moniker, where the file moniker represents an absolute path. Do not call this method on relative monikers.

Notes to Implementors

Your implementation of IMoniker::RelativePathTo 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 relative path. Otherwise, it should pass both monikers in a call to the MonikerRelativePathTo API function, which correctly handles the generic case.

The first step in determining a relative path is determining the common prefix of this moniker and pmkOther. The next step is to break this moniker and pmkOther into two parts each, say (P, myTail) and (P, otherTail) respectively, where P is the common prefix. The correct relative path is then the inverse of myTail composed with otherTail:

Comp( Inv( myTail ), otherTail )

Where Comp() represents the composition operation and Inv() represents the inverse operation.

Note that for certain types of monikers, you cannot use your IMoniker::Inverse method to construct the inverse of myTail. For example, a file moniker returns an anti-moniker as an inverse, while its IMoniker::RelativePathTo method must use one or more file monikers that each represent the path ".." to construct the inverse of myTail.

See Also

IMoniker::Inverse, IMoniker::CommonPrefixWith, MonikerRelativePathTo

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