This API enables third party developers to integrate their MTM based services to Messaging Centre and SendUI API. This document describes the required identifiers and the required resource definition necessary to implement the integration. It is assumed that the reader is familiar with Symbian Messaging Framework and Message Type Modules (MTMs). The intent of this document is not to describe how to create MTMs from scratch.



Classification and release information

This API is an SDK API and was first published in S60 5th Edition.

API description

Developers can extend the messaging capabilities of the platform by implementing MTM services. The purpose of this API is to help developers integrate their MTM services into Messaging Centre and the Send menu provided by SendUI API. This is a framework API.

Use cases

MTM integration

Enabling MTM in Messaging Centre and SendUI

A sending service is installed into the system. The user launches Messaging Centre, and selects "Write Message". A list query containing all suitable installed sending services is shown. See implementation details in sections 1.1 and 1.2 .

Dynamic function filtering in Messaging Centre

A message is selected in Messaging Centre. MTM, owning the selected message, supports different functions based on the context. Messaging Centre inquires available functions from the selected MTM and creates the context sensitive menu accordingly. See section 1.3 for details.

Integrating settings into Messaging Centre

A sending service is installed into the system. The user wants to modify the settings of the service. He selects "Settings" in the options menu of the Messaging Centre main view. A view opens listing all the messaging services that has settings. The user chooses the service. The settings of the service open. See section 1.4 for details.

Dynamic sending service filtering in SendUI

The client application requests to show all sending services that have the predefined sending capability support. SendUI shows a list query containing all suitable sending services. The user has selected content and dynamic filtering is requested from SendUI. SendUI compares the content to the capabilities reported by the sending service. MTM service is shown in the Send menu, if the sending service can send the selected content. See sections 1.5 and 1.6 for details.

API class structure

This API contains only constant definitions. It does not provide any classes.

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 on Symbian 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.

Capability identifiers


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.



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.


Related APIs
  • EFalse
  • ETrue
  • KErrNone
  • KUidMsvMtmQuerySupportEditor
  • KUidMtmQueryCanSendMsg

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.

Constant defined in mtmuidef.hrh.


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

Related APIs
  • CMtmDllInfo::HumanReadableName
  • KMtmUiFunctionSendAs

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.

Activity diagram of creating dynamic MTM...

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.

Activity diagram of selecting MTM custom...

Activity diagram of selecting MTM custom function in Messaging Centre

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

Constants defined in mtud.hrh.


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.


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 =
             functiontext = qtn_my_mtm_info;
             command = KMtmUiFunctionMyMtmCommand;
             flags = EMtudContextSpecific | EMtudAsynchronous;
Related APIs
  • EMtudAsynchronous
  • EMtudContextSpecific
  • InvokeAsyncFunctionL
  • InvokeSyncFunctionL
  • KErrNone
  • KMtmUiFirstFreeMtmSpecificFunction
  • MtmUiData::OperationSupportedL
  • OperationSupportedL
  • command
  • functiontext

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.

  • The user interface of the settings dialog or wizard is based on the dialog architecture (not views).

Related APIs
  • CBaseMtmUi::EditL
  • CBaseMtmUi::InvokeSyncFunctionL(...)
  • InvokeSyncFunctionL()
  • KMtmUiFunctionSettingsWizard
  • KMtmUiMceSettings
  • KSenduiTechnologyMailUid
  • TInt
  • TPckgBuf<TInt>
  • aFunctionId
  • aParameter
  • aSelection
  • functiontext

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.

Inquire service capability support from...

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 .

These constants are defined in mtmuids.h, if not otherwise stated.



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.



The maximum size of the message including attachments and body text.


Stored in iFlags ; bit flag is ESupportsBodyText

Returns KErrNone if body text is supported. Otherwise returns KErrNotSupported .


Stored in iFlags ; bit flag is ESupportsAttachments

Returns KErrNone if attachments are supported. Otherwise returns KErrNotSupported .



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
         case KUidMsvMtmQuerySupportLinks: // flow through
        case KUidMsvMtmQuerySupportEditor:
            aResponse = ETrue;
        case KUidMtmQuerySupportAttachmentsValue:
        case KUidMtmQueryCanSendMsgValue:
            error = KErrNotSupported;
    return error;   
Related APIs
  • ESupportsAttachments
  • ESupportsBodyText
  • ETrue
  • KErrNone
  • KErrNone/EFalse
  • KErrNotSupported
  • KUidMsvMtmQuerySupportLinks
  • KUidMtmQueryMaxBodySize
  • KUidMtmQueryMaxTotalMsgSize
  • KUidMtmQuerySupportAttachments
  • KUidMtmQuerySupportedBody
  • iBodySize
  • iFlags
  • iMessageSize

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.

An activity diagram of registering MTM s...

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.

Activity diagram of sending a message vi...

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

Related APIs
  • AddLinkedAttachmentL
  • CBaseMtmUiData::CanCreateEntry
  • CMessageData
  • EMTudCommandSendAs
  • EditL
  • KUidMsvMtmQuerySupportEditor
  • KUidMtmQueryMaxBodySize
  • KUidMtmQueryMaxTotalMsgSize
  • KUidMtmQuerySupportAttachments
  • KUidMtmQuerySupportedBody

Error handling


Memory overhead


Extensions to the API


Limitations of the API





MTM Message Type Module



API An application programming interface is a source code interface that a programming library provides in order to support requests for services to be made to it.

Messaging Centre

Messaging Centre is an application offering a framework for the present and future messaging applications. It includes for example the local Inbox, the local Outbox, document storing in a Documents folder and access to mailboxes.


Message Type Module; a group of components that together provide message handling for a particular protocol.


The Send UI API interface offers a possibility to launch messaging services for other applications.



Creating Custom Message Type Modules (With Example) v1.0

Introduction To Messaging Applications For C++ Developers v1.1

Symbian OS v9.3 Library.