IMsgServiceAdmin::CreateMsgService

The IMsgServiceAdmin::CreateMsgService method adds a message service to the current profile.

Quick Info

See IMsgServiceAdmin : IUnknown.

HRESULT CreateMsgService(
  LPTSTR lpszService,   
  LPTSTR lpszDisplayName,   
  ULONG ulUIParam,      
  ULONG ulFlags         
);
 

Parameters

lpszService

[in] Pointer to the name of the message service to add. This message service name must appear in the [Services] section of the MAPISVC.INF file.

lpszDisplayName

[in] Pointer to the display name of the message service to add. The lpszDisplayName parameter is ignored if the message service has set PR_DISPLAY_NAME in the MAPISVC.INF file.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

ulFlags

[in] Bitmask of flags that controls how the message service is installed. The following flags can be set:

MAPI_UNICODE

The names are in Unicode format. If the MAPI_UNICODE flag is not set, the names are in ANSI format.

SERVICE_UI_ALLOWED

Allows the display of the message service's configuration property sheet only if the service is not completely configured.

Return Values

S_OK

The call succeeded and has returned the expected value or values.

MAPI_E_NOT_FOUND

The message service name is not in the [Services] section of MAPISVC.INF.

Remarks

The IMsgServiceAdmin::CreateMsgService method adds a message service to the current profile. CreateMsgService calls the message service's entry point function to perform any service-specific configuration tasks. If the SERVICE_UI_ALLOWED flag is set in the ulFlags parameter, the message service being installed can display a property sheet to enable the user to configure its settings.

The list of providers that make up a message service and the properties for each are contained within the MAPISVC.INF file. CreateMsgService first creates a new profile section for the message service and then copies all of the information for that service from the MAPISVC.INF file into the profile, creating new sections for each provider.

After all the information has been copied from MAPISVC.INF, the message service's entry point function is called with the MSG_SERVICE_CREATE value set in the ulContext parameter. If the SERVICE_UI_ALLOWED flag is set in the CreateMsgService method's ulFlags parameter, then the values in the CreateMsgService ulUIParam and ulFlags parameters are also passed when the message service's entry point function is called. Service providers should display their configuration property sheets so users can configure the message service.

Notes to Callers

CreateMsgService does not return the MAPIUID for the message service added to the profile.

    To retrieve the MAPIUID for the created message service

1. Call IMsgServiceAdmin::GetMsgServiceTable to get the message service administration table.
2. Locate the row that represents the message service by placing a restriction on the table that matches the PR_SERVICE_NAME property with the name of the message service.
3. Retrieve the service's PR_SERVICE_UID property.
4. Pass the value of the PR_SERVICE_UID property in the lpUid parameter to IMsgServiceAdmin::ConfigureMsgService to configure the service.