Abstract

This specification defines a System Level API which offers a
simple interface to get access to mobile messaging services. A
typical use case of the Messaging API is the implementation of
a messaging client application that allows the user to send SMS
and MMS messages as well as to access and manage the received
SMS and MMS messages.

Status of This Document

This section describes the status of this document at
the time of its publication. Other documents may supersede this
document. A list of current W3C publications and the
latest revision of this technical report can be found in the
W3C technical reports
index at http://www.w3.org/TR/.

This document defines a System Level API for access to
mobile messaging services including SMS and MMS messages.
This can be contrasted with the earlier and discontinued draft
messaging
specification for the regular browser context.

Publication as a First Public Working Draft does not imply
endorsement by the W3C
Membership. This is a draft document and may be updated,
replaced or obsoleted by other documents at any time. It is
inappropriate to cite this document as other than work in
progress.

1. Introduction

This section is non-normative.

The Messaging API provides operations to get access to the
primitives offered by mobile messaging services (send, receive)
as well as those that allow to manage a mobile messaging client
inbox (delete, store, mark as read)

2. Conformance

As well as sections marked as non-normative, all authoring
guidelines, diagrams, examples, and notes in this specification
are non-normative. Everything else in this specification is
normative.

The key words MUST,
MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be
interpreted as described in [RFC2119].

This specification defines conformance criteria that apply
to a single product: the user
agent that implements the interfaces that it
contains.

Implementations that use ECMAScript to implement the APIs
defined in this specification MUST implement them in a manner consistent with the
ECMAScript Bindings defined in the Web IDL specification
[WEBIDL],
as this specification uses that specification and
terminology.

3. Terminology

The EventHandler
interface represents a callback used for event handlers as
defined in [HTML5].

6.1 Attributes

6.2 Methods

findMessages

This method makes a request to retrieve the messages
matching the filter described by the filter
parameter and according to the filtering options
described in the options. It returns a new
Future that will be used to notify the
caller about the result of the operation, which is a
MessagingCursor to access the set of messages.

This method makes a request to retrieve the list of
conversations in which the messages can be grouped using
the criteria defined by the groupBy
parameter. Only those messages matching the filter
described in the filter parameter SHALL be included in the
resulting conversations, what can be useful for instance
to filter just a specific type of messages (e.g. SMS) or
to implement message search in a conversational messaging
client. It returns a new Future that will be
used to notify the caller about the result of the
operation, which is a MessagingCursor to access the set
of conversations.

Indicates the criteria used to
define the conversations. It may have the values
'participants' if a conversation is to be defined as
the set of messages exchanged among the same set of
parties, and 'subject' if a conversation is to be
defined as the set of messages with the same
subject.

This method requests the deletion of all the messages in
the conversation with identifier equal to the
conversationID parameter. A new
Future is returned in order to notify the
request result (success or error) to the caller.

This method requests to mark as read or unread the
message with identifier equal to the
messageID parameter. The method returns a
new Future that will allow the caller to be
notified about the result (success, error) of the
operation.

This method requests to mark as read or unread all the
messages in the conversation with identifier equal to the
conversationID parameter. The method returns
a new Future that will allow the caller to
be notified about the result (success, error) of the
operation.

The findConversations
method when invoked MUST run the following steps:

Make a request to the system to get the set of
conversations in which the messages can be grouped,
according to the set of participants or the subject as
indicated in the groupBy parameter, and
filtering the messages included in those conversations
according to the filter included in the filter
parameter and the filtering options described in the
options parameter.

Let future be a new Future
object and resolver its associated
resolver

Return future to the caller.

If an error occurs call
resolver's reject(value)method with
error as value argument.

When the request has been successfully completed:

Let messagingCursor be a new
MessagingCursor object providing access to
the results of the retrieval, i.e. the set of
Conversation elements.

Make a request to the system to mark as read/unread
(depending on the value parameter being
respectively 'true' or 'false') the message with identifier
equal to the messageID parameter passed in the
request.

Let future be a new Future
object and resolver its associated
resolver

Return future to the caller.

If an error occurs call
resolver's reject(value)method with
error as value argument.

When the request has been successfully completed:

Let messageID be the
messageID parameter passed in the
request

Call resolver's
accept(value)method with
messageID as value
argument.

The markConversationRead
method when invoked MUST run the following steps:

Make a request to the system to mark as read/unread
(depending on the value parameter being
respectively 'true' or 'false') the messages in the
conversation with identifier equal to the
conversationID parameter passed in the
request.

Let future be a new Future
object and resolver its associated
resolver

Return future to the caller.

If an error occurs call
resolver's reject(value)method with
error as value argument.

When the request has been successfully completed:

Let conversationID be the
conversationID parameter passed in the
request

Handles the serviceremoved event of type
ServiceChangeEvent, fired when
an existing messaging service is disabled on this
messaging service manager.

7.2 Methods

segmentInfo

This method returns an SmsSegmentInfo object
including information on the number of concatenated SMS
segments needed to send the text in the text
parameter, the number of characters available per segment
and the maximum number of available characters in the
last segment.

This method issues a request to the messaging system to
send an SMS message with the text of the
text parameter to the destination number
indicated in the to parameter. A
Future object will be returned in order to
notify the result of the request.

7.3 Steps

Generate a identifier for this message that is
globally unique within the implementation, i.e. there
cannot be any other message with the same
identifier.

Set the messageID of the
SmsMessage to the generated
identifier.

Set the type of the
SmsMessage to 'sms'.

Set the serviceID of the
SmsMessage to the identifier of the
service used to send the message, i.e. the one passed
in the serviceID parameter, if provided,
or otherwise to the first element in the
serviceIDs attribute of the
SmsManager.

Set the from of the
SmsMessage to the number of the mobile
subscription used to send this SMS message.

Set the read of the
SmsMessage to 'true'.

Set the to of the
SmsMessage to the value of the
to parameter.

Set the body of the
SmsMessage to the value of the
text parameter.

Set the messageClass of the
SmsMessage to 'class1'.

Set the state of the
SmsMessage to 'sending'.

Set the deliveryStatus of the
SmsMessage to 'pending' if a delivery
report has been requested or to 'not-applicable'
otherwise.

Make a request to the system to send an SMS message
with text passed in the text parameter to
the number of the recipient indicated in the
to parameter, using the proper service as
described above.

Let future be a new Future
object and resolver its associated
resolver

Return future to the caller.

If an error occurs run these substeps and
terminate these steps

If a delivery report had been requested set the
deliveryStatus of the
SmsMessage to 'error'.

call resolver's
reject(value)method with error
as value argument.

When the request has been successfully completed:

Set the state of the
SmsMessage to 'sent'.

Set the timestamp of the
SmsMessage to the timestamp when the SMS
message reached the Short Message Center, i.e. the
value of the TP-Service-Centre-Time-Stamp (TP-SCTS)
parameter returned in the SMS-SUBMIT-REPORT Protocol
Data Unit [GSM-SMS].

Call resolver's
accept(value)method with the sent
SmsMessage as value
argument.

The segmentInfo method when
invoked MUST return a
SmsSegmentInfo object that contains the
following elements:

A segments element indicating the number
of concatenated SMS segments needed to send the text passed
in the text parameter using the service with
identifier equal to the one passed in the
serviceID parameter, if provided, or otherwise
to the first element in the serviceIDs
attribute of the SmsManager. Note that the
application SHOULD
NOT split the text in a set of strings that fit each
into a single SMS segment as it would result in different
independent SMS messages being sent, but SHOULD instead send the full
message in a single sendSMS request. However
having information on the number of SMS segments may be
required by the application in order to inform the user
(e.g. in case the length of the text impacts on the price
charged for sending the message).

A charsPerSegment element indicating the
number of characters available per SMS segment. This number
depends on the encoding to be used to send the SMS message,
which in turn depends on the language / special characters
included in the text.

A charsAvailableInLastSegment element
indicating the maximum number of available characters in
the last segment that would be needed to send the input
string. This provides useful information to the user on the
number of characters that can type without requiring an
additional SMS segment to send the text.

Generate a identifier for this message that is globally
unique within the implementation, i.e. there cannot be any
other message with the same identifier.

Set the messageID of the
SmsMessage to the generated identifier.

Set the type of the
SmsMessage to 'sms'.

Set the serviceID of the
SmsMessage to the identifier of the service at
which the message has been received.

Set the from of the
SmsMessage to the sender of the SMS message,
i.e. the value of the TP Originating Address (TP-OA) field
of the SMS message [GSM-SMS].

Set the timestamp of the
SmsMessage to the timestamp of the SMS
message, i.e. the value of the TP-Service-Centre-Time-Stamp
(TP-SCTS) parameter received in the SMS DELIVER Protocol
Data Unit [GSM-SMS].

Set the read of the
SmsMessage to 'false'.

Set the to of the SmsMessage
to the recipient of the SMS message, i.e. the value of the
TP Destination Address (TP-DA) field of the SMS message
[GSM-SMS].

Set the messageClass of the
SmsMessage to the message class indicated in
the TP-Data-Coding-Scheme (TP-DCS) field of the SMS message
[GSM-SMS].

Set the body element to the text of the
received SMS message, i.e. the value of the SM element
contained within the TP User Data (TP-UD) field of the SMS
message [GSM-SMS].

MUST return the
total number of SMS segments needed to send the input
string, taking into account the encoding to be used to send
such message as well as the overhead associated to
concatenated SMS messages.

MUST return the
number of characters available per SMS segment as per the
encoding to be used to send the SMS message. In case the
variable length encoding, the value of this element
MUST be calculated
asumming the minimum length for all the characters.

MUST return the
maximum number of available characters in the last segment
needed to send the input string. In case the variable
length encoding, the value of this element MUST be calculated asumming the
minimum length for all the remaining characters.

Handles the serviceremoved event of type
ServiceChangeEvent, fired when
an existing messaging service is disabled on this
messaging service manager.

9.2 Methods

getFetchMode

This method requests to retrieve the fetch mode
associated to a specific service (the one identified by
the serviceID attribute, if provided, or the
first element in the serviceIDs attribute of
the MmsManager otherwise).

This method issues a request to the messaging system to
set to manual or automatic the MMS
message fetch mode of the specific service, the one
identified by the serviceID attribute, if
provided, or all services otherwise).

This method issues a request to the messaging system to
send an MMS message with the content and recipients
included in the mmsContent parameter. A
Future object will be returned in order to
notify the result of the request.

This method requests to fetch an MMS message with
identifier equal to the indicated in the
messageID parameter from the URL indicated
in the MMS notification. The method returns a new
Future that will allow the caller to be
notified about the result (success, error) of the
operation.

It is FFS whether MMS settings (e.g. fetch mode, creation
mode) needs to be managed through the MmsManager interface.

9.3 Steps

The send method
when invoked MUST run
the following steps:

Create a new instance of MmsMessage and:

Generate a identifier for this message that is
globally unique within the implementation, i.e. there
cannot be any other message with the same
identifier.

Set the messageID of the
MmsMessage to the generated
identifier.

Set the type of the
MmsMessage to 'mms'.

Set the serviceID of the
MmsMessage to the identifier of the
service used to send the message, i.e. the one passed
in the serviceID parameter, if provided,
or otherwise to the first element in the
serviceIDs attribute of the
MmsManager.

Set the from of the
MmsMessage to the number of the mobile
subscription used to send this MMS message.

Set the read of the
MmsMessage to 'true'.

Set the to of the
MmsMessage to the to in the
mmsContent parameter.

Set the cc of the
MmsMessage to the cc array in
the mmsContent parameter.

Set the bcc of the
MmsMessage to the bcc array
in the mmsContent parameter.

Set the subject of the
MmsMessage to the value of the the
subject parameter in
mmsContent.

Set the smil of the
MmsMessage to the value of the the
smil parameter in
mmsContent.

Set the attachments of the
MmsMessage to the value of the the
attachments array in
mmsContent parameter.

Set the state of the
MmsMessage to 'sending'.

Add a new element in the
deliveryStatus array of the
MmsMessage for each of the addresses
included in the to, cc and
bcc parameters, with value 'pending' if a
delivery report has been requested or with value
'not-applicable' otherwise.

Make a request to the system to send an MMS message
with the content passed in the content
parameter to the number(s) of indicated in the
to parameter, using the proper service as
described above.

The reception of an MMS message is a two-step process:
Firstly, an MMS notification encapsulated in a WAP Push OTA
message [OMA-PUSH] is received by the
device. This MMS notification contains limited information
about the MMS message and a URL where the device can retrieve
the full MMS message from. Secondly, the MMS message is
retrieved either automatically, i.e. performed right after
the reception of the MMS notification, or manually, i.e.
invoked manually by the user.

Set the from of the
MmsMessage to the value of the 'From'
field of the MMS notification, if present.

Set the timestamp of the
MmsMessage to the timestamp of the binary
SMS message used to transport the MMS notification,
i.e. the value of the TP-Service-Centre-Time-Stamp
(TP-SCTS) parameter received in the SMS-DELIVER
Protocol Data Unit [GSM-SMS].

Add a new element in the to array of
the MmsMessage for each of recipients in
the 'To' field of the MMS notification [MMS13], if
present.

Add a new element in the cc array of
the MmsMessage for each of recipients in
the 'Cc' field of the MMS notification [MMS13], if
present.

Add a new element in the bcc array of
the MmsMessage for each of recipients in
the 'Bcc' field of the MMS notification
[MMS13], if present.

Set the subject element to the value
of the 'Subject' field of the MMS notification
[MMS13], if present.

Queue a
task to fire a system message named
received of type ReceivedMessage with
the message attribute set to the newly
created MmsMessage instance.

The fetch method
can be invoked to fetch an MMS message that has not been
automatically fetched upon receiving the corresponding MMS
notification due to the fetch mode being manual. When this
method is invoked the User Agent MUST run the following steps:

If the messageID parameter passed in the
request matches with an MMS message that has already been
fetched, or to an SMS message go to next step, otherwise
make a request to the system to fetch the MMS message.

Let future be a new Future
object and resolver its associated
resolver

Return future to the caller.

If an error occurs call
resolver's reject(value)method with
error as value argument.

MUST return an
array with each of the elements indicating the delivery
status to each of the recipients of the message, in order
starting with the recipients in the 'To' field, followed by
those in 'Cc' and ending with those in 'Bcc'.

The Content-ID parameter that MAY be used to refer to the attachment
from the SMIL presentation object as described in
[MMS13] and [MIME-ENC]. At least one of
contentID and contentLocation MUST be specified if the MMS Message contains
an SMIL presentation object.

The Content-Location parameter that MAY be used to refer to the attachment
from the SMIL presentation object as described in
[MMS13] and [MIME-ENC]. At least one of
contentID and contentLocation MUST be specified if the MMS Message contains
an SMIL presentation object. It may also be used as a hint
to define the filename when the attachment is stored at the
file system.

MUST return the
type of conversation, with value 'participants' if the
conversation is defined as the set of messages exchanged
among the same set of parties, and 'subject' if the
conversation is defined as the set of messages with the
same subject.

MUST return an
array containing the participants in the conversation. In
case the conversation is of type 'subject' and there are
messages in the conversation with a different set of
participants then this element MUST return the union of the participants of
all the messages in the conversation.

As soon as the MessagingCursor is accessing an element, it
MUST put its associated
request in the 'processing' readyState, and
set the result to null. Then, the UA MUST fetch the next/previous
element asynchronously. When the element is retrieved, the
associated request's readyState
must be set to 'done' and the result must point to
the cursor. If no element was found, the cursor's
element property must return null.

15.1 Attributes

This property MUST
return the currently accessed element. If the cursor went
past the last element or if it is currently accessing
the next element, it MUST return null.

15.2 Methods

next

When this method is called, the cursor MUST change its internal
state to accessing an element and proceed to
access to the next element.
If this method is called while the cursor is in the
process of accessing an element, the method
MUST throw an
"InvalidStateError" error as defined in
[DOM4].

When this method is called, the cursor MUST change its internal
state to accessing an element and proceed to
access to the previous element.
If this method is called while the cursor is in the
process of accessing an element, the method
MUST throw an
"InvalidStateError" error as defined in
[DOM4].

16.1 Attributes

The DeliveryReport interface represents
a system message related to a delivery report of a sent
message. This event is originated from the system and will
start the application if it is not currently running.

The application that consumes this API MAY set a message handler for the
DeliveryReport system message to listen for when a
system message related to a received delivery report is
fired.

MUST return an
array contining the addresses of the subset of the original
recipients of the message to which this delivery report is
related. As delivery reports related to just part of the
recipients of the MMS message are possible, this array may
not contain the full list of recipients to which the MMS
message was sent. If the delivery report is related to an
SMS message then the array will contain a single element
corresponding to the single recipient of the SMS
message.

MUST return an
array contining the addresses of the subset of the original
recipients of the message to which this delivery report
event is related. As delivery reports related to just part
of the recipients of the MMS message are possible, this
array may not contain the full list of recipients to which
the MMS message was sent. If the delivery report is related
to an SMS message then the array will contain a single
element corresponding to the single recipient of the SMS
message.

20.1 Attributes

The MessagingFilter Dictionary
represents a filter that is used to select a set of messages
(e.g. to be provided upon invoking the
findMessages or the findConversations
method in the Messaging interface).