Applies to: Outlook
Reconfigures a message service.
HRESULT ConfigureMsgService( LPMAPIUID lpUID, ULONG_PTR ulUIParam, ULONG ulFlags, ULONG cValues, LPSPropValue lpProps );
[in] A pointer to the MAPIUID structure that contains the unique identifier for the message service to configure.
[in] A handle to the parent window of the configuration property sheet.
[in] A bitmask of flags that controls the display of the property sheet. The following flags can be set:
The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.
The message service should display its configuration property sheet but not enable the user to change it. Most message services ignore this flag.
The message service should display its configuration property sheet only if the service is not completely configured.
The message service must always display its configuration property sheet. If SERVICE_UI_ALWAYS is not set, a configuration property sheet can still be displayed if SERVICE_UI_ALLOWED is set and valid configuration information is not available from the property value array in the lpProps parameter. Either SERVICE_UI_ALLOWED or SERVICE_UI_ALWAYS must be set for a property sheet to be displayed.
[in] The count of property values in the SPropValue structure pointed to by lpProps.
[in] A pointer to an array of property values that describe the properties to display in the property sheet. The lpProps parameter should not be NULL if the message service should be configured without a user interface.
The message service was successfully configured.
The MAPIUID pointed to by lpUID does not match that of an existing message service.
The message service does not have an entry point function.
The user canceled the operation, typically by clicking the Cancel button in the property sheet.
The IMsgServiceAdmin::ConfigureMsgService method enables a message service to be configured, with or without a configuration property sheet.
To allow configuration without a property sheet display, message services typically prepare a header file that includes constants for all the required and optional properties and their values.
Notes to callers
To retrieve the MAPIUID structure for the message service to configure, retrieve the PR_SERVICE_UID (PidTagServiceUid) column from the message service's row in the message service table. For more information, see the procedure outlined in the IMsgServiceAdmin::CreateMsgService method.
You can configure a message service without displaying a property sheet to a user only if you have advance information about the property values to be set. If you are configuring a message service without displaying a property sheet, pass valid property values in the lpProps parameter and do not set the MSG_SERVICE_UI_READ_ONLY, SERVICE_UI_ALLOWED, or SERVICE_UI_ALWAYS flags.
If you receive all or some of the configuration information from the user by way of a property sheet, set SERVICE_UI_ALLOWED in ulFlags. If you use existing property information only to establish default settings and the user is able to change the settings, set SERVICE_UI_ALWAYS in ulFlags.
For MFCMAPI sample code, see the following table.
||MFCMAPI uses the IMsgServiceAdmin::ConfigureMsgService method to configure a service that has been added to a profile.