Returns a reduced moniker; that is, another moniker that refers to the same object as this moniker but can be bound with equal or greater efficiency.
HRESULT Reduce(
IBindCtx *pbc, //Pointer to bind context to be used
DWORD dwReduceHowFar, //How much reduction should be done
IMoniker **ppmkToLeft, //Address of output variable that receives
//the IMoniker interface pointer to the
//moniker to the left in the composite
IMoniker **ppmkReduced //Address of output variable that receives
//the IMoniker interface pointer to the
//reduced moniker
);
On return, *ppmkToLeft is usually set to NULL, indicating no change in the original moniker to the left. In rare situations, *ppmkToLeft indicates a moniker, indicating that the previous moniker to the left should be disregarded and the moniker returned through *ppmkToLeft is the replacement. In such a situation, the implementation must call IUnknown::Release on the old moniker to the left of this moniker and must call IUnknown::AddRef on the new returned moniker; the caller must release it later. If an error occurs, the implementation can either leave the interface pointer unchanged or set it to NULL.
The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY, as well as the following:
IMoniker::Reduce is intended for the following uses:
The intent of the MKRREDUCE flags passed in the dwReduceHowFar parameter is to provide the ability to programmatically reduce a moniker to a form whose display name is recognizable to the user. For example, paths in the file system, bookmarks in word-processing documents, and range names in spreadsheets are all recognizable to users. In contrast, a macro or an alias encapsulated in a moniker are not recognizable to users.
The scenarios described above are not currently implemented by the system-supplied moniker classes.
You should call IMoniker::Reduce before comparing two monikers using the IMoniker::IsEqual method, because a reduced moniker is in its most specific form. IMoniker::IsEqual may return S_FALSE on two monikers before they are reduced and return S_OK after they are reduced.
If the current moniker can be reduced, your implementation must not reduce the moniker in-place. Instead, it must return a new moniker that represents the reduced state of the current one. This way, the caller still has the option of using the non-reduced moniker (for example, enumerating its components). Your implementation should reduce the moniker at least as far as is requested.
Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in objidl.h.