Reduces a moniker to its simplest form.
HRESULT Reduce( IBindCtx *pbc, DWORD dwReduceHowFar, IMoniker **ppmkToLeft, IMoniker **ppmkReduced );
A pointer to the IBindCtx interface on the bind context to be used in this binding operation. The bind context caches objects bound during the binding process, contains parameters that apply to all operations using the bind context, and provides the means by which the moniker implementation should retrieve information about its environment.
Specifies how far this moniker should be reduced. This parameter must be one of the values from the MKRREDUCE enumeration.
On entry, a pointer to an IMoniker pointer variable that contains the interface pointer to moniker to the left of this moniker. This parameter is used primarily by moniker implementers to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL.
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 Release on the old moniker to the left of this moniker and must call 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.
A pointer to an IMoniker pointer variable that receives the interface pointer to the reduced form of this moniker, which can be NULL if an error occurs or if this moniker is reduced to nothing. If this moniker cannot be reduced, *ppmkReduced is simply set to this moniker and the return value is MK_S_REDUCED_TO_SELF. If *ppmkReduced is non-NULL, the implementation must call AddRef on the new moniker; it is the caller's responsibility to call Release. (This is true even if *ppmkReduced is set to this moniker.)
This method can return the standard return values E_OUTOFMEMORY and E_UNEXPECTED, as well as the following values.
||The method completed successfully.|
||This moniker could not be reduced any further, so ppmkReduced indicates this moniker.|
||The operation could not be completed within the time limit specified by the bind context's BIND_OPTS structure.|
This method is intended for the following uses:
- Enable the construction of user-defined macros or aliases as new kinds of moniker classes. When reduced, the moniker to which the macro evaluates is returned.
- Enable the construction of a kind of moniker that tracks data as it moves about. When reduced, the moniker of the data in its current location is returned.
- On file systems that support an identifier-based method of accessing files that is independent of filenames; a file moniker could be reduced to a moniker which contains one of these identifiers.
You should call Reduce before comparing two monikers using the IMoniker::IsEqual method because a reduced moniker is in its most specific form. IsEqual may return S_FALSE on two monikers before they are reduced and return S_OK after they are reduced.
|Anti-moniker||This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.|
|Class moniker||This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.|
|File moniker||This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.|
|Generic composite moniker||This method recursively calls Reduce for each of its component monikers. If any of the components reduces itself, the method returns S_OK and passes back a composite of the reduced components. If no reduction occurred, the method passes back the same moniker and returns MK_S_REDUCED_TO_SELF.|
|Item moniker||This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.|
|OBJREF moniker||This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.|
|Pointer moniker||This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.|
|URL moniker||This method returns MK_S_REDUCED_TO_SELF and passes back the same moniker.|
|Minimum supported client||Windows 2000 Professional [desktop apps only]|
|Minimum supported server||Windows 2000 Server [desktop apps only]|