SERVICEWIZARDDLGPROC

The SERVICEWIZARDDLGPROC function prototype defines a callback function invoked by the Profile Wizard to allow a provider to react to user events when the provider s property sheets or pages are shown.

Quick Info

BOOL SERVICEWIZARDDLGPROC(

Parameters

hDlg

[in] Window handle to the Profile Wizard dialog box.

wMsgID

[in] The message to be processed. In addition to all the regular Windows messages expected by a modal dialog box, the following messages can be received:

WM_CLOSE

Called when the Profile Wizard has completed. The provider should do any cleanup such as deallocating any dynamically allocated memory.

WM_COMMAND

Called for all of the provider s controls, and in addition, WM_COMMAND is called for the Next {  ID_NEXT }, and Prev {  ID_PREV } buttons. When called with ID_NEXT or ID_PREV, the provider is responsible for hiding the old page s controls and showing the controls for the next or previous page.

WM_INITDIALOG

Called even after the dialog box exists to allow the provider to initialize the controls that the Profile Wizard has added to the dialog box.

WIZ_QUERYNUMPAGES

Called to ask for the number of pages that the provider needs to display. The provider should return the number of pages instead of TRUE or FALSE. For example, use the following return statement to indicate that three pages should to be displayed:

return (BOOL)3;

wParam

[in] Contents depend on the message specified in the wMsgID parameter.

lParam

[in] Contents depend on the message specified in the wMsgID parameter.

Remarks

When the user chooses the Next button, the SERVICEWIZARDDLGPROC function is called with the WM_COMMAND message and ID_NEXT in the wParam parameter. The following steps describe what occurs between the time the user chooses Next and the time the first provider s configuration pages are rendered.

  1.  The Profile Wizard hides any controls that are on the window.

  2.  The Profile Wizard adds the provider s controls (hidden) to the page.

  3.  The Profile Wizard calls SERVICEWIZARDDLGPROC, sending the WM_INITDIALOG message, so that the provider can initialize the controls.

  4.  The Profile Wizard calls SERVICEWIZARDDLGPROC, sending the WIZ_QUERYNUMPAGES message. The provider returns the number of pages that it will be showing.

  5.  The Profile Wizard calls SERVICEWIZARDDLGPROC, sending the WM_COMMAND message with the wParam parameter set to either ID_NEXT or ID_PREV. At this point, the provider either returns FALSE { error} or reveals its controls and returns TRUE { success}. If the Profile Wizard passes in ID_NEXT, the provider s first page is displayed. If ID_PREV is passed in, the last page is displayed.

  6.  The Profile Wizard calls the provider s SERVICEWIZARDDLGPROC function, sending the WM_COMMAND message with the wParam parameter set to either ID_NEXT or ID_PREV (depending on which button the user chose). The provider is responsible for showing or hiding its controls and writing its data to the IMAPIProp passed to the profile wizard to step through its sequence of pages. The provider should return TRUE if the next or previous page was successfully shown, and FALSE if neither the next nor previous page could be shown. The provider needs to be aware of when it is stepping outside of its sequence of pages, and respond appropriately by hiding its controls and writing its data to the profile.

  7.  If the user steps outside the provider s range of pages, the Profile Wizard deletes the provider s hidden controls from the dialog box and calls the next provider (or displays its next page if that was the last provider).

The value returned by SERVICEWIZARDDLGPROC is dependent on the message type sent. The recommended practice is to return TRUE if the provider processes the message and FALSE if the provider does not process the message.