Send UI API: Using the SendUi API

The capabilities required to use the SendUi API are:

LocalServices, NetworkServices, ReadDeviceData, WriteDeviceData, ReadUserData, andWriteUserData.

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
• Creating a message to be sent
• Displaying a list of available messaging services for the user to choose from
• Sending a message using a specified MTM
• Validating a message service
• Launching a messaging editor to allow the user to complete and send a message

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.

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
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 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().

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); 
CleanupStack::PushL(array);
array->AppendL(KSenduiMtmMmsUid);

// 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
CleanupStack::PopAndDestroy(array);

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

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);
CleanupStack::PopAndDestroy(message);

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

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

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.

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