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
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()
.
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);
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.)
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);
CleanupStack::PopAndDestroy(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)
{
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.
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
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.
Related APIs
-
CSendUi::CreateAndSendMessageL()
-
CSendUi::ShowQueryAndSendL()
-
CSendUi::ShowSendQueryL()
-
CSendUi::ShowTypedQueryAndSendL()
-
ShowQueryAndSendL()
Related APIs
-
DRM
-
LocalServices
-
NetworkServices
-
ReadDeviceData
-
ReadUserData
-
WriteDeviceData
-
WriteUserData
