Send UI API Specification

Contents 1 Overview 1.1 Description 1.2 Use Cases 1.3 Class Structure 2 Using The API 2.1 Creating an instance of CSendUi 2.2 Creating a message to be sent 2.3 Displaying a list of available messaging services for end users to choose from 2.4 Sending a message using a specified MTM 2.5 Validating a message service 2.6 Launching a messaging editor to allow end users to complete and send a message 2.7 Security issues 3 Glossary 3.1 Abbreviations

1 Overview

The Send UI API provides a method to easily create and send messages through available services. These services are device dependant but normally include SMS, MMS, Email, Bluetooth and Infrared. In addition to these MTM-based options, services based on the ECom architecture may also be available and can send meeting requests or upload MMS messages.

API category	public
API type	c++
API libraries	sendui.lib
Location	/sf/mw/messagingmw/msgfw_pub/send_ui_api
Buildfiles	/sf/mw/messagingmw/msgfw_pub/send_ui_api/group/bld.inf

1.1 Description

The Send UI API is a library API. It provides 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.

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

1.2 Use Cases

• Creating an instance of CSendUi
• Creating a message to be sent
• Displaying a list of available messaging services for end users to choose from
• Sending a message using a specified MTM
• Validating a message service
• Launching a messaging editor to allow end users to complete and send a message

1.3 Class Structure

Summary of API classes and header files

Classes	Files

CMessageAddress /epoc32/include/mw/CMessageAddress.h CMessageData /epoc32/include/mw/CMessageData.h CSendUi /epoc32/include/mw/sendui.h CSendingServiceInfo /epoc32/include/mw/CSendingServiceInfo.h TSendingCapabilities /epoc32/include/mw/TSendingCapabilities.h No classes/epoc32/include/mw/SendUiConsts.h, /epoc32/include/mw/SenduiMtmUids.h, /epoc32/include/mw/TSendingCapabilities.inl

• The main class of the SendUI API is called CSendUi . A client application must create an instance of that class in order to launch the messaging functionality provided through this API.
• CMessageData encapsulates the message data to be sent,
• 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.

2 Using The API

2.1 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. Note that the creation of a CSendUi object is expensive. Therefore, you must only create the object when it is used for the first time.

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

2.2 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 are set depending on the sending service to be used. For example, if a file is to be sent through Infrared, only the attachment attribute is relevant. For an MMS message, all attributes may be set.

// Data to be used - this  is normally 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 an email
message->AppendToAddressL(KAddress, KAlias);

// Add a subject line
message->SetSubjectL(&KSubject);

// 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
message->SetBodyTextL(iRichText);

To set an address, two descriptor parameters are required. The first represents the actual address and the second is 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, instead of the 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. Therefore once the body text has been set it can be deleted. An alternative and preferred method to use the body text function is to add any message text as an attachment using AppendAttachmentL() or AppendAttachmentHandleL().

2.3 Displaying a list of available messaging services for end users to choose from

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

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

Filtering of the options presented to end users is based on:

• The attributes of the message being sent. If the message to be sent has attributes defined, 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. They are specified by their UIDs.

In the following example, a request is made for services that can support a message with an attachment (using a TSendingCapabilities object), but not for 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);
CleanupStack::PushL(array);
array->AppendL(KSenduiMtmMmsUid);

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

// clean up
CleanupStack::PopAndDestroy(array);

The KSenduiMtmMmsUid constant that shows that MMS is excluded from the list of display options is defined in SendUiConsts.h. The constants for other MTM and ECom services are also defined in this file.

The list of services presented to end users is dependent on the device being used. The following diagram shows the list of services available on the emulator. Note that not all listed services work on the emulator.

2.4 Sending a message using a specified MTM

CSendUi::CreateAndSendMessageL() allows a message to be created using CMessageData and to be sent using a service specified by a TUid . For some services, messaging sending requires user intervention. For example, the MMS service will launch the MMS editor with the message data loaded, and 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 and the Uid of the service can be selected by the user 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);
CleanupStack::PopAndDestroy(message);

CreateAndSendMessageL() takes a CMessageData* , but it does not take ownership. Therefore, the appropriate cleanup needs to be performed.

2.5 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 sending of messages with attachments. This example also shows how to use the ValidateServiceL() function with the constant KSenduiMtmSmsUid to define the service. In practice, it is more used to validate a user selected service.

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)
    {
    note->ExecuteLD(KSupports);
    }
else // SMS does not support attachments
    {
    note->ExecuteLD(KNoSupport);
    }

2.6 Launching a messaging editor to allow end users 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 end users (based on the specified filtering restrictions). In addition, once a service has been selected, it launches the appropriate messaging editor or sends a message. For example, if the messaging editor is launched and the MMS MTM is selected, end users can modify the message and send it using the editor's menu.

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

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

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

2.7 Security issues

The capabilities required to use the Send UI API are:

• LocalServices
• NetworkServices
• ReadDeviceData
• WriteDeviceData
• ReadUserData
• WriteUserData
• DRM if DRM protected files are sent through MMS.

3 Glossary

3.1 Abbreviations

Abbreviations

API	Application Programming Interface
ECom	Epoc Component object model. Symbian OS framework for plug-in DLLs
MTM	Message Type Module. A group of components that together provide message handling for a particular protocol
MMS	Multimedia Messaging Service Protocol defined by 3GPP. Messaging for text, images and audio
SMS	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
IR	Infrared