MSGSERVICEENTRY

The MSGSERVICEENTRY function prototype defines a message service entry point function to support message service configuration.

Quick Info

Header file:	MAPISPI.H
Defined function implemented by:	Message services
Defined function called by:	MAPI

HRESULT MSGSERVICEENTRY(
  HINSTANCE hInstance,            
  LPMALLOC lpMalloc,              
  LPMAPISUP lpMAPISup,            
  ULONG ulUIParam,                
  ULONG ulFlags,                  
  ULONG ulContext,                
  ULONG cValues,                  
  LPSPropValue lpProps,           
  LPPROVIDERADMIN lpProviderAdmin,   
  LPMAPIERROR FAR * lppMapiError  
);

Parameters

hInstance

[in] Handle of the instance of the service provider DLL. The handle is typically used to retrieve resources.

lpMalloc

[in] Pointer to a memory allocator object exposing the OLE IMalloc interface. The message service may need to use this allocation method when working with certain interfaces such as IStream.

lpMAPISup

[in] Pointer to an IMAPISupport : IUnknown interface implementation.

ulUIParam

[in] An implementation-specific 32-bit value used for passing user interface information to a function or zero. In applications that run on Microsoft Windows, the ulUIParam parameter is the parent window handle for the configuration dialog box and is of type HWND (cast to a ULONG). A value of zero indicates that there is no parent window.

ulFlags

[in] Bitmask of flags indicating options for the service entry function. 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 service's configuration user interface should display the current configuration but not allow the user to change it.
SERVICE_UI_ALLOWED: Permits a configuration dialog box to be displayed if necessary. When the SERVICE_UI_ALLOWED flag is set, the dialog box should be displayed only if the lpProps property value array is empty or does not contain a valid configuration. If SERVICE_UI_ALLOWED is not set, a dialog box might still be displayed if the UI_SERVICE_ALWAYS flag is set.
UI_CURRENT_PROVIDER_FIRST: Requests that the configuration dialog box for the active provider be displayed on top of other dialog boxes.
UI_SERVICE_ALWAYS: Requires the message service to display a configuration dialog box. If the UI_SERVICE_ALWAYS flag is not set, a configuration dialog box might still be displayed if the SERVICE_UI_ALLOWED flag is set and valid configuration information is not available from the lpProps property value array. Either SERVICE_UI_ALLOWED or UI_SERVICE_ALWAYS must be set to allow a user interface to be displayed.

ulContext

[in] The configuration operation that MAPI is currently performing. The ulContext parameter will contain one of the following values:

MSG_SERVICE_CONFIGURE: Changes to the service's configuration should be made in the profile. If the UI_SERVICE_ALWAYS flag is set, the service should display its configuration dialog box. The dialog box should also be displayed if the SERVICE_UI_ALLOWED flag is set and the lpProps parameter is empty or does not contain valid configuration data. If lpProps contains valid data, no dialog box should be displayed and the service should use this data for making the configuration change.
MSG_SERVICE_CREATE: The service is being added to a profile. If either the UI_SERVICE_ALWAYS or SERVICE_UI_ALLOWED flag is set, the service should display its configuration dialog box. If neither flag is set, the service should fail.
MSG_SERVICE_DELETE: The service is being removed from a profile. After receiving this event, the service should return S_OK.
MSG_SERVICE_INSTALL: The service has been installed to the user's workstation from a network, floppy disk, or other external medium. After receiving this event, the service usually returns S_OK.
MSG_SERVICE_PROVIDER_CREATE: Requests that the service create an additional instance of a provider. If the service supports this operation, it should call IProviderAdmin::CreateProvider. If the service does not support this operation, it can return MAPI_E_NO_SUPPORT.
MSG_SERVICE_PROVIDER_DELETE: Requests that the service delete a provider instance. If the service supports this operation, it should call IProviderAdmin::DeleteProvider. If the service does not support this operation, it can return MAPI_E_NO_SUPPORT.
MSG_SERVICE_UNINSTALL: The service is being removed. After receiving this event, the service can perform any cleanup tasks that should be done before the service ends and then return with a success value. If the user cancels the removal, the service should return MAPI_E_USER_CANCEL.

cValues

[in] Count of property values in the array pointed to by the lpProps parameter. The value of the cValues parameter is zero if MAPI is passing no property values.

lpProps

[in] Pointer to an optional array of SPropValue structures indicating values for provider-supported properties that the function will use in configuring the message service. The function only uses this parameter if the ulContext parameter is set to MSG_SERVICE_CONFIGURE. This parameter is commonly used to pass the path to a file for a file-based service, such as a personal address book service. If the MSG_SERVICE_CONFIGURE flag is not passed in the ulFlags parameter, the lpProps parameter must be zero.

lpProviderAdmin

[in] Pointer to an IProviderAdmin:IUnknown interface that the function can use to locate profile sections for a specific provider in the current message service.

lppMapiError

[out] Pointer to a MAPIERROR structure. The structure is allocated with the MAPIAllocateBuffer function. All members are optional, although most structures will contain a valid error message string in the lpszError member. If the lpszComponent or lpszError members of the structure are present, their memory must eventually be freed by a single call to MAPIFreeBuffer on the base structure.

Return Values

S_OK: The call succeeded and has returned the expected value or values.
MAPI_E_UNCONFIGURED: The service provider has not been configured.
MAPI_E_USER_CANCEL: The user canceled the operation, typically by clicking the Cancel button in a dialog box.
MAPI_E_NO_SUPPORT: The provider either does not support changes to its objects or does not support notification of changes.
MAPI_E_BAD_CHARWIDTH: Either the MAPI_UNICODE flag was set and the implementation does not support Unicode, or MAPI_UNICODE was not set and the implementation only supports Unicode.

Remarks

A function defined using the MSGSERVICEENTRY function prototype enables message services to configure themselves or to perform other service-specific actions. The function primarily furnishes a dialog box in which the user can change settings specific to the message service. It can also support programmatic configuration by using the property value array passed in the lpProps parameter. Programmatic configuration is optional unless the service supports the Profile Wizard, for which it is required.

MAPI calls this entry point from the Control Panel application or in response to a client application calling IMsgServiceAdmin::CreateMsgService or IMsgServiceAdmin::ConfigureMsgService.

MAPI places no restriction on the function name that a message service uses for the MSGSERVICEENTRY prototype but prefers the name ServiceEntry. There is no restriction on the ordinal for the function, and a single provider DLL can contain more than one function. However, only one of the functions can be named ServiceEntry.

MAPI enables a message service to use Windows 95-style property sheets for its configuration dialog boxes. The message service can use the BuildDisplayTable function and the IMAPISupport::DoConfigPropsheet method to simplify configuration dialog box implementation.

It is possible for a user to cancel a MSG_SERVICE_UNINSTALL operation. In this case, the ServiceEntry function should check with the user to verify that the service should not be removed and return MAPI_E_USER_CANCEL if the service remains installed.

A function based on the MSGSERVICEENTRY prototype returns one of the HRESULT values listed. MAPI forwards this value when responding to a client's call to IMsgServiceAdmin::ConfigureMsgService.

Message services that export a service entry function must include the PR_SERVICE_DLL_NAME and PR_SERVICE_ENTRY_NAME properties in the message service section of MAPISVC.INF.