The purpose of the Send UI API is to offer a method to easily create and send messages via available services. These services are device dependant but will normally include, SMS, MMS, Email, Bluetooth and Infrared. In addition to these familiar MTM-based options, services based on the ECom architecture may be also be available and could include sending meeting requests or uploading MMS messages.

The API is aimed at end-user applications as the message creation and sending may require user intervention.

API Description

Send UI API is a library API. It offers a simple way to incorporate messaging functionality into an application. It is not part of the Messaging architecture but provides an interface to available messaging MTMs and appropriate ECom plug-ins.

API Class structure

The main class of the SendUI API is called CSendUi . Each consumer application should create an instance of that class in order to launch the messaging functionality provided through this API. It also defines a class, CMessageData , to encapsulate the message data to be sent, while CMessageAddress encapsulates recipient details.

CServiceInfo encapsulates an ECom sending service, allowing information such as the name of the service and its capabilities to be retrieved.

TSendingCapabilities has public member data members that are used to define the capabilities of a service in terms of message attributes.

The classes of the Send UI API are shown in Figure 1:

Class diagram of the Send UI API

Class diagram of the Send UI API

Related APIs
  • CMessageAddress
  • CMessageData
  • CSendUi
  • CServiceInfo
  • TSendingCapabilities

Using the SendUi API

The capabilities required to use the SendUi API are:

LocalServices , NetworkServices , ReadDeviceData , WriteDeviceData , ReadUserData , and WriteUserData .

In addition, if DRM protected files are being sent via MMS, the DRM capability is required.

The most important Use Cases are described in the sections below:

Creating an instance of CSendUi

CSendUi is the key class in the API and creating an instance of CSendUi is the starting point for most operations.

              // Create an instance of CSendUi
iSendUi = CSendUi::NewL();    

Note that the creation of a CSendUi object is expensive and therefore you should only create the object at the time it is first be used.

Related APIs
  • CSendUi

Creating a message to be sent

The CMessageData class encapsulates message data for use with the sending services accessed through CSendUi . The CMessageData class allows message recipients, subject line, message body text, and attachments attributes to be set. The attributes set depend on the sending service to be used. For example, if a file is to be sent via Infrared, then only the attachment attribute is relevant. For an MMS message, all attributes may be set, although it is not essential that this is the case.

              // Data to be used - this should normally be defined in a resource file
// or created dynamically
_LIT(KAddress, "07738123456");
_LIT(KAlias, "Sam");
_LIT(KBodyData, "This is the message body");
_LIT(KSubject, "This is the subject");
// Create the message data instance
CMessageData* message = CMessageData::NewLC();
// Add an address
// Note, there are also options for the CC address 
// and Bcc adress used in email
message->AppendToAddressL(KAddress, KAlias);
// Add a subject line

// Add the body text
// The preferred method of setting the body text is to add it as an attachment
// It is also possible to use the body text field and that is shown here
// The body text needs to be a rich text object 
// create the formatting and then the rich text object
iParaFormatLayer = CParaFormatLayer::NewL();
iCharFormatLayer = CCharFormatLayer::NewL();
iRichText = CRichText::NewL(iParaFormatLayer, iCharFormatLayer);
// Populate the rich text object with some text
TInt pos = 0; // Insertion position of text will be zero
iRichText->InsertL(pos, KBodyData);

// Set the body text    

To set an address, two descriptor parameters are required. The first represents the actual address and the second an alias that may be displayed by a messaging editor. The CMessageData class stores the address values in a CMessageAddress object. The CMessageData class holds an array of address objects for each type of recipient (To, Cc, Bcc) and the data can be accessed through its getter functions.

Note that CMessageData::SetSubjectL() takes a const TDesC* as a parameter, rather than the more usual const TDesC& .

To use the body text field, you need to create a rich text object. The CMessageData class does not take ownership of the rich text object and therefore once the body text has been set it can be deleted. An alternative, and preferred, method to using the body text function, is to add any message text as an attachment using AppendAttachmentL() or AppendAttachmentHandleL() .

Related APIs
  • AppendAttachmentHandleL()
  • AppendAttachmentL()
  • CMessageAddress
  • CMessageData
  • CMessageData::SetSubjectL()
  • CSendUi

Displaying a list of available messaging services for the user to choose from

Messages can be sent via available MTM or ECom services. In some circumstances, it may be appropriate to allow the user to select the required mechanism. For example, if an application creates an image which can then be sent to a friend, the user could be asked to decide whether to use Infrared, Bluetooth, MMS, email and so on. It is possible to filter the choices offered to the user based on certain criteria and/or preferences.

There are two functions available that offer very similar functionality, CSendUi::ShowSendQueryL() and CSendUi::.ShowTypedQueryL() . The difference between the functions is that ShowTypedQueryL() offers some control over the title of the list dialog displayed to the user to present the choice of services.

Filtering of the options presented to the user is based on:

  • The attributes of the message being sent. If the message to be sent has attributes defined, then the capabilities (defined in TSendingCapabilities::TSendingFlags ) required to send that message are used to filter out unsuitable services.

  • Criteria specified using a TSendingCapabilities object

  • A list of services that should not be offered, specified by their Uid

In the following example, a request is made for services that can support a message with an attachment (using a TSendingCapabilities object) - but not the MMS service.

              // We need to send an attachment
TSendingCapabilities sendingCapabilities;
sendingCapabilities.iFlags = TSendingCapabilities::ESupportsAttachments;

// We're not interested in MMS
CArrayFixFlat<TUid>* array = new (ELeave) CArrayFixFlat<TUid>(1); 

// Show the list of options to the user and save the Uid of the required service
TUid uid = iSendUi->ShowTypedQueryL(CSendUi::ESendMenu, NULL, sendingCapabilities, array);

// clean up

The constant KSenduiMtmMmsUid that is used to signify that MMS should be excluded from the list of display options, is defined in SendUiConsts.h . The constants for defining other MTM and ECom services can be found there too.

The list of services presented to the user will be dependent upon the device being used. Figure 2 shows the list of services available on the emulator. (Note that not all listed services will work on the emulator.)

Send UI Messaging Services available on...

Send UI Messaging Services available on the Emulator

Related APIs
  • CSendUi::.ShowTypedQueryL()
  • CSendUi::ShowSendQueryL()
  • KSenduiMtmMmsUid
  • ShowTypedQueryL()
  • TSendingCapabilities
  • TSendingCapabilities::TSendingFlags

Sending a message using a specified MTM

CSendUi::CreateAndSendMessageL() allows a message created using CMessageData to be sent using a service specified by a TUid . For some services, the messaging sending will require user intervention. For example, the MMS service will launch the MMS editor with the message data loaded but the user will have the opportunity to amend the message and will need to send it using the editor's menu options. The Bluetooth service will search for devices in range and send the message to the selected device; the IR service will just try to send the message immediately.

The CreateAndSendMessageL() function is simple to use. A message ( CMessageData ) can be created using the method shown in Creating a message to be sent and the Uid of the service either selected by the user using the method shown in Displaying a list of available services or chosen from those listed in SendUiConsts.h .

              CMessageData* message = CMessageData::NewLC();
// fill in message details
// Send message using Bluetooth Mtm
iSendUi->CreateAndSendMessageL(KSenduiMtmBtUid, message);

Although CreateAndSendMessageL() takes a CMessageData* , it does not take ownership so the appropriate cleanup should be performed.

Related APIs
  • CMessageData
  • CMessageData*
  • CSendUi::CreateAndSendMessageL()
  • CreateAndSendMessageL()
  • TUid

Validating a message service

Using CSendUi::ValidateServiceL() , it is possible to verify that the selected service can handle the capabilities required for a particular message. In the following example, a check is made to test if the SMS MTM supports the sending of messages with attachments.

              TSendingCapabilities sendingCapabilities;
sendingCapabilities.iFlags = TSendingCapabilities::ESupportsAttachments;

TBool serviceAvailable = iSendUi->ValidateServiceL(KSenduiMtmSmsUid, sendingCapabilities);

_LIT(KSupports, "Supports attachments");
_LIT(KNoSupport, "Does not supports attachments");

CAknInformationNote* note = new (ELeave) CAknInformationNote();
if (serviceAvailable)
else // SMS does not support attachments

This example demonstrates how to use the ValidateServiceL () function using the constant KSenduiMtmSmsUid to define the service. In practice, it is more likely that it would be used to validate a user selected service.

Related APIs
  • ()
  • CSendUi::ValidateServiceL()
  • KSenduiMtmSmsUid
  • ValidateServiceL

Launching a messaging editor to allow the user to complete and send a message

The function CSendUi::ShowQueryAndSendL() combines the functionality of CSendUi::ShowSendQueryL() and CSendUi::CreateAndSendMessageL() . It presents a list of available services to the user (subject to the filtering restrictions specified) and, once a service has been selected, launches the appropriate messaging editor or sends a message as appropriate. Where the messaging editor is launched, for example if the MMS MTM is selected, the user can modify the message and send it using the editor's menu.

              _LIT(KAttachmentPath, "C:\\Data\\Images\\Picture.jpg");

CMessageData* message = CMessageData::NewLC();
// We're sending a picture so we need the service to support attachments
TSendingCapabilities sendingCapabilities;
sendingCapabilities.iFlags = TSendingCapabilities::ESupportsAttachments;
// Add the picture to our message
//Show the user the options and send the message (or launch the editor)
iSendUi->ShowQueryAndSendL(message, sendingCapabilities);  

CSendUi::ShowTypedQueryAndSendL() offers similar functionality to ShowQueryAndSendL() but with more control over the menu title.

Related APIs
  • CSendUi::CreateAndSendMessageL()
  • CSendUi::ShowQueryAndSendL()
  • CSendUi::ShowSendQueryL()
  • CSendUi::ShowTypedQueryAndSendL()
  • ShowQueryAndSendL()
Related APIs
  • DRM
  • LocalServices
  • NetworkServices
  • ReadDeviceData
  • ReadUserData
  • WriteDeviceData
  • WriteUserData




API Application Programming Interface


Epoc Component object model. Symbian framework for plug-in DLLs


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


Multimedia Messaging Service Protocol defined by 3GPP. Messaging for text, images, audio


Short Message Service. A GSM digital mobile phone standard which enables a single short text message up to 160 characters long to be sent to a mobile phone