IExchExtAdvancedCriteria::InstallAdvancedCriteria

Enables an extension object to install its advanced criteria dialog box.

Quick Info

See IExchExtAdvancedCriteria : IUnknown.

HRESULT InstallAdvancedCriteria(
  HWND hwnd,              
  LPSRestriction lpres,   
  BOOL fNot,              
  LPENTRYLIST lpeidl,     
  ULONG ulFlags           
);

Parameters

hwnd

[in] Window handle containing the advanced criteria user interface.

lpres

[in] Pointer to a MAPI SRestriction structure containing the advanced criteria restriction. NULL if none exists.

fNot

[in] TRUE if the user wants only messages that do not meet the criteria specified in the structure pointed to by the lpres parameter.

lpeidl

[in] Pointer to an array of folder entry identifiers to which the criteria will be applied.

ulFlags

[in] Bitmask of flags. The following flag can be set:

EEAC_INCLUDESUBFOLDERS: Subfolders of the lpeidl parameter are to be included in the search.

Return Values

S_OK: The extension object will display its advanced criteria user interface.
S_FALSE: The extension object will not display its advanced criteria user interface.

Remarks

Microsoft Exchange calls the IExchExtAdvancedCriteria::InstallAdvancedCriteria method when the user chooses the Advanced button in the Find dialog box. The first extension that returns S_OK is the only IExchExtAdvancedCriteria interface implementation used for the criteria dialog box instance. Implementations of this method should examine the lpres parameter to see if the restriction's format is recognizable. If not, S_FALSE should be returned and other extensions will be given the opportunity to handle the restriction. Extensions should use comment fields in restrictions to identify their particular formats.

Calls to InstallAdvancedCriteria will not be nested within a single context; that is, they will not be prompted to install their advanced criteria dialog box a second time before an existing installation has been uninstalled (with the exception of multiple instances of Microsoft Exchange Find windows and advanced criteria objects). Specifically, separate contexts which use IExchExtAdvancedCriteria can have overlapping lifespans.

To determine whether your extension should participate in the current advanced criteria context, you can obtain information about the context during the last call to the IExchExt::Install method. You might want to save information about the advanced criteria context for later use. You cannot save the pointer to the callback object during the call to Install.

If S_FALSE is returned, remaining extension objects will be given the opportunity to recognize the restriction and display the user interface. If no extension object returns S_OK, the Advanced button will be disabled. Microsoft Exchange will provide default advanced criteria functionality.