Messaging Integration API: Using Messaging Integration API

Messaging Integration API: Using Messaging Integration API

MTM services are integrated into Messaging Centre and SendUI. MTM can be integrated to Message Centre, SendUI or both. For Messaging Centre sending service can implement a context sensitive options for its own message entries.

MTM Service Integration

The S60 platform requests name and feature information from MTM.

Enabling MTM in Messaging Centre and SendUI

An MTM service must have editor support (KUidMsvMtmQuerySupportEditor) in order to be visible in the Messaging Centre. Similarly, an MTM service must support sending (KUidMtmQueryCanSendMsg) in order to be available in the SendUI menu. The support for the features is checked by calling CBaseMtmUiData::QueryCapability with the corresponding capability identifiers. See the following sections for implementation details.

**Table 1:** Capability identifiers
Constant	Explanation	Source
`KUidMtmQueryCanSendMsg`	Returns `KErrNone`, if the MTM can send messages. This must always return KErrNone, if service is to be shown under SendUI menu. This feature has no significance to Messaging Centre.	MTMUids.h
`KUidMsvMtmQuerySupportEditor`	Returns `ETrue`, if the sending service supports editor. Otherwise returns `EFalse`. This must return `ETrue`, if the service is to be shown in the Messaging Centre. Note that SendUI supports also sending services without editor.	ExtendedMTMIDS.hrh

Setting MTM service names

Messaging Centre asks the name of the MTM service from the MTM registry. The name is inquired from the MTM Registry using the function called CMtmDllInfo::HumanReadableName.

SendUI uses the following identifier to resolve the name of the service to be used in the SendUI menu.

**Table 2:** Constant defined in mtmuidef.hrh.
Constant	Explanation
`KMtmUiFunctionSendAs`	Function identifier for sending service name. Defined in MTM functions. Typically name syntax is "via myService".

The MTM service name is defined with an MTM function (MTUD_FUNCTION). The function is defined in the source file of the MTM, e.g. myMtm.rss. See the resource definition example below.

RESOURCE MTUD_FUNCTION_ARRAY r_my_mtm_function_array

    {

    functions =

         {

         ...

         MTUD_FUNCTION 

             {

             functiontext = myapp_query_send_via_my_service;

             command = KMtmUiFunctionSendAs;

              },

         ...

         };

     }

SendUI will search for a function with the above mentioned function identifier. If the function is found the name of the service is taken from the functiontext of the function. If the function is not found the name of the service is asked from the MTM Registry.

Integrating MTM specific functions into Messaging Centre

In the below picture is presented as an activity diagram, how the Messaging Centre utilizes MTM functions. Messaging Centre goes through all the MTM functions (MTUD_FUNCTIONs), checking if the EMtudContextSpecific flag is set. If the flag is set, the selected command and the entry are given as input to MtmUiData::OperationSupportedL which is implemented by the MTM. The OperationSupportedL function returns KErrNone, if the command is supported with the specified entry. Otherwise a resource identifier indicating an error is returned. Any returned error code is ignored by the Messaging Centre. No heavy operations are allowed in OperationSupportedL.

The command item is added to the Messaging Centre Options menu, if the operation is supported or the command is not context specific. The command parameter of MTUD_FUNCTION must be a unique value in the scope of the MTM. Valid values start from KMtmUiFirstFreeMtmSpecificFunction .The name of the menu item is taken from the functiontext parameter of MTUD_FUNCTION.

Figure 1: Activity diagram of creating dynamic MTM custom functions for a message entry in the Messaging Centre

Selecting a message specific custom function is presented in the activity chart below. After a message command has been selected, it is checked if the command is context specific. If it is context specific the selected message is set as the context of the client MTM of the selected service. The method of calling MTM synchronously or asynchronously is determined next. Finally the function is invoked with the command identifier and the selected entry (or entries) as parameters.

Figure 2: Activity diagram of selecting MTM custom function in Messaging Centre

Messaging Centre uses the following constants to resolve sending service capabilities.

**Table 3:** Constants defined in mtud.hrh.
Constant	Explanation
`EMtudAsynchronous`	The flag is set, if the MTM function is asynchronous and `InvokeAsyncFunctionL` can be used. Otherwise the operation is called using `InvokeSyncFunctionL`. Asynchronous operations may be canceled at any time.
`EMtudContextSpecific`	Used in Messaging Centre for enabling and disabling menu content depending on the selected message entry. Messaging Centre provides MTM UI, the selected entry, and function ID. Messaging Centre show the menu option depending on the function outcome.

The required function syntax for setting the sending service features is explained in the example below.

RESOURCE MTUD_FUNCTION_ARRAY r_my_mtm_function_array

    {

    functions =

         {

         ...

         MTUD_FUNCTION 

             {

             functiontext = qtn_my_mtm_info;

             command = KMtmUiFunctionMyMtmCommand;

             flags = EMtudContextSpecific | EMtudAsynchronous;

             },

         ...

         };

     }

Integrating settings into Messaging Centre

Integrating an MTM service to Messaging Centre's settings list

An MTM service can register itself to be shown on Messaging Centre's settings list with an MTM function (MTUD_FUNCTION). The command ID of the function has to be KMtmUiMceSettings (defined in ExtendedMTMIDS.hrh) and its functiontext is used as the service name in the settings list.

When the user selects an MTM service from the list the following steps are performed:

A service entry corresponding to the MTM type is searched.
The service entry is set as the current context of the MTM UI.
CBaseMtmUi::EditL is called.

Note! MTM Services that support service entry creation should not register to be shown on the settings list.

Integrating a mail service to Mail Wizard UI

A mail MTM service can also register itself to be shown in the list of mail protocols in Mail Settings Wizard UI. This can be done with an MTM function with command ID KMtmUiFunctionSettingsWizard (defined in ExtendedMTMIDS.hrh). An MTM service is considered a mail service if its technology type is set to KSenduiTechnologyMailUid (defined in SendUiConsts.h).

When the user selects a protocol from the list CBaseMtmUi::InvokeSyncFunctionL(...) is called for the corresponding MTM. The parameters of the called are described below:

The value of the aFunctionId parameter when the InvokeSyncFunctionL() function of the MTM UI is called to start the external wizard is KMtmUiFunctionSettingsWizard.
The aParameter parameter contains a TInt packaged inside TPckgBuf<TInt>. This parameter is used to decide whether the wizard is completed or whether the focus is retuned back to the protocol selection list. If the value is 1, when InvokeSyncFunctionL() returns, Wizard exits. Otherwise, the focus returns to the protocol selection list.
The aSelection parameter does not carry any information.

Assumptions concerning settings integration

The following assumptions apply to both integration points described above:

The settings dialog or wizard manages the screen while it is active; i.e. S60 does not show any progress or wait note when a settings method is called.
The user interface of the settings dialog or wizard is based on the dialog architecture (not views).

Dynamic sending service filtering in SendUI

Framework inquires support for the specified feature at runtime from the MTM. Default response of MTM is KErrNotSupported. Positive return values indicate a supported feature or attribute of a supported feature. For example the answer to KUidMtmQueryMaxBodySize can be any positive integer value, indicating the maximum message body size. Note, that some features indicate support with return value KErrNone and other with return value ETrue or any positive integer value.

Figure 3: Inquire service capability support from the MTM

SendUI uses the following identifiers to resolve the MTM service attributes at runtime. These flags are defined in mtmuids.h.

**Table 4:** These constants are defined in mtmuids.h, if not otherwise stated.
Constant	Corresponding in TSendingCapabilities class	Explanation
`KUidMtmQueryMaxBodySize`	`iBodySize`	The maximum size of the body text. The size is in bytes. Note that a Unicode character is double as big as UTF-8 character.
`KUidMtmQueryMaxTotalMsgSize`	`iMessageSize`	The maximum size of the message including attachments and body text.
`KUidMtmQuerySupportedBody`	Stored in `iFlags`; bit flag is `ESupportsBodyText`	Returns `KErrNone` if body text is supported. Otherwise returns `KErrNotSupported`.
`KUidMtmQuerySupportAttachments`	Stored in `iFlags`; bit flag is `ESupportsAttachments`	Returns `KErrNone` if attachments are supported. Otherwise returns `KErrNotSupported`.
`KUidMsvMtmQuerySupportLinks`	None	Returns `ETrue` if linked attachments are supported. Otherwise returns `KErrNone/EFalse`. If the sending service supports links, the attachment files are not duplicated to Message Store, but the original files are passed directly to the sending service. This can give performance boost when sending many files or large files, because copying of files is not necessary. SendUI ensures that there is enough free space for the duplicate files on the device before sending file attachments. Message sending fails, if there is not enough free space on the device. However it is not quarantined that a linked attachment file exists till the end of file sending. This can cause unexpected challenges, if file to be sent is removed unexpectedly. Such situation can occur, if the owner of the temporary file application exits before the sending is completed. The sending service must quarantine that all created temporary files have a unique file path. This constant is defined in ExtendedMTMIDS.hrh.

TInt CMyMtmUiData::QueryCapability(

    TUid aFunctionId,

    TInt& aResponse ) const

    {

    TInt error = KErrNone;



    switch ( aFunctionId.iUid )

        {

        // Supported:

        case KUidMtmQueryMaxTotalMsgSizeValue:

            aResponse = KMaxTInt; // In practice this is equal to no limit

            break;

 	      case KUidMsvMtmQuerySupportLinks: // flow through

        case KUidMsvMtmQuerySupportEditor:

            aResponse = ETrue;

            break;

        case KUidMtmQuerySupportAttachmentsValue:

        case KUidMtmQueryCanSendMsgValue:

            break;

        default:

            error = KErrNotSupported;

        }

    return error;   

    }

MTM service handling in SendUI

SendUI maintains a list of available sending services. Section 1.1 covered how to make MTM service visible in SendUI. The purpose of this section is to cover in detail how MTM services are managed in SendUI.

SendUI requests all MTM services from the MTM registry (see the picture below). Each service's message sending capability is inquired. Services which support message sending are taken to closer review. Service name is copied from the function that has EMTudCommandSendAs as command identification. For detailed function syntax, see section 1.2. If MTM functions do not define the service name, the service name is requested from the MTM registry.

Name resolving is followed by service attribute setting. SendUI inquires from MTM's UI data component support for the following features: KUidMtmQueryMaxBodySize, KUidMtmQueryMaxTotalMsgSize, KUidMtmQuerySupportAttachments, KUidMtmQuerySupportedBody and KUidMsvMtmQuerySupportEditor. See section 1.5 for more information about the possible return values for support enquiries.

The final phase of MTM service registration is to find out, if the MTM service requires account to be functional. For instance SMS and MMS do not require accounts in order to be valid. If the MTM service can create a service entry (CBaseMtmUiData::CanCreateEntry), that indicates multiple account support. In that case it is checked, if any existing accounts (service entries) are associated with the MTM service. For example Email service does not show up in SendUI menu until at least one Email account has been defined. MTM services that have associated account(s) and service that do not support accounts are registered by SendUI.

Note, that Messaging Centre does not do this check for MTM services when creating list of available services.

Figure 4: An activity diagram of registering MTM services in SendUI

Sending a message via MTM service

The message is stored in the CMessageData object, which is later referred as the message data. SendUI checks if the selected service can be validated. If validation is supported and service is not valid, a common error note is shown. If service specific error notes are preferred, then the MTM should not support service validation.

A draft entry is created and set as the current entry of the client MTM. The client MTM takes the ownership of the entry. After entry has been created the message data is copied to MTM.

The first stage is to add all recipient addresses to MTM. Next the body text is copied to MTM. If MTM does not support body text, then an attachment file is created from the body text. Name of the attachment file is taken from the first allowed characters of the body text. Filename extension of the attachment is TXT.

This is followed by inserting the attachments to MTM. If MTM supports linked attachment, then the AddLinkedAttachmentL function is used. See section 1.5 for more information about linked attachments. Finally the subject is copied to MTM and MTM's EditL is called. Calling of EditL is a sign for the MTM to e.g. validate its settings, start the editor or begin message sending.

SendUI waits until the asynchronous EditL call completes. Status or success of the sending operation is not available from SendUI.

Figure 5: Activity diagram of sending a message via SendUI when MTM sending service is used.

Error handling

None.

Memory overhead

None.

Extensions to the API

None.

Limitations of the API

None.