Implementing a Display Table

A display table is used to show a property sheet — a special dialog box that is made up of one or more tabbed property pages dedicated to displaying and possibly editing one or more properties. Associated with every display table is an IMAPIProp interface implementation. The IMAPIProp implementation maintains the property data that is presented in the property sheet.

The following illustration is an example of a property sheet that displays the properties of a messaging user:

The rows in a display table represent the controls in the property sheet. Most controls can be associated with properties maintained with the IMAPIProp implementation. When a user changes the value of a modifiable control, the corresponding property is updated.

The columns in a display table represent properties of the control, such as its position in the property sheet, its type, associated structure, and identifier. For a complete list of required display table columns, see Display Tables.

MAPI displays a property sheet to the user of a client application by reading property values from the IMAPIProp implementation associated with the display table or from the display table directly. As the user works with the property sheet, changing values in the controls, MAPI calls IMAPIProp::SetProps to save a changed control if the control's DT_SET_IMMEDIATE flag is set. For controls without the DT_SET_IMMEDIATE flag set, changes to properties are saved when the user dismisses the dialog box by clicking the OK or Apply Now button. When either of these buttons or the Cancel button is clicked, MAPI removes the property sheet from view.

MAPI gains access to your display table either by calling the OpenProperty method in the IMAPIProp implementation and requesting the PR_DETAILS_TABLE property or by inheriting it in a call that you have made to MAPI, such as IMAPISupport::DoConfigPropsheet.

The first access technique is used when address book providers are asked to show details about messaging users or distribution lists. The following processing occurs:

  1. A client calls the IAddrBook::Details method.
  2. MAPI calls the address book provider's IABLogon::OpenEntry method to access the messaging user that represents the selected entry.
  3. MAPI calls the messaging user's IMAPIProp::OpenProperty method to retrieve the PR_DETAILS_TABLE property, the display table for the details dialog box.
  4. MAPI displays the dialog box, handling the user's interaction with the information, and removes it when the user has finished.

A combination of the two access techniques is used when transport providers are asked to show a message options property sheet. The transport provider makes the property interface available to MAPI through a callback function. MAPI then calls the property interface to open the PR_DETAILS_TABLE property.

Before a message options property sheet can be shown, the transport provider must:

  1. Make the message options properties available by returning an OPTIONDATA structure with information about supported options when MAPI calls its IXPLogon::RegisterOptions method.
  2. Implement a function that conforms to the OPTIONCALLBACK prototype. The OPTIONCALLBACK function handles the data stored in the OPTIONDATA structure.

When it is time to show the message options property sheet, the following processing occurs:

  1. The client calls IMAPISession::MessageOptions.
  2. MAPI calls the transport provider's OPTIONCALLBACK function which returns an IMAPIProp interface implementation. The OpenProperty method of this implementation supports the PR_DETAILS_TABLE property.
  3. When the OPTIONCALLBACK function returns, MAPI calls OpenProperty to open PR_DETAILS_TABLE and retrieve the display table describing the message options dialog box.
  4. MAPI displays the dialog box, handling the user's interaction with the information, and removes it when the user has finished.