IMsgServiceAdmin::ConfigureMsgService

The IMsgServiceAdmin::ConfigureMsgService method reconfigures a message service.

Quick Info

See IMsgServiceAdmin : IUnknownAV9KUM.

HRESULT ConfigureMsgService(

Parameters

lpUID

[in] Pointer to the MAPIUIDT02NXD 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 be NULL if the message service is being configured without displaying a property sheet.

Return Values

S_OK

The message service was successfully configured.

MAPI_E_EXTENDED_ERROR

An error specific to a message service. To get the MAPIERROR4GS6AI structure describing the error, the client application should call the IMsgServiceAdmin::GetLastError1WUB0RA 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_UID1NI9UDF column from the message service s row in the message service table. See the procedure outlined in IMsgServiceAdmin::CreateMsgService63PW_7 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, 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 via 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.

See Also