IMsgServiceAdmin::ConfigureMsgService

The IMsgServiceAdmin::ConfigureMsgService method reconfigures a message service.

Quick Info

HRESULT ConfigureMsgService(
  LPMAPIUID lpUID,      
  ULONG ulUIParam,      
  ULONG ulFlags,        
  ULONG cValues,        
  LPSPropValue lpProps  
);

Parameters

lpUID

[in] Pointer to the MAPIUID structure holding the unique identifier for the message service to configure.

ulUIParam

[in] Handle of the parent window for the configuration property sheet.

ulFlags

[in] Bitmask of flags that controls the display of the property sheet. The following flags can be set:

MAPI_UNICODE: The passed-in strings are in Unicode format. If the MAPI_UNICODE flag is not set, the strings are in ANSI format.
MSG_SERVICE_UI_READ_ONLY: The message service should display its configuration property sheet but not enable the user to change it. Most message services ignore this flag.
SERVICE_UI_ALLOWED: The message service should display its configuration property sheet only if the service is not completely configured.
SERVICE_UI_ALWAYS: 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.

cValues

[in] Count of property values in the SPropValue structure pointed to by lpProps.

lpProps

[in] Pointer to an array of property values describing 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.

Return Values

S_OK: The message service was successfully configured.
MAPI_E_EXTENDED_ERROR: An error specific to a message service. To get the MAPIERROR structure describing the error, the client application should call the IMsgServiceAdmin::GetLastError method.
MAPI_E_NOT_FOUND: The MAPIUID pointed to by lpUID does not match that of an existing message service.
MAPI_E_NOT_INITIALIZED: The message service does not have an entry point function.
MAPI_E_USER_CANCEL: The user canceled the operation, typically by clicking the Cancel button in the property sheet.

Remarks

The IMsgServiceAdmin::ConfigureMsgService method allows 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 for the message service to configure, retrieve the PR_SERVICE_UID column from the message service's row in the message service table. See the procedure outlined in IMsgServiceAdmin::CreateMsgService for more information.

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.