Implementing a Control Object

Control objects, or objects that support the IMAPIControl interface, are implemented by providers to add functionality to a button that appears on a MAPI dialog box. Control objects can only be implemented for buttons.

IMAPIControl has three methods: GetLastError, GetState, and Activate.

MAPI calls IMAPIControl::GetState to determine whether or not to disable the button. GetState is called:

• When the dialog box on which the button appears is first displayed.
• When a display table notification is issued for the button.

Set the contents of the lpulState parameter to MAPI_DISABLED if the user cannot interact with the button and MAPI_ENABLED if the user can interact.

When the user clicks the button, MAPI calls Activate. Activate performs the task that has been associated with the button. This task can be anything appropriate for your provider, such as displaying a dialog box or updating a property. If the task is unsuccessful because the user has canceled it, return MAPI_E_USER_CANCEL. With other causes of failure, return the appropriate error value.

If the task is successful and it is linked to a property change that is reflected in another control on the dialog box, call ITableData::HrNotify. HrNotify is called to issue a display table notification with the changed property's PR_CONTROL_ID in the TABLE_NOTIFICATION structure. Do not place the new property value in the structure; return it instead when IMAPIProp::GetProps is called. Although typically a display table notification cannot be used to disable or enable a control, it can be used with a button. MAPI will refresh the changed control to respond to the notification.

MAPI calls the control's GetLastError method when Activate returns an error other than MAPI_E_USER_CANCEL. If GetLastError places extended error information in the MAPIERROR structure that it returns in the contents of the lppMAPIError parameter, MAPI displays it for the user.