Messaging API

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 MAY, MUST, SHALL, SHOULD, and SHOULD NOT 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].

The concepts queue a task and fire an event are defined in [HTML5].

The terms event handler and event handler event types are defined in [HTML5].

The Promise interface, the concepts of a resolver, a resolver's fulfill algorithm and a resolver's reject algorithm are defined in ECMAScript 6 (ECMA-262).

4. Security and privacy considerations

This API must be only exposed to trusted content

5. `Navigator` Interface

partial interface Navigator {
    readonly    attribute Messaging messaging;
};

5.1 Attributes

messaging of type Messaging, readonly: The object that exposes the interface to mobile messaging services.

6. `MessagingManager` Interface

The MessagingManager interface represents the initial entry point for getting access to the mobile messaging services, i.e. SMS and MMS.

interface MessagingManager {
    readonly    attribute SmsManager sms;
    readonly    attribute MmsManager mms;
    Promise findMessages (MessagingFilter filter, FilterOptions options);
    Promise findConversations (DOMString groupBy, MessagingFilter filter, FilterOptions options);
    Promise getMessage (DOMString messageID);
    Promise deleteMessage (DOMString messageID);
    Promise deleteConversation (DOMString conversationID);
    Promise markMessageRead (DOMString messageID, boolean value, optional boolean sendReadReport = false);
    Promise markConversationRead (DOMString conversationID, boolean value, optional boolean sendReadReport = false);
};

6.1 Attributes

sms of type SmsManager, readonly: Provides access to the SMS service's specific functionality.
mms of type MmsManager, readonly: Provides access to the MMS service's specific functionality.

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 Promise that will be used to notify the caller about the result of the operation, which is a MessagingCursor to access the set of messages.

Parameter	Type	Nullable	Optional	Description
filter	`MessagingFilter`	✘	✘	Filter that identifies the set of messages that are requested to be retrieved
options	`FilterOptions`	✘	✘	Indicates the filtering options (i.e. sorting criteria, sorting order, limit of results).

Return type: Promise

findConversations

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 Promise that will be used to notify the caller about the result of the operation, which is a MessagingCursor to access the set of conversations.

Parameter	Type	Nullable	Optional	Description
groupBy	`DOMString`	✘	✘	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.
filter	`MessagingFilter`	✘	✘	Filter that identifies the set of messages that are requested to be included in the resulting conversations.
options	`FilterOptions`	✘	✘	Indicates the filtering options (i.e. sorting criteria, sorting order, limit of results) to be aplied when filtering the messages to be included in each of the resulting conversations.

Return type: Promise

getMessage

This method makes a request to retrieve the message identified by the messageID parameter. It returns a new Promise object which allows the caller to be notified about the result of the operation.

Parameter	Type	Nullable	Optional	Description
messageID	`DOMString`	✘	✘	Identifier of the message that is requested to be retrieved

Return type: Promise

deleteMessage

This method requests the deletion of the message with identifier equal to the messageID parameter. A new Promise is returned in order to notify the request result (success or error) to the caller.

Parameter	Type	Nullable	Optional	Description
messageID	`DOMString`	✘	✘	Identifier of the message that is requested to be deleted

Return type: Promise

deleteConversation

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

Parameter	Type	Nullable	Optional	Description
conversationID	`DOMString`	✘	✘	Identifier of the conversation whose messages are requested to be deleted

Return type: Promise

markMessageRead

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

Parameter	Type	Nullable	Optional	Description
messageID	`DOMString`	✘	✘	Identifier of the message that is requested to be marked as read or unread
value	`boolean`	✘	✘	Indicates whether the message is to be marked as read ('true') or unread ('false')
sendReadReport	`boolean = false`	✘	✔	Indicates that, in case a Read Report was requested, it is to be sent ('true') or not ('false', which is the default)

Return type: Promise

markConversationRead

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 Promise that will allow the caller to be notified about the result (success, error) of the operation.

Parameter	Type	Nullable	Optional	Description
conversationID	`DOMString`	✘	✘	Identifier of the conversation whose messages are requested to be marked as read or unread
value	`boolean`	✘	✘	Indicates whether the messages in the conversation are to be marked as read ('true') or unread ('false')
sendReadReport	`boolean = false`	✘	✔	Indicates that, in case a Read Report was requested for any MMS message in the conversation, a Read Report is to be sent ('true') or not ('false', which is the default)

Return type: Promise

6.3 Steps

The findMessages method when invoked MUST run the following steps:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
Make a request to the system to get the message(s) matching the filter included in the filter parameter and according to the filtering options described in the options parameter.
If an error occurs invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Let messagingCursor be a new MessagingCursor object providing access to the results of the retrieval, i.e. the set of SmsMessage and/or MmsMessage elements.
2. Invoke resolver's fulfill algorithm with messagingCursor as the value argument.

The findConversations method when invoked MUST run the following steps:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
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.
If an error occurs invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Let messagingCursor be a new MessagingCursor object providing access to the results of the retrieval, i.e. the set of Conversation elements.
2. Invoke resolver's fulfill algorithm with messagingCursor as the value argument.

The getMessage method when invoked MUST run the following steps:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
Make a request to the system to get the message with identifier equal to the messageID parameter passed in the request.
If an error occurs invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Let message be the SmsMessage or MmsMessage whose identifier matches the messageID parameter.
2. Invoke resolver's fulfill algorithm with message as the value argument.

The deleteMessage method when invoked MUST run the following steps:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
Make a request to the system to delete the message with identifier equal to the messageID parameter passed in the request.
If an error occurs invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Let messageID be the messageID parameter passed in the request
2. Invoke resolver's fulfill algorithm with messageID as the value argument.

The deleteConversation method when invoked MUST run the following steps:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
Make a request to the system to delete the messages in the conversation with identifier equal to the conversationID parameter passed in the request.
If an error occurs invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Let conversationID be the conversationID parameter passed in the request
2. Invoke resolver's fulfill algorithm with conversationID as the value argument.

The markMessageRead method when invoked MUST run the following steps:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
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, and to send a Read Report if sendReadReport is set to 'true'.
If an error occurs invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Let messageID be the messageID parameter passed in the request
2. Invoke resolver's fulfill algorithm with messageID as the value argument.

The markConversationRead method when invoked MUST run the following steps:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
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, and in case sendReadReport is set to 'true', to send a Read Report for each of the MMS messages for which it was requested.
If an error occurs invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Let conversationID be the conversationID parameter passed in the request
2. Invoke resolver's fulfill algorithm with conversationID as the value argument.

Note

It is FFS whether the methods deleteMessage() and markMessageRead() should also accept an array of message identifiers as input parameter.

7. `SmsManager` Interface

The SmsManager interface represents the SMS messaging service manager.

interface SmsManager : EventTarget {
    readonly    attribute MessageType  type;
    readonly    attribute DOMString[]  serviceIDs;
    Promise segmentInfo (DOMString text, optional DOMString serviceID);
    Promise send (DOMString to, DOMString text, optional DOMString serviceID);
    Promise clear (DOMString serviceID);
                attribute EventHandler onreceived;
                attribute EventHandler onsent;
                attribute EventHandler ondeliverysuccess;
                attribute EventHandler ondeliveryerror;
                attribute EventHandler onserviceadded;
                attribute EventHandler onserviceremoved;
};

7.1 Attributes

type of type MessageType, readonly: MUST return the type of the messaging service manager. It can have the following values: 'sms' or 'mms'.
serviceIDs of type array of DOMString, readonly: MUST return the identifier of the different services for this type of messaging service (e.g. 'sms_sim1').
onreceived of type EventHandler,: Handles the received event of type MessagingEvent, fired when a new message is received on this messaging service manager.
onsent of type EventHandler,: Handles the sent event of type MessagingEvent, fired when a new message is sent using this messaging service manager.
ondeliverysuccess of type EventHandler,: Handles the deliverysuccess event of type DeliveryReportEvent, fired when a new succesful delivery report is received on this messaging service manager.
ondeliveryerror of type EventHandler,: Handles the deliveryerror event of type DeliveryReportEvent, fired when a new failure delivery report is received on this messaging service manager.
onserviceadded of type EventHandler,: Handles the serviceadded event of type ServiceChangeEvent, fired whenever a new messaging service is enabled on this messaging service manager.
onserviceremoved of type EventHandler,: 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 issues a request to get 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. A Promise object will be returned in order to notify the result of the request.

Parameter	Type	Nullable	Optional	Description
text	`DOMString`	✘	✘	Text intended to be sent as an SMS, whose segmentation information is checked by this method.
serviceID	`DOMString`	✘	✔	Identifier of the service through which the message is would be sent.

Return type: Promise

send

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 Promise object will be returned in order to notify the result of the request.

Parameter	Type	Nullable	Optional	Description
to	`DOMString`	✘	✘	Destination number for the SMS message.
text	`DOMString`	✘	✘	Content of the SMS message to be sent.
serviceID	`DOMString`	✘	✔	Identifier of the service through which the message is requested to be sent.

Return type: Promise

clear

This method makes a request to delete all the messages associated to the messaging service passed as parameter.

Parameter	Type	Nullable	Optional	Description
serviceID	`DOMString`	✘	✘	Identifies the messaging service all whose messages are requested to be deleted.

Return type: Promise

7.3 Steps

The send method when invoked MUST run the following steps:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
Let smsMessage be a new instance of SmsMessage:
1. 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.
2. Set the messageID of smsMessage to the generated identifier.
3. Set the type of smsMessage to 'sms'.
4. Set the serviceID of 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 item in the serviceIDs attribute of the SmsManager.
5. Set the from of smsMessage to the number of the mobile subscription used to send this SMS message.
6. Set the read of smsMessage to 'true'.
7. Set the to of smsMessage to the value of the to parameter.
8. Set the body of smsMessage to the value of the text parameter.
9. Set the messageClass of smsMessage to 'class1'.
10. Set the state of smsMessage to 'sending'.
11. Set the deliveryStatus of smsMessage to 'pending' if a delivery report has been requested or to 'not-applicable' otherwise.
12. 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.
13. Queue a task to monitor SMS submission process.
If an error occurs run these substeps and terminate these steps
1. If a delivery report had been requested set the deliveryStatus of smsMessage to 'error'.
2. invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Set the state of smsMessage to 'sent'.
2. Set the timestamp of smsMessage to the device's date when the SMS message was sent, i.e. when the SMS-SUBMIT Protocol Data Unit was sent.
3. Invoke resolver's fulfill algorithm with smsMessage as the value argument.
4. Queue a task to fire an event named sent with the message attribute set to smsMessage.

The segmentInfo method when invoked MUST run the following steps:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
Let smsSegmentInfo be a new instance of SmsSegmentInfo.
Make a request to the system to calculate the segmentation information related to the sending as SMS 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 item in the serviceIDs attribute of the SmsManager.
Queue a task to monitor the calculation process.
If an error occurs run these substeps and terminate these steps
1. invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Set the segments of smsSegmentInfo to the number of concatenated SMS segments needed to send the provided text.
2. Set the charsPerSegment of smsSegmentInfo to 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.
3. Set the charsAvailableInLastSegment of smsSegmentInfo to 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.
4. Invoke resolver's fulfill algorithm with smsSegmentInfo as the value argument.

Note that the application that has invoked the segmentInfo method SHOULD NOT split the text in a set of strings that fit each into a single SMS segment and send each of them by an independent call to the sendSMS method 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).

Upon a new SMS message being received, the user agent MUST:

Let smsMessage be a new instance of SmsMessage.
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 smsMessage to the generated identifier.
Set the type of smsMessage to 'sms'.
Set the serviceID of smsMessage to the identifier of the service at which the message has been received.
Set the from of 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 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 smsMessage to 'false'.
Set the to of 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 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].
Set the state of smsMessage to 'received'.
Set the deliveryStatus of smsMessage to 'not-applicable'.
Queue a task to fire an event named received with the message attribute set to smsMessage.
Queue a task to fire a system message named received of type ReceivedMessage with the message attribute set to smsMessage.

Upon a delivery report of a previously sent SMS message being received, the user agent MUST

Let smsMessage be the instance of SmsMessage to which this delivery report is related.
Set the deliveryStatus parameter of smsMessage to 'success' or 'error' depending on the reported result.
Set the deliveryTimestamp of smsMessage to the delivery time of the SMS message, i.e. the TP-Discharge-Time (TP DT) parameter included in the SMS-STATUS-REPORT Protocol Data Unit [GSM-SMS].
Queue a task to fire an event named deliverysuccess or deliveryerror respectively if the delivery was successfull or not, with
1. the messageID attribute set to the messageID attribute of smsMessage,
2. the serviceID attribute set to the serviceID attribute of smsMessage,
3. the first item in the recipients attribute set to the to attribute of smsMessage, and
4. the first item in the deliveryTimestamps attribute set to delivery time of such message.
Queue a task to fire a system message of type DeliveryReportnamed deliverysuccess or deliveryerror respectively if the delivery was successfull or not, with
1. the messageID attribute set to the messageID attribute of smsMessage,
2. the serviceID attribute set to the serviceID attribute of smsMessage, and
3. the first item in the recipients attribute set to the to attribute of smsMessage.
4. the first item in the deliveryTimestamps attribute set to delivery time of such message.

The clear method when invoked MUST run the following steps:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
Make a request to the system to delete all the messages associated to the messaging service with identifier equal to the serviceID parameter.
If an error occurs invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Let serviceID be the serviceID parameter passed in the request
2. Invoke resolver's fulfill algorithm with serviceID as the value argument.

7.4 Event handlers

The following are the event handlers (and their corresponding event types) that MUST be supported as attributes by the SmsManager object.

event handler	event name	event type	short description
`onreceived`	`received`	`MessagingEvent`	handles received messages
`onsent`	`sent`	`MessagingEvent`	handles sent messages
`ondeliverysuccess`	`deliverysuccess`	`DeliveryReportEvent`	handles successful delivery reports
`ondeliveryerror`	`deliveryerror`	`DeliveryReportEvent`	handles failure delivery reports
`onserviceadded`	`serviceadded`	`ServiceChangeEvent`	handle new messaging services
`onserviceremoved`	`serviceremoved`	`ServiceChangeEvent`	handle disabled messaging services

8. `SmsSegmentInfo` Dictionary

The SmsSegmentInfo dictionary contains information about the segmentation of a given text to be sent as SMS.

dictionary SmsSegmentInfo {
             long segments;
             long charsPerSegment;
             long charsAvailableInLastSegment;
};

8.1 Dictionary `SmsSegmentInfo` Members

segments of type long,: 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.
charsPerSegment of type long,: 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.
charsAvailableInLastSegment of type long,: 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.

9. `MmsManager` Interface

The MmsManager interface represents the MMS messaging service manager.

interface MmsManager : EventTarget {
    readonly    attribute MessageType  type;
    readonly    attribute DOMString[]  serviceIDs;
    FetchMode getFetchMode (optional DOMString serviceID);
    void      setFetchMode (FetchMode fetchMode, optional DOMString serviceID);
    Promise   send (MmsContent mmsContent, optional MmsSendParameters sendParameters);
    Promise   fetch (DOMString messageID);
    Promise   clear (DOMString serviceID);
                attribute EventHandler onreceived;
                attribute EventHandler onsent;
                attribute EventHandler ondeliverysuccess;
                attribute EventHandler ondeliveryerror;
                attribute EventHandler onreadsuccess;
                attribute EventHandler onreaderror;
                attribute EventHandler onserviceadded;
                attribute EventHandler onserviceremoved;
};

9.1 Attributes

type of type MessageType, readonly: MUST return the type of the messaging service manager. It can have the following values: 'sms' or 'mms'.
serviceIDs of type array of DOMString, readonly: MUST return the identifier of the different services for this type of messaging service (e.g. 'sms_sim1').
onreceived of type EventHandler,: Handles the received event of type MessagingEvent, fired when a new message is received on this messaging service manager.
onsent of type EventHandler,: Handles the sent event of type MessagingEvent, fired when a new message is sent using this messaging service manager.
ondeliverysuccess of type EventHandler,: Handles the deliverysuccess event of type DeliveryReportEvent, fired when a new succesful delivery report is received on this messaging service manager.
ondeliveryerror of type EventHandler,: Handles the deliveryerror event of type DeliveryReportEvent, fired when a new failure delivery report is received on this messaging service manager.
onreadsuccess of type EventHandler,: Handles the readsuccess event of type ReadReportEvent, fired when a new succesful read report is received on this messaging service manager.
onreaderror of type EventHandler,: Handles the readerror event of type ReadReportEvent, fired when a new failure read report is received on this messaging service manager.
onserviceadded of type EventHandler,: Handles the serviceadded event of type ServiceChangeEvent, fired whenever a new messaging service is enabled on this messaging service manager.
onserviceremoved of type EventHandler,: 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 parameter, if provided, or the first item in the serviceIDs attribute of the MmsManager otherwise).

Parameter	Type	Nullable	Optional	Description
serviceID	`DOMString`	✘	✔	Identifier of the service whose fetch mode is queried.

Return type: FetchMode

setFetchMode

This method issues a request to the messaging system to set the MMS message fetch mode for the service identified by the serviceID parameter, if provided, or for all services otherwise, to the mode indicated in the fetchMode parameter.

Parameter	Type	Nullable	Optional	Description
fetchMode	`FetchMode`	✘	✘	Fetch mode that is requested to be set for a specific service.
serviceID	`DOMString`	✘	✔	Identifier of the service whose fetch mode is requested to be set.

Return type: void

send

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 Promise object will be returned in order to notify the result of the request.

Parameter	Type	Nullable	Optional	Description
mmsContent	`MmsContent`	✘	✘	Content and recipients of the MMS message to be sent.
sendParameters	`MmsSendParameters`	✘	✔	Set of parameters related to the submission of the message (e.g. request of delivery/read report or not).

Return type: Promise

fetch

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 Promise that will allow the caller to be notified about the result (success, error) of the operation.

Parameter	Type	Nullable	Optional	Description
messageID	`DOMString`	✘	✘	Identifier of the MMS message that is requested to be download.

Return type: Promise

clear

This method makes a request to delete all the messages associated to the messaging service passed as parameter.

Parameter	Type	Nullable	Optional	Description
serviceID	`DOMString`	✘	✘	Identifies the messaging service all whose messages are requested to be deleted.

Return type: Promise

Note

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:

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
Let mmsMessage be a new instance of MmsMessage and:
1. 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.
2. Set the messageID of mmsMessage to the generated identifier.
3. Set the type of mmsMessage to 'mms'.
4. Set the serviceID of mmsMessage to the identifier of the service used to send the message, i.e. the one passed in the serviceID parameter in MmsSendParameters, if provided, or otherwise to the first item in the serviceIDs attribute of the MmsManager.
5. Set the from of mmsMessage to the number of the mobile subscription used to send this MMS message.
6. Set the read of mmsMessage to 'true'.
7. Set the to of mmsMessage to the to in the mmsContent parameter.
8. Set the cc of mmsMessage to the cc array in the mmsContent parameter.
9. Set the bcc of mmsMessage to the bcc array in the mmsContent parameter.
10. Set the subject of mmsMessage to the value of the the subject parameter in mmsContent.
11. Set the smil of mmsMessage to the value of the the smil parameter in mmsContent.
12. Set the attachments of mmsMessage to the value of the the attachments array in mmsContent parameter.
13. Set the state of mmsMessage to 'sending'.
14. Add a new item in the deliveryInfo attribute of mmsMessage for each unique recipient included in the to, cc and bcc parameters (i.e. a single item if the same address has multiple ocurrences across these parameters), with the recipient attribute set to this recipient's address, with the deliveryStatus attribute set to 'pending', if a delivery report has been requested, or 'not-applicable' otherwise and with the readStatus attribute set to 'pending', if a read report has been requested, or 'not-applicable' otherwise.
15. 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 and asking for delivery and/or read report if requested.
16. Queue a task to monitor MMS sending progress.
If an error occurs run these substeps and terminate these steps
1. If a delivery report had been requested set the deliveryStatus attribute of the different items in the deliveryInfo array attribute of mmsMessage to 'error'.
2. invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Set the state of mmsMessage to 'sent'.
2. Set the timestamp of mmsMessage to the device's date when the MMS message was sent, i.e. the date when the M-Send.req Protocol Data Unit was sent by the MMS Client.
3. Invoke resolver's fulfill algorithm with mmsMessage as the value argument.
4. Queue a task to fire an event named sent with the message attribute set to mmsMessage.

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.

Upon a new MMS notification being received, the user agent MUST:

Let mmsMessage be a new instance of MmsMessage.
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 mmsMessage to the generated identifier.
Set the type of mmsMessage to 'mms'.
Set the serviceID of mmsMessage to the identifier of the service at which the message has been received.
Set the read of mmsMessage to 'false'.
if the fetch mode is manual, never or the device is not in the home network and the the fetch mode is automatic-home:
1. Set the from of mmsMessage to the value of the 'From' field of the MMS notification, if present.
2. Set the timestamp of 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].
3. Set the expiry of mmsMessage to the value of the 'X-Mms-Expiry' field of the MMS notification.
4. Add a new item in the to array of mmsMessage for each of recipients in the 'To' field of the MMS notification [MMS13], if present.
5. Add a new item in the cc array of mmsMessage for each of recipients in the 'Cc' field of the MMS notification [MMS13], if present.
6. Add a new item in the bcc array of mmsMessage for each of recipients in the 'Bcc' field of the MMS notification [MMS13], if present.
7. Set the subject attribute to the value of the 'Subject' field of the MMS notification [MMS13], if present.
8. Set the state of mmsMessage to 'not-downloaded'.
if the fetch mode is otherwise automatic or the device is in the home network and the the fetch mode is automatic-home:
1. Make a request to the system to fetch the MMS message from the URL indicated in the X-Mms-Content-Location field of the MMS notification. Once the MMS has been fetched continue with following steps.
2. Run the steps for filling the MmsMessage object with the data contained in the MMS message enclosed in the M-Retrieve.conf Protocol Data Unit.
  1. Set the from of mmsMessage to the value of the 'From' field of the MMS message [MMS13].
  2. Set the timestamp of mmsMessage to the value of the 'Date' field of the MMS message [MMS13].
  3. Add a new item in the to array of mmsMessage for each of recipients in the 'To' field of the MMS message [MMS13], if present.
  4. Add a new item in the cc array of mmsMessage for each of recipients in the 'Cc' field of the MMS message [MMS13], if present.
  5. Add a new item in the bcc array of mmsMessage for each of recipients in the 'Bcc' field of the MMS message [MMS13], if present.
  6. Set the subject attribute to the value of the 'Subject' field of the MMS message [MMS13], if present.
  7. Set the smil attribute to a DOMString containing the SMIL object of the received MMS message [MMS13], if present.
  8. For each of the media files attached to the received MMS message add a new item to the attachments array with:
    1. A new Blob object including the actual content of the attachment and the media type. The charset encoding is indicated as part of the type attribute of the Blob object by means of appending a charset parameter after the media type as explained in [RFC2046], e.g. "text/plain; charset=utf-8".
    2. The contentID attribute filled with the Content-ID used to reference this attachment from the SMIL object in the incoming MMS message [MMS13], if present.
    3. The contentLocation attribute filled with the Content-Location used to reference this attachment from the SMIL object in the incoming MMS message [MMS13], if present.
  9. Set the readReportRequested attribute to 'true' if the 'X-Mms-Read-Report' field is present in the incoming MMS message [MMS13] and has the value 'Yes', and to 'false' otherwise.
3. Set the state of mmsMessage to 'received'.
4. Add a new item in the deliveryInfo array attribute of mmsMessage for each unique recipient included in the 'To', 'Cc' and 'Bcc' fields (i.e. a single item if the same address has multiple ocurrences across these parameters), with the recipient attribute set to this recipient's address and the deliveryStatus attribute set to 'not-applicable'.
Queue a task to fire an event named received with the message attribute set to mmsMessage.
Queue a task to fire a system message named received of type ReceivedMessage with the message attribute set to mmsMessage.

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

Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
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 let mmsMessage the message with messageID attribute equal to the messageID parameter and set the state of mmsMessage to 'fetching' and make a request to the system to fetch the MMS message.
If an error occurs invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Run the steps for filling the MmsMessage object with the data contained in the MMS message.
2. Invoke resolver's fulfill algorithm with mmsMessage as the value argument.

An example of manual fetch of an MMS is provided below:

Example 2

navigator.setMessageHandler ('received', onMessageReceived)
function onMessageReceived(message) {
  if (message.type == 'sms') { window.console.log('SMS Message from ' +
                               message.from + ' received');  } 
  else if (message.type == 'mms') {
	window.console.log('MMS Message from ' + message.from + ' received');  
	if (message.state == 'not-downloaded') { 
		 window.console.log('MMS Message download started');  
		 navigator.messaging.mms.fetch (message.id).done(
			function(message) { window.console.log('MMS Message downloaded!');},
			function(error)   { window.console.error('Error: ' + error);} );
	}
  }
}

Note

It is FFS how to report the progress of the sending and fetching of an MMS message.

Upon a delivery report of a previously sent MMS message being received, the user agent MUST

Let mmsMessage be the instance of MmsMessage to which this delivery report is related.
For each of the items in the deliveryInfo array attribute of mmsMessage whose recipient attribute matches one of the recipients of the MMS to which the delivery report is related,
1. set its deliveryStatus attribute:
  1. to 'success', in case of successful delivery, i.e. if the value of the X-Mms-Status element in the M-Delivery.ind Protocol Data Unit [MMS13] is 'Retrieved', or
  2. to 'error', in case of failed delivery, i.e. if the value of the X-Mms-Status element in the M-Delivery.ind Protocol Data Unit [MMS13] is 'Expired', 'Rejected' or 'Unreachable'.
2. set its deliveryTimestamp attribute to the delivery time, i.e. the 'Date' field in the M-Delivery.ind Protocol Data Unit [MMS13], in case of successful delivery.
Queue a task to fire an event named deliverysuccess or deliveryerror respectively if the delivery was successfull or not, with
1. the messageID attribute set to the messageID attribute of mmsMessage,
2. the serviceID attribute set to the serviceID attribute of mmsMessage,
3. the recipients attribute set to the subset of the original recipients of mmsMessageto which this delivery report is related, and
4. in case of successful delivery, with each of the items in the deliveryTimestamps attribute set to the delivery time of the MMS message to the corresponding recipient, i.e. that in the same position of the recipients array.
Queue a task to fire a system message of type DeliveryReport named deliverysuccess or deliveryerror respectively if the delivery was successfull or not, with
1. the messageID attribute set to the messageID attribute of mmsMessage,
2. the serviceID attribute set to the serviceID attribute of mmsMessage,
3. the recipients attribute set to the subset of the original recipients of mmsMessageto which this delivery report is related, and
4. in case of successful delivery, with each of the items in the deliveryTimestamps attribute set to the delivery time of the MMS message to the corresponding recipient, i.e. that in the same position of the recipients array.

Upon a read report of a previously sent MMS message being received, the user agent MUST

Let mmsMessage be the instance of MmsMessage to which this read report is related.
For each of the items in the deliveryInfo array attribute of mmsMessage whose recipient attribute matches one of the recipients of the MMS to which the read report is related,
1. set its readStatus attribute:
  1. to 'success', in case the message has been read, i.e. if the value of the X-Mms-Read-Status element in the M-Read-Orig.ind Protocol Data Unit [MMS13] is 'Read', or
  2. to 'error', in case the message has been deleted without being read, i.e. if the value of the X-Mms-Status element in the M-Read-Orig.ind Protocol Data Unit [MMS13] is 'Deleted without being read'.
2. set its readTimestamp attribute to the read time, i.e. the 'Date' field in the M-Read-Orig.ind Protocol Data Unit [MMS13], in case the message has been read.
Queue a task to fire an event named readsuccess or readerror respectively if the message has been read or not, with
1. the messageID attribute set to the messageID attribute of mmsMessage,
2. the serviceID attribute set to the serviceID attribute of mmsMessage,
3. the recipients attribute set to the subset of the original recipients of mmsMessageto which this read report is related, and
4. in case the message has been read, with each of the items in the readTimestamps attribute set to the read time of the MMS message by the corresponding recipient, i.e. that in the same position of the recipients array.
Queue a task to fire a system message of type ReadReport named readsuccess or readerror respectively if the message has been read or not, with
1. the messageID attribute set to the messageID attribute of mmsMessage,
2. the serviceID attribute set to the serviceID attribute of mmsMessage,
3. the recipients attribute set to the subset of the original recipients of mmsMessageto which this read report is related, and
4. in case the message has been read, with each of the items in the readTimestamps attribute set to the read time of the MMS message by the corresponding recipient, i.e. that in the same position of the recipients array.

The clear method when invoked MUST run the following steps:

Make a request to the system to delete all the messages associated to the messaging service with identifier equal to the serviceID parameter.
Let promise be a new Promise object and resolver its associated resolver
Return promise to the caller.
If an error occurs invoke resolver's reject algorithm with error as the value argument.
When the request has been successfully completed:
1. Let serviceID be the serviceID parameter passed in the request
2. Invoke resolver's fulfill algorithm with serviceID as the value argument.

9.4 Event handlers

The following are the event handlers (and their corresponding event types) that MUST be supported as attributes by the MmsManager object.

event handler	event name	event type	short description
`onreceived`	`received`	`MessagingEvent`	handles received messages
`onsent`	`sent`	`MessagingEvent`	handles sent messages
`ondeliverysuccess`	`deliverysuccess`	`DeliveryReportEvent`	handles successful delivery reports
`ondeliveryerror`	`deliveryerror`	`DeliveryReportEvent`	handles failure delivery reports
`onreadsuccess`	`readsuccess`	`ReadReportEvent`	handles successful read reports
`onreaderror`	`readerror`	`ReadReportEvent`	handles failure read reports
`onserviceadded`	`serviceadded`	`ServiceChangeEvent`	handle new messaging services
`onserviceremoved`	`serviceremoved`	`ServiceChangeEvent`	handle disabled messaging services

10. `MmsSendParameters` Dictionary

dictionary MmsSendParameters {
             optional DOMString serviceID;
             boolean            requestDeliveryReport;
             boolean            requestReadReport;
};

10.1 Dictionary `MmsSendParameters` Members

serviceID of type optional DOMString,: Identifier of the service through which the message is requested to be sent.
requestDeliveryReport of type boolean,: Flag to indicate whether a delivery report is requested.
requestReadReport of type boolean,: Flag to indicate whether a read report is requested.

11. `SmsMessage` Interface

The SmsMessage interface represents an SMS message as defined in [GSM-SMS]. This interface is not intended to represent binary SMS, which are out of the scope of this API.

interface SmsMessage {
    readonly    attribute DOMString      messageID;
    readonly    attribute MessageType    type;
    readonly    attribute DOMString      serviceID;
    readonly    attribute DOMString      from;
    readonly    attribute Date           timestamp;
    readonly    attribute boolean        read;
    readonly    attribute DOMString      to;
    readonly    attribute DOMString      body;
    readonly    attribute SmsState       state;
    readonly    attribute DeliveryStatus deliveryStatus;
    readonly    attribute Date?          deliveryTimestamp;
    readonly    attribute MessageClass   messageClass;
};

11.1 Attributes

messageID of type DOMString, readonly: MUST return the identifier of the message.
type of type MessageType, readonly: MUST return the type of message, i.e. 'sms'.
serviceID of type DOMString, readonly: MUST return the messaging service id used to send / receive this message.
from of type DOMString, readonly: MUST return the sender of the message, i.e. the TP Originating Address (TP-OA) of the SMS message.
timestamp of type Date, readonly: MUST return, for received messages the time the message reached the Short Message Center, indicated in the TP-Service-Centre-Time-Stamp (TP-SCTS) parameter of the SMS message, and for sent messages the the device's date when the SMS message was sent, i.e. when the SMS-SUBMIT Protocol Data Unit was sent.
read of type boolean, readonly: MUST return 'true' if the message has been marked as read, or 'false' otherwise.
to of type DOMString, readonly: MUST return the recipient of the message, i.e. the TP Destination Address (TP-DA) of the SMS message.
body of type DOMString, readonly: MUST return text of the SMS message, i.e. the SM element contained within the TP User Data (TP-UD) field of the SMS message.
state of type SmsState, readonly: MUST return the status of the SMS message.
deliveryStatus of type DeliveryStatus, readonly: MUST return the delivery status of the SMS message.
deliveryTimestamp of type Date, readonly , nullable: MUST return for sent messages the delivery date as reported in the TP-Discharge-Time (TP DT) parameter included in the SMS-STATUS-REPORT Protocol Data Unit or null if there is no positive knowledge about the delivery of the message. MUST return null for received messages.
messageClass of type MessageClass, readonly: MUST return the SMS message class, according to the value indicated in the TP-Data-Coding-Scheme (TP-DCS) field of the SMS.

12. `MmsMessage` Interface

The MmsMessage interface represents an MMS message, as defined in [MMS13].

interface MmsMessage {
    readonly    attribute DOMString         messageID;
    readonly    attribute MessageType       type;
    readonly    attribute DOMString         serviceID;
    readonly    attribute DOMString         from;
    readonly    attribute Date              timestamp;
    readonly    attribute unsigned long?    expiry;
    readonly    attribute boolean           read;
    readonly    attribute DOMString[]       to;
    readonly    attribute DOMString[]       cc;
    readonly    attribute DOMString[]       bcc;
    readonly    attribute DOMString         subject;
    readonly    attribute DOMString         smil;
    readonly    attribute MmsAttachment[]?  attachments;
    readonly    attribute MmsState          state;
    readonly    attribute MmsDeliveryInfo[] deliveryInfo;
    readonly    attribute boolean?          readReportRequested;
};

12.1 Attributes

messageID of type DOMString, readonly: MUST return the identifier of the message.
type of type MessageType, readonly: MUST return the type of message, i.e. 'mms'.
serviceID of type DOMString, readonly: MUST return the messaging service id used to send / receive this message.
from of type DOMString, readonly: MUST return the sender of the message, i.e. the 'From' field of the MMS message.
timestamp of type Date, readonly: MUST return, for received messages the time the message reached the Multimedia Messaging Service Center, i.e. the 'Date' field of the MMS message, for received but not downloaded messages the timestamp of the binary SMS message used to transport the MMS notification and for sent messages the device's date when the MMS message was sent, i.e. the date when the M-Send.req Protocol Data Unit was sent by the MMS Client.
expiry of type unsigned long, readonly , nullable: MUST return the number of seconds the message will be stored in the Multimedia Messaging Service Center and thus available for download. This time is calculated since the date the MMS Notification was sent.
read of type boolean, readonly: MUST return 'true' if the message has been marked as read, or 'false' otherwise.
to of type array of DOMString, readonly: MUST return an array containing the recipient(s) included in the 'To' field of the MMS message.
cc of type array of DOMString, readonly: MUST return an array containing the recipient(s) included in the 'Cc' field of the MMS message.
bcc of type array of DOMString, readonly: MUST return an array containing the recipient(s) included in the 'Bcc' field of the MMS message.
subject of type DOMString, readonly: MUST return the subject of the MMS message, corresponding to the 'Subject' field of the MMS message.
smil of type DOMString, readonly: MUST return the SMIL, i.e. the presentation element, unparsed as DOMString, that the messaging client needs to use to determine the way the content of the MMS message is displayed.
attachments of type array of MmsAttachment, readonly , nullable: MUST return the set of attachments of the MMS message.
state of type MmsState, readonly: MUST return the status of the MMS message.
deliveryInfo of type array of MmsDeliveryInfo, readonly: MUST return an array with each of the items indicating the delivery status and, if applicable, the delivery time to each of the recipients of the message.
readReportRequested of type boolean, readonly , nullable: MUST return true in case the originator of a received message requested a read report and false otherwise. MUST return null for sent messages.

13. `MmsContent` Dictionary

dictionary MmsContent {
             DOMString       subject;
             DOMString[]     to;
             DOMString[]     cc;
             DOMString[]     bcc;
             DOMString       smil;
             MmsAttachment[] attachments;
};

13.1 Dictionary `MmsContent` Members

subject of type DOMString,: Indicates the subject of the MMS message, corresponding to the 'Subject' field of the MMS message.
to of type array of DOMString,: Indicates the recipient(s) included in the 'To' field of the MMS message. There MUST be at least one recipient in any of the to, cc or bcc attributes.
cc of type array of DOMString,: Indicates the recipient(s) included in the 'Cc' field of the MMS message. There MUST be at least one recipient in any of the to, cc or bcc attributes.
bcc of type array of DOMString,: Indicates the recipient(s) included in the 'Bcc' field of the MMS message. There MUST be at least one recipient in any of the to, cc or bcc attributes.
smil of type DOMString,: Contains the SMIL component, i.e. the presentation element that determines the way the content of the MMS message MUST be displayed.
attachments of type array of MmsAttachment,: Contains the set of attachments of the MMS message.

14. `MmsAttachment` Dictionary

dictionary MmsAttachment {
             DOMString contentID;
             DOMString contentLocation;
             Blob      content;
};

14.1 Dictionary `MmsAttachment` Members

contentID of type DOMString,: 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.
contentLocation of type DOMString,: 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.
content of type Blob,: The Blob object containing the media type and the content of the attachment.

15. `MmsDeliveryInfo` Dictionary

dictionary MmsDeliveryInfo {
             DOMString      recipient;
             DeliveryStatus deliveryStatus;
             Date           deliveryTimestamp;
             ReadStatus     readStatus;
             Date           readTimestamp;
};

15.1 Dictionary `MmsDeliveryInfo` Members

recipient of type DOMString,: The recipient of the MMS to which the delivery status is related.
deliveryStatus of type DeliveryStatus,: The delivery status of the MMS message to a specific recipient.
deliveryTimestamp of type Date,: The time the message was delivered to the recipient, i.e. the 'Date' field in the M-Delivery.ind Protocol Data Unit [MMS13]. It is not provided if there is no positive knowledge about the delivery of the message.
readStatus of type ReadStatus,: The read status of the MMS message to a specific recipient.
readTimestamp of type Date,: The time the message was read by the recipient, i.e. the 'Date' field in the M-Read-Orig.ind Protocol Data Unit [MMS13]. It is not provided if there is no positive knowledge about the delivery of the message.

16. `Conversation` Interface

The Conversation interface represents a set of messages that are grouped together either because they are exchanged among the same set of participants or because they have the same subject.

interface Conversation {
    readonly    attribute DOMString     conversationID;
    readonly    attribute MessageType   type;
    readonly    attribute DOMString[]   participants;
    readonly    attribute DOMString     subject;
    readonly    attribute DOMString[]   messageTypes;
    readonly    attribute unsigned long messageCount;
    readonly    attribute unsigned long unreadCount;
    readonly    attribute DOMString     lastMessageID;
    readonly    attribute MessageCursor cursor;
};

16.1 Attributes

conversationID of type DOMString, readonly: MUST return the identifier of the conversation, which is globally unique within the implementation, i.e. there cannot be any other conversation with the same identifier.
type of type MessageType, readonly: 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.
participants of type array of DOMString, readonly: 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 attribute MUST return the union of the participants of all the messages in the conversation.
subject of type DOMString, readonly: MUST return the subject of the conversation, if there is a single one.
messageTypes of type array of DOMString, readonly: MUST return an array contining the different types of messages included in the conversation.
messageCount of type unsigned long, readonly: MUST return the number of messages in the conversation.
unreadCount of type unsigned long, readonly: MUST return the number of unread messages in the conversation.
lastMessageID of type DOMString, readonly: MUST return the identifier of the message in the conversation with the most recent timestamp.
cursor of type MessageCursor, readonly: MUST return the MessageCursor to access the messages in this conversation.

17. `MessagingCursor` Interface

The MessagingCursor interface allows to iterate through a list of Conversation elements or of messages (SmsMessage and/or MmsMessage elements).

A MessagingCursor always has, an associated request which is the Promise that created it.

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.

interface MessagingCursor {
    readonly    attribute any? element;
    void next ();
    void previous ();
};

17.1 Attributes

element of type any, readonly , nullable: 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.

17.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].
No parameters.
Return type: void
previous: 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].
No parameters.
Return type: void

18. `ReceivedMessage` Interface

The ReceivedMessage interface represents a system message related to a received 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 SHOULD set a message handler for the ReceivedMessage system message to listen for when a system message related to a received message is fired.

interface ReceivedMessage {
    readonly    attribute (SmsMessage or MmsMessage) message;
};

18.1 Attributes

message of type (SmsMessage or MmsMessage), readonly: MUST return the SmsMessage or MmsMessage object to which this system message is related.

19. `DeliveryReport` Interface

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.

interface DeliveryReport {
    readonly    attribute DOMString   serviceID;
    readonly    attribute DOMString   messageID;
    readonly    attribute DOMString[] recipients;
    readonly    attribute Date[]?     deliveryTimestamps;
};

19.1 Attributes

serviceID of type DOMString, readonly: MUST return the identifier of the service used to send the message to which this delivery report is related.
messageID of type DOMString, readonly: MUST return the identifier of the message to which this delivery report is related.
recipients of type array of DOMString, readonly: MUST return an array containing 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 item corresponding to the single recipient of the SMS message.
deliveryTimestamps of type array of Date, readonly , nullable: MUST return an array containing the delivery dates for each of the recipients to which this delivery report event relates. Each element in the array refers to the recipient in the same position of the recipients array. It MUST return null if case of delivery failure (e.g. message expired)

20. `ReadReport` Interface

The ReadReport interface represents a system message related to a read report of a sent MMS 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 ReadReport system message to listen for when a system message related to a received read report is fired.

interface ReadReport {
    readonly    attribute DOMString   serviceID;
    readonly    attribute DOMString   messageID;
    readonly    attribute DOMString[] recipients;
    readonly    attribute Date[]?     readTimestamps;
};

20.1 Attributes

serviceID of type DOMString, readonly: MUST return the identifier of the service used to send the message to which this read report is related.
messageID of type DOMString, readonly: MUST return the identifier of the message to which this read report is related.
recipients of type array of DOMString, readonly: MUST return an array containing the addresses of the subset of the original recipients of the message to which this read report is related. As read 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.
readTimestamps of type array of Date, readonly , nullable: MUST return an array containing the read dates by each of the recipients to which this read report event relates. Each element in the array refers to the recipient in the same position of the recipients array.

21. `MessagingEvent` Interface

The MessagingEvent interface represents events related to a message sent or received.

interface MessagingEvent {
    readonly    attribute (SmsMessage or MmsMessage) message;
};

21.1 Attributes

message of type (SmsMessage or MmsMessage), readonly: MUST return the SmsMessage or MmsMessage object to which this event is related.

22. `DeliveryReportEvent` Interface

The DeliveryReportEvent interface represents events related to a delivery report of a sent message.

interface DeliveryReportEvent : Event {
    readonly    attribute DOMString   serviceID;
    readonly    attribute DOMString   messageID;
    readonly    attribute DOMString[] recipients;
    readonly    attribute Date[]?     deliveryTimestamps;
};

22.1 Attributes

serviceID of type DOMString, readonly: MUST return the identifier of the service used to send the message to which this delivery report event is related.
messageID of type DOMString, readonly: MUST return the identifier of the message to which this delivery report event is related.
recipients of type array of DOMString, readonly: MUST return an array containing 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 item corresponding to the single recipient of the SMS message.
deliveryTimestamps of type array of Date, readonly , nullable: MUST return an array containing the delivery dates for each of the recipients to which this delivery report event relates. Each element in the array refers to the recipient in the same position of the recipients array. It MUST return null if case of delivery failure (e.g. message expired)

23. `ReadReportEvent` Interface

The ReadReportEvent interface represents events related to a read report of a sent message.

interface ReadReportEvent : Event {
    readonly    attribute DOMString   serviceID;
    readonly    attribute DOMString   messageID;
    readonly    attribute DOMString[] recipients;
    readonly    attribute Date[]?     readTimestamps;
};

23.1 Attributes

serviceID of type DOMString, readonly: MUST return the identifier of the service used to send the message to which this read report event is related.
messageID of type DOMString, readonly: MUST return the identifier of the message to which this read report event is related.
recipients of type array of DOMString, readonly: MUST return an array containing the addresses of the subset of the original recipients of the message to which this read report event is related. As read 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.
readTimestamps of type array of Date, readonly , nullable: MUST return an array containing the read dates for each of the recipients to which this read report event relates. Each element in the array refers to the recipient in the same position of the recipients array.

24. `ServiceChangeEvent` Interface

The ServiceChangeEvent interface represents events related to messaging services enabled or disabled.

interface ServiceChangeEvent : Event {
    readonly    attribute DOMString serviceID;
};

24.1 Attributes

serviceID of type DOMString, readonly: MUST return the identifier of the messaging service which is enabled or disabled.

25. `MessagingFilter` Dictionary

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

dictionary MessagingFilter {
             MessageType            type;
             Date                   startDate;
             Date                   endDate;
             DOMString              from;
             sequence<DOMString>    recipients;
             (SmsState or MmsState) state;
             DOMString              serviceID;
             boolean                read;
};

25.1 Dictionary `MessagingFilter` Members

type of type MessageType,: Indicates whether just the SMS or MMS messages are to be provided in the results of this filter, respectively if it is set to string value 'SMS' or 'MMS'.
startDate of type Date,: Indicates that messages with timestamp previous to this date will not be provided in the results of this filter.
endDate of type Date,: Indicates that messages with timestamp after this date will not be provided in the results of this filter.
from of type DOMString,: Indicates that just messages sent from this number are to be provided in the results of this filter.
recipients of type sequence<DOMString>,: Indicates that just messages sent to one of these numbers are to be provided in the results of this filter.
state of type (SmsState or MmsState),: Indicates whether the results of this filter just needs to return the messages matching the indicated state.
serviceID of type DOMString,: Indicates that just messages associated to the messaging service with this identifier are to be provided in the results of this filter.
read of type boolean,: Indicates whether just read or unread messages are to be provided in the results of this filter, respectively if it is set to 'true' or 'false'.

dictionary FilterOptions {
             DOMString     sortBy;
             DOMString     sortOrder;
             unsigned long limit;
};

27. Enumerations

The attibute type can have the following values:

enum MessageType {
    "sms",
    "mms"
};

Enumeration description
`sms`	Corresponding to SMS message(s).
`mms`	Corresponding to MMS message(s).

The attibute messageClass in an SmsMessage can have the following values:

enum MessageClass {
    "class-0",
    "class-1",
    "class-2",
    "class-3",
    "normal"
};

Enumeration description
`class-0`	The message is of class 0.
`class-1`	The message is of class 1.
`class-2`	The message is of class 2.
`class-3`	The message is of class 3.
`normal`	The message is of class 1 (same as 'class-1').

The attibute state in an SmsMessage can have the following values:

enum SmsState {
    "received",
    "sending",
    "sent",
    "failed"
};

Enumeration description
`received`	The message is an inbound message.
`sending`	The message is in process of being sent.
`sent`	The message has been successfully sent.
`failed`	The message is an outbound message whose submission has failed.

The attibute state in an MmsMessage can have the following values:

enum MmsState {
    "not-downloaded",
    "fetching",
    "received",
    "sending",
    "sent",
    "failed"
};

Enumeration description
`not-downloaded`	The message is an inbound message, for which an MMS notification has been received but that has not yet been downloaded.
`fetching`	The message is an inbound message, for which an MMS notification has been received, and whose download has started and not yet finished.
`received`	The message is an inbound message.
`sending`	The message is in process of being sent.
`sent`	The message has been successfully sent.
`failed`	The message is an outbound message whose submission has failed.

The attibute deliveryStatus can have the following values:

enum DeliveryStatus {
    "success",
    "pending",
    "error",
    "not-applicable"
};

Enumeration description
`success`	The message has been succesfully delivered to the recipient.
`pending`	The message is pending delivery.
`error`	The delivery of the message has failed.
`not-applicable`	The delivery status is not applicable either because a delivery report has not been requested or because the message is an inbound message

The attibute readStatus can have the following values:

enum ReadStatus {
    "success",
    "pending",
    "error",
    "not-applicable"
};

Enumeration description
`success`	The message has been read by the recipient.
`pending`	There is no positive knowledge that the message has been read by the recipient.
`error`	The delivery of the message has failed.
`not-applicable`	The read status is not applicable either because a read report has not been requested or because the message is an inbound message

The MMS fetch mode can have the following values:

enum FetchMode {
    "automatic",
    "automatic-home",
    "manual",
    "never"
};

Enumeration description
`automatic`	MMS message is fecthed right after the reception of the MMS notification.
`automatic-home`	MMS message is fecthed right after the reception of the MMS notification if the device is located in the home network, i.e. not roaming, otherwise the message will be fetched upon the device entering in the home network again or the user manually requesting it.
`manual`	The message is not fecthed until the user manually requests it.
`never`	MMS message retrieval is completely disabled.

28. Acknowledgements

The editors would like to express their gratitude to the Mozilla B2G Team and specially to Jonas Sicking, Mounir Lamouri and Vicamo Yang for their technical guidance, implementation work and support.

A.1 Normative references

[DOM4]: Anne van Kesteren; Aryeh Gregor; Ms2ger; Alex Russell; Robin Berjon. W3C DOM4. 28 April 2015. W3C Last Call Working Draft. URL: http://www.w3.org/TR/dom/
[GSM-SMS]: Richard Burbidge. Technical realization of the Short Message Service (SMS). URL: http://www.3gpp.org/ftp/Specs/html-info/23040.htm
[HTML5]: Ian Hickson; Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 28 October 2014. W3C Recommendation. URL: http://www.w3.org/TR/html5/
[MIME-ENC]: J. Palme; A. Hopmann; N. Shelness. MIME Encapsulation of Aggregate Documents, such as HTML (MHTML). March 1999. Proposed Standard. URL: https://tools.ietf.org/html/rfc2557
[MMS13]: Multimedia Messaging Service 1.3. 13 September 2011. Approved Enabler Release. URL: http://technical.openmobilealliance.org/Technical/release_program/mms_v1_3.aspx
[RFC2046]: N. Freed; N. Borenstein. Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. November 1996. Draft Standard. URL: https://tools.ietf.org/html/rfc2046
[RFC2119]: S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]: Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/

A.2 Informative references

[OMA-PUSH]: Open Mobile Alliance. OMA Push Version 2.3. URL: http://www.openmobilealliance.org/Technical/release_program/push_v2_3.aspx

Abstract

Status of This Document

Table of Contents

1. Introduction

2. Conformance

3. Terminology

4. Security and privacy considerations

5. Navigator Interface

5.1 Attributes

6. MessagingManager Interface

6.1 Attributes

6.2 Methods

6.3 Steps

7. SmsManager Interface

7.1 Attributes

7.2 Methods

7.3 Steps

7.4 Event handlers

8. SmsSegmentInfo Dictionary

8.1 Dictionary SmsSegmentInfo Members

9. MmsManager Interface

9.1 Attributes

9.2 Methods

9.3 Steps

9.4 Event handlers

10. MmsSendParameters Dictionary

10.1 Dictionary MmsSendParameters Members

11. SmsMessage Interface

11.1 Attributes

12. MmsMessage Interface

12.1 Attributes

13. MmsContent Dictionary

13.1 Dictionary MmsContent Members

14. MmsAttachment Dictionary

14.1 Dictionary MmsAttachment Members

15. MmsDeliveryInfo Dictionary

15.1 Dictionary MmsDeliveryInfo Members

16. Conversation Interface

16.1 Attributes

17. MessagingCursor Interface

17.1 Attributes

17.2 Methods

18. ReceivedMessage Interface

18.1 Attributes

19. DeliveryReport Interface

19.1 Attributes

20. ReadReport Interface

20.1 Attributes

21. MessagingEvent Interface

21.1 Attributes

22. DeliveryReportEvent Interface

22.1 Attributes

23. ReadReportEvent Interface

23.1 Attributes

24. ServiceChangeEvent Interface

24.1 Attributes

25. MessagingFilter Dictionary

25.1 Dictionary MessagingFilter Members

26. FilterOptions Dictionary

26.1 Dictionary FilterOptions Members

27. Enumerations

28. Acknowledgements

A. References

A.1 Normative references

A.2 Informative references

5. `Navigator` Interface

6. `MessagingManager` Interface

7. `SmsManager` Interface

8. `SmsSegmentInfo` Dictionary

8.1 Dictionary `SmsSegmentInfo` Members

9. `MmsManager` Interface

10. `MmsSendParameters` Dictionary

10.1 Dictionary `MmsSendParameters` Members

11. `SmsMessage` Interface

12. `MmsMessage` Interface

13. `MmsContent` Dictionary

13.1 Dictionary `MmsContent` Members

14. `MmsAttachment` Dictionary

14.1 Dictionary `MmsAttachment` Members

15. `MmsDeliveryInfo` Dictionary

15.1 Dictionary `MmsDeliveryInfo` Members

16. `Conversation` Interface

17. `MessagingCursor` Interface

18. `ReceivedMessage` Interface

19. `DeliveryReport` Interface

20. `ReadReport` Interface

21. `MessagingEvent` Interface

22. `DeliveryReportEvent` Interface

23. `ReadReportEvent` Interface

24. `ServiceChangeEvent` Interface

25. `MessagingFilter` Dictionary

25.1 Dictionary `MessagingFilter` Members

26. `FilterOptions` Dictionary

26.1 Dictionary `FilterOptions` Members