Platform SDK: Exchange Server

Implementing Property Sheet Extensions

To implement a property sheet extension

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

Property sheet extensions enable you to add custom property sheet pages for information stores, folders, and messages. These pages can be added to property sheets that are displayed in a variety of contexts. For example, you can add a page to the folder property sheet that is displayed when a user chooses the Properties command from the File menu in the main Viewer window when a folder is selected.

Property sheet extensions are useful for displaying custom properties for messages of a particular message class or for adding your own Microsoft Exchange options. For example, if you wrote an application that created and managed a specific public folder, you could add a property sheet page that would enable users to set various application-specific properties for the folder.

The sequence of events that should occur when Microsoft Exchange interacts with your extension object to install and use custom property sheet pages is as follows:

  1. When the user chooses Properties from the File menu to view the property sheet, Microsoft Exchange sequentially calls the IExchExt::Install method on all extensions registered to participate in the EECONTEXT_PROPERTYSHEETS context and passes each extension a pointer to an IExchExtCallback interface. These extensions, along with extensions that have registered for the context in which the property sheet is displayed, will be called to add property sheet pages. For example, if a property sheet is displayed in the Viewer window, extensions registered for the EECONTEXT_PROPERTYSHEETS or EECONTEXT_VIEWER context will be called.
  2. Microsoft Exchange calls the IExchExtPropertySheets::GetMaxPageCount method on each extension that returned S_OK from Install. This enables Microsoft Exchange to allocate sufficient memory for the property sheet page array.
  3. When Microsoft Exchange is ready to build the property sheet, it calls the IExchExtPropertySheets::GetPages method so that the extension can specify a pointer to the pages it will append. GetPages is called immediately before the property sheet is displayed and enables the extension to fill in the pages it wants appended to the Microsoft Exchange Properties dialog box. The standard Microsoft Exchange pages are added first, followed by pages from each extension in the order the extensions are installed. GetPages uses the IExchExtCallback::GetObject method to retrieve the object for which the information should be displayed and the store which contains that object. The extension must use the standard property sheet structures specified by the Windows API. One of the parameters passed to the extension in GetPages is the type of property sheet being displayed — for example, message, folder, or store property sheet.
  4. When the user closes the property sheet, Microsoft Exchange calls the IExchExtPropertySheets::FreePages method which instructs the extension to free any resources associated with the property sheet pages that were specified in GetPages.

The following table summarizes the interaction between a user, Microsoft Exchange and an extension object when a custom property sheet is being added to the Microsoft Exchange client. It also shows which component — the Microsoft Exchange client or the extension — performs the step and in the case of the extension, what method is invoked. To simplify this table, the installation of command extensions is not included. Command extensions are called in the context of a user choosing the Properties command from the File menu.