IMoniker::Reduce

HRESULT IMoniker::Reduce(pbc, dwReduceHowFar, ppmkToLeft, ppmkReduced)

The reduction of monikers was reviewed and illustrated in the synopsis above; this is the function that actually carries it out. Return a more efficient or equally efficient moniker that refers to the same object as does this moniker. Many monikers, if not most, will simply reduce to themselves, since they cannot be rewritten any further. A moniker which reduces to itself indicates this by returning itself through ppmkReduced and the returning status code MK_S_REDUCED_TO_SELF. A moniker which reduces to nothing should return NULL, and should return the status code S_OK.

If the moniker does not reduce to itself, then this function does not reduce this moniker in-place; instead, it returns a new moniker.

The reduction of a moniker which is a composite of other monikers repeatedly reduces the pieces of which it is composed until they all reduce to themselves, then returns the composite of the reduced pieces. dwReduceHowFar controls the stopping point of the reduction process. It controls to what extent the reduction should be carried out. It has the following legal values.

typedef enum tagMKRREDUCE {
    MKRREDUCE_ONE            = 3<<16,
    MKRREDUCE_TOUSER            = 2<<16,
    MKRREDUCE_THROUGUSER    = 1<<16,
    MKRREDUCE_ALL                 = 0
    } MKRREDUCE;

These values have the following semantics.

Value	Description
MKRREDUCE _ONE	Perform only one step of reduction on this moniker. In general, the caller will have to have specific knowledge as to the particular kind of moniker in question in order to be able to usefully take advantage of this option.
MKRREDUCE _TOUSER	Reduce this moniker to the first point where it first is of the form where it represents something that the user conceptualizes as being the identity of a persistent object. For example, a file name would qualify, but a macro or an alias would not. If no such point exists, then this option should be treated as MKRREDUCE_ALL.
MKRREDUCE _THROUGUSER	Reduce this moniker to the point where any further reduction would reduce it to a form which the user does not conceptualize as being the identity of a persistent object. Often, this is the same stage as MKRREDUCE_TOUSER.
MKRREDUCE _ALL	Reduce the entire moniker, then, if needed reduce it again and again to the point where it reduces to simply itself.

When determining whether they have reduced themselves as far as requested, IMoniker::Reduce implementations should not compare for equality against dwReduceHowFar, as we wish to allow for the possibility that intermediate levels of reduction will be introduced in the future. Instead, IMoniker::Reduce implementations should reduce themselves at least as far as is requested.

An important concept in the above is the idea of a moniker that the user thinks of as the name of a persistent object; a persistent identity. The intent is to provide the ability to programmatically reduce a moniker to canonical forms whose display names would be recognizable to the user. Paths in the file system, bookmarks in word-processing documents, and range names in spreadsheets are all examples of user-identities. In contrast, neither a macro nor an alias encapsulated in a moniker, nor an inode-like file ID moniker are such identities.

The bind context parameter is used as in IMoniker::BindToObject. In particular, implementations of IMoniker::Reduce should pay attention to the time deadline imposed by the caller and the reporting of the moniker of the object that, if it had been running, would have allowed the reduction to progress further. See IBindCtx below.

Argument	Type	Description
pbc	IBindCtx*	The bind context to use in this operation.
dwReduceHowFar	DWORD	Indicates to what degree this moniker should be reduced; see above.
ppmkToLeft	IMoniker**	On entry, the moniker which is the prefix of this one in the composite in which it is found. On exit, the pointer is either NULL or non-NULL. Non-NULL indicates that what was previously thought of as the prefix should be disregarded and the moniker returned through ppmkToLeft considered the prefix in its place (this is very rare). NULL indicates that the prefix should not be so replaced. Thus, most monikers will NULL out this parameter before returning.
ppmkReduced	IMoniker**	On exit, the reduced form of this moniker. Possibly NULL.
return value	HRESULT	S_OK, MK_S_REDUCED_TO_SELF, MK_E_EXCEEDEDDEADLINE.