IMsgServiceAdmin::ConfigureMsgService

Applies to: Office 2010 | Outlook 2010 | Visual Studio

Reconfigures a message service.

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

Parameters

• lpUID
  [in] A pointer to the MAPIUID structure that contains the unique identifier for the message service to configure.

• ulUIParam
  [in] A handle to the parent window of the configuration property sheet.

• ulFlags
  [in] A 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] The count of property values in the SPropValue structure pointed to by lpProps.

• 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.

Return Value

• S_OK
  The message service was successfully configured.

• MAPI_E_EXTENDED_ERROR
  An error specific to a message service. To get the MAPIERROR structure that describes 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 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.

MFCMAPI Reference

For MFCMAPI sample code, see the following table.

See Also

Reference

MAPIUID

SPropValue

IMsgServiceAdmin : IUnknown

Concepts

MFCMAPI as a Code Sample