Implementing Advanced Criteria Extensions

To implement advanced criteria extensions

1. Create a single DLL that contains one or more extension objects.
2. Implement the following interfaces:
   • IExchExt
   • IExchExtAdvancedCriteria
3. Register for the EECONTEXT_ADVANCED_CRITERIA context by placing an entry in the EXCHNG.INI file or 16-bit versions of Microsoft Windows or in the registry on Windows NT or Windows 95.

Advanced criteria extensions enable you to create your own advanced criteria window that can be used when searching for messages. This is especially useful when you want to enable users to search for custom message properties.

Although several extensions that supply advanced criteria dialog boxes might be available, only one advanced criteria window at a time can be displayed from a single context. Multiple advanced criteria contexts can be active at the same time; for example, when more than one Find window is open. Extensions are called in the order in which they were installed.

Because more than one advanced criteria extension might be installed, it is important to ensure that your advanced criteria is as selective as possible before choosing to install extensions into an advanced criteria context. For instance, a public folder application should only choose to install its advanced criteria interface when its public folder is open or highlighted.

Advanced criteria extensions that are more selective should be listed ahead of more general ones in the EXCHNG.INI file or the registry. Because Microsoft Exchange itself uses very general advanced criteria, most extensions should register themselves before Microsoft Exchange. If two or more such general advanced criteria extensions are present, the first one installed will always be used. The ordering of extensions is determined by their entry order in the EXCHNG.INI file or in the registry. For more information on creating extension entries, see Registering Extensions.

The sequence of events that should occur when Microsoft Exchange interacts with your extension object to add a custom advanced criteria dialog box to the Microsoft Exchange client is as follows:

1. When the user chooses the Find command from the Tools menu, Microsoft Exchange calls the IExchExt::Install method on all extension objects with the EECONTEXT_ADVANCEDCRITERIA bit set in the context map. During the call, it passes each extension a pointer to an IExchExtCallback interface along with the context, which in this case is EECONTEXT_ADVANCEDCRITERIA. The IExchExtCallBack pointer enables the extension to retrieve information about the current context. In this case, the current message store and folder will probably be useful. If it is the right context for you, return S_OK; otherwise, S_FALSE.
2. Microsoft Exchange calls the IExchExtAdvancedCriteria::InstallAdvancedCriteria method on the first extension to return S_OK from Install. Microsoft Exchange uses InstallAdvancedCriteria to pass information to the extension, including the window handle of the Find dialog box, the current advanced criteria restriction, and an array of folder entry identifiers to which the criteria will be applied. If the extension returns S_OK from InstallAdvancedCriteria, Microsoft Exchange will call the IExchExtAdvancedCriteria::DoDialog method when the user selects the Advanced button in the Find dialog box.

   If S_FALSE is returned from InstallAdvancedCriteria, remaining extensions will be given the opportunity to examine the current search restriction and display a custom search dialog box. If no extension returns S_OK, Microsoft Exchange will display the standard default advanced criteria dialog box.

3. If the user chooses the New Search button, changes folders, or closes the Find dialog box after Microsoft Exchange calls InstallAdvancedCriteria, Microsoft Exchange calls the IExchExtAdvancedCriteria::Clear, IExchExtAdvancedCriteria::SetFolders, or IExchExtAdvancedCriteria::QueryRestriction methods respectively to inform the extension of the changes.
4. When the user closes the advanced criteria window, Microsoft Exchange calls the IExchExtAdvancedCriteria::UninstallAdvancedCriteria method, which allows the extension to free any resources associated with the advanced criteria window that it displayed.

The following table summarizes the interaction between a user, Microsoft Exchange and an extension object when using a custom advanced criteria dialog box. It also shows which component — Microsoft Exchange or the client extension — performs the step and in the case of the client extension, what method is invoked.