Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method reduces the moniker to the simplest form.

Syntax 

HRESULT Reduce( 
  IBindCtx* 
pbc, 
  DWORD 
dwReduceHowFar, 
  IMoniker** 
ppmkToLeft,
  IMoniker** 
ppmkReduced
);

Parameters

pbc

[in] Pointer to the IBindCtxinterface 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.

For more information, see IBindCtx.

dwReduceHowFar

[in] Value that specifies how far this moniker should be reduced. This parameter must be one of the values from the MKRREDUCEenumeration.

ppmkToLeft

[in, out] On entry, address of IMoniker* pointer variable that contains the interface pointer to moniker to the left of this moniker.

This parameter is primarily used by moniker implementers to enable cooperation between the various components of a composite moniker; moniker clients can usually pass NULL.

On return, * ppmkToLeftis usually set to NULL, that indicates no change in the original moniker to the left.

In rare situations, * ppmkToLeftindicates a moniker, that indicates that the previous moniker to the left should be disregarded and the moniker returned through * ppmkToLeftis the replacement.

In such a situation, the implementation must call the IUnknown::Releasemethod on the old moniker to the left of this moniker and must call the IUnknown::AddRefmethod 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.

ppmkReduced

[out] Address of 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, * ppmkReducedis simply set to this moniker and the return value is MK_S_REDUCED_TO_SELF.

If * ppmkReducedis non-NULL, the implementation must call IUnknown::AddRefon the new moniker; it is the caller's responsibility to call IUnknown::Release. (This is true even if * ppmkReducedis set to this moniker.)

Return Value

The method supports the standard return values E_UNEXPECTED and E_OUTOFMEMORY.

The following table shows the additional return values for this method.

Value Description

S_OK

This moniker was reduced.

MK_S_REDUCED_TO_SELF

This moniker could not be reduced any further, so ppmkReducedindicates this moniker.

MK_E_EXCEEDEDDEADLINE

The operation could not be completed within the time limit specified by the bind context's BIND_OPTSstructure.

Remarks

IMoniker::Reduceis intended for the following uses:

  • It enables 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.

  • It enables 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 file names; a file moniker could be reduced to a moniker that contains one of these identifiers.

The intent of the MKRREDUCEflags passed in the dwReduceHowFarparameter 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.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Notes to Callers

The scenarios described above are not currently implemented by the system-supplied moniker classes.

You should call IMoniker::Reducebefore comparing two monikers using the IMoniker::IsEqualmethod, because a reduced moniker is in its most specific form. IMoniker::IsEqualmay return S_FALSE on two monikers before they are reduced and return S_OK after they are reduced.

Notes to Implementers

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 leastas far as is requested.

Requirements

Header objidl.h, objidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also