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.

Introduction

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)

An example of use is provided below:

navigator.messaging.sms.send ( '+1234567890', 'How are you?').then(
  function(message) { window.console.log('Message with identifier  ' +
                      message.messageID + ' sent at ' + message.timestamp); },
  function(error) {   window.console.error('Error: ' + error); } )
  

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.

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 [[DOM4]].

Security and privacy considerations

This API must be only exposed to trusted content

Navigator Interface

readonly attribute Messaging messaging
The object that exposes the interface to mobile messaging services.

MessagingManager Interface

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

readonly attribute SmsManager sms
Provides access to the SMS service's specific functionality.
readonly attribute MmsManager mms
Provides access to the MMS service's specific functionality.
Promise 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.
MessagingFilter filter
Filter that identifies the set of messages that are requested to be retrieved
FilterOptions options
Indicates the filtering options (i.e. sorting criteria, sorting order, limit of results).
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.
DOMString groupBy
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.
MessagingFilter filter
Filter that identifies the set of messages that are requested to be included in the resulting conversations.
FilterOptions options
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.
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.
DOMString messageID
Identifier of the message that is requested to be retrieved
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.
DOMString messageID
Identifier of the message that is requested to be deleted
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.
DOMString conversationID
Identifier of the conversation whose messages are requested to be deleted
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.
DOMString messageID
Identifier of the message that is requested to be marked as read or unread
boolean value
Indicates whether the message is to be marked as read ('true') or unread ('false')
optional boolean sendReadReport = false
Indicates that, in case a Read Report was requested, it is to be sent ('true') or not ('false', which is the default)
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.
DOMString conversationID
Identifier of the conversation whose messages are requested to be marked as read or unread
boolean value
Indicates whether the messages in the conversation are to be marked as read ('true') or unread ('false')
optional boolean sendReadReport = 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)

Steps

The findMessages method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. 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.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. 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:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. 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.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. 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:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to get the message with identifier equal to the messageID parameter passed in the request.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. 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:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to delete the message with identifier equal to the messageID parameter passed in the request.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. 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:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to delete the messages in the conversation with identifier equal to the conversationID parameter passed in the request.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. 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:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. 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'.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. 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:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. 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.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. 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.
It is FFS whether the methods deleteMessage() and markMessageRead() should also accept an array of message identifiers as input parameter.

SmsManager Interface

The SmsManager interface represents the SMS messaging service manager.

readonly attribute MessageType type
MUST return the type of the messaging service manager. It can have the following values: 'sms' or 'mms'.
readonly attribute DOMString[] serviceIDs
MUST return the identifier of the different services for this type of messaging service (e.g. 'sms_sim1').
Promise 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.
DOMString text
Text intended to be sent as an SMS, whose segmentation information is checked by this method.
optional DOMString serviceID
Identifier of the service through which the message is would be sent.
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.
DOMString to
Destination number for the SMS message.
DOMString text
Content of the SMS message to be sent.
optional DOMString serviceID
Identifier of the service through which the message is requested to be sent.
Promise clear ()
This method makes a request to delete all the messages associated to the messaging service passed as parameter.
DOMString serviceID
Identifies the messaging service all whose messages are requested to be deleted.
attribute EventHandler onreceived
Handles the received event of type MessagingEvent, fired when a new message is received on this messaging service manager.
attribute EventHandler onsent
Handles the sent event of type MessagingEvent, fired when a new message is sent using this messaging service manager.
attribute EventHandler ondeliverysuccess
Handles the deliverysuccess event of type DeliveryReportEvent, fired when a new succesful delivery report is received on this messaging service manager.
attribute EventHandler ondeliveryerror
Handles the deliveryerror event of type DeliveryReportEvent, fired when a new failure delivery report is received on this messaging service manager.
attribute EventHandler onserviceadded
Handles the serviceadded event of type ServiceChangeEvent, fired whenever a new messaging service is enabled on this messaging service manager.
attribute EventHandler onserviceremoved
Handles the serviceremoved event of type ServiceChangeEvent, fired when an existing messaging service is disabled on this messaging service manager.

Steps

The send method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. 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.
  4. 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.
  5. 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:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Let smsSegmentInfo be a new instance of SmsSegmentInfo.
  4. 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.
  5. Queue a task to monitor the calculation process.
  6. If an error occurs run these substeps and terminate these steps
    1. invoke resolver's reject algorithm with error as the value argument.
  7. 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:

  1. Let smsMessage be a new instance of SmsMessage.
  2. 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.
  3. Set the messageID of smsMessage to the generated identifier.
  4. Set the type of smsMessage to 'sms'.
  5. Set the serviceID of smsMessage to the identifier of the service at which the message has been received.
  6. 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]].
  7. 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]].
  8. Set the read of smsMessage to 'false'.
  9. 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]].
  10. 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]].
  11. 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]].
  12. Set the state of smsMessage to 'received'.
  13. Set the deliveryStatus of smsMessage to 'not-applicable'.
  14. Queue a task to fire an event named received with the message attribute set to smsMessage.
  15. 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

  1. Let smsMessage be the instance of SmsMessage to which this delivery report is related.
  2. Set the deliveryStatus parameter of smsMessage to 'success' or 'error' depending on the reported result.
  3. 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]].
  4. 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.
  5. 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:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. Make a request to the system to delete all the messages associated to the messaging service with identifier equal to the serviceID parameter.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. 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.

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

SmsSegmentInfo Dictionary

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

long segments
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.
long charsPerSegment
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.
long charsAvailableInLastSegment
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.

MmsManager Interface

The MmsManager interface represents the MMS messaging service manager.

readonly attribute MessageType type
MUST return the type of the messaging service manager. It can have the following values: 'sms' or 'mms'.
readonly attribute DOMString[] serviceIDs
MUST return the identifier of the different services for this type of messaging service (e.g. 'sms_sim1').
FetchMode 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).
optional DOMString serviceID
Identifier of the service whose fetch mode is queried.
void 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.
FetchMode fetchMode
Fetch mode that is requested to be set for a specific service.
optional DOMString serviceID
Identifier of the service whose fetch mode is requested to be set.
Promise 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.
MmsContent mmsContent
Content and recipients of the MMS message to be sent.
optional MmsSendParameters sendParameters
Set of parameters related to the submission of the message (e.g. request of delivery/read report or not).
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.
DOMString messageID
Identifier of the MMS message that is requested to be download.
Promise clear ()
This method makes a request to delete all the messages associated to the messaging service passed as parameter.
DOMString serviceID
Identifies the messaging service all whose messages are requested to be deleted.
attribute EventHandler onreceived
Handles the received event of type MessagingEvent, fired when a new message is received on this messaging service manager.
attribute EventHandler onsent
Handles the sent event of type MessagingEvent, fired when a new message is sent using this messaging service manager.
attribute EventHandler ondeliverysuccess
Handles the deliverysuccess event of type DeliveryReportEvent, fired when a new succesful delivery report is received on this messaging service manager.
attribute EventHandler ondeliveryerror
Handles the deliveryerror event of type DeliveryReportEvent, fired when a new failure delivery report is received on this messaging service manager.
attribute EventHandler onreadsuccess
Handles the readsuccess event of type ReadReportEvent, fired when a new succesful read report is received on this messaging service manager.
attribute EventHandler onreaderror
Handles the readerror event of type ReadReportEvent, fired when a new failure read report is received on this messaging service manager.
attribute EventHandler onserviceadded
Handles the serviceadded event of type ServiceChangeEvent, fired whenever a new messaging service is enabled on this messaging service manager.
attribute EventHandler onserviceremoved
Handles the serviceremoved event of type ServiceChangeEvent, fired when an existing messaging service is disabled on this messaging service manager.
It is FFS whether MMS settings (e.g. fetch mode, creation mode) needs to be managed through the MmsManager interface.

Steps

The send method when invoked MUST run the following steps:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. 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.
  4. 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.
  5. 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:

  1. Let mmsMessage be a new instance of MmsMessage.
  2. 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.
  3. Set the messageID of mmsMessage to the generated identifier.
  4. Set the type of mmsMessage to 'mms'.
  5. Set the serviceID of mmsMessage to the identifier of the service at which the message has been received.
  6. Set the read of mmsMessage to 'false'.
  7. 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'.
  8. 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'.
  9. Queue a task to fire an event named received with the message attribute set to mmsMessage.
  10. 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:

  1. Let promise be a new Promise object and resolver its associated resolver
  2. Return promise to the caller.
  3. 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.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. 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:

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);} );
	}
  }
}
  
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

  1. Let mmsMessage be the instance of MmsMessage to which this delivery report is related.
  2. 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.
  3. 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.
  4. 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

  1. Let mmsMessage be the instance of MmsMessage to which this read report is related.
  2. 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.
  3. 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.
  4. 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:

  1. Make a request to the system to delete all the messages associated to the messaging service with identifier equal to the serviceID parameter.
  2. Let promise be a new Promise object and resolver its associated resolver
  3. Return promise to the caller.
  4. If an error occurs invoke resolver's reject algorithm with error as the value argument.
  5. 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.

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

MmsSendParameters Dictionary

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

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.

readonly attribute DOMString messageID
MUST return the identifier of the message.
readonly attribute MessageType type
MUST return the type of message, i.e. 'sms'.
readonly attribute DOMString serviceID
MUST return the messaging service id used to send / receive this message.
readonly attribute DOMString from
MUST return the sender of the message, i.e. the TP Originating Address (TP-OA) of the SMS message.
readonly attribute Date timestamp
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.
readonly attribute boolean read
MUST return 'true' if the message has been marked as read, or 'false' otherwise.
readonly attribute DOMString to
MUST return the recipient of the message, i.e. the TP Destination Address (TP-DA) of the SMS message.
readonly attribute DOMString body
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.
readonly attribute SmsState state
MUST return the status of the SMS message.
readonly attribute DeliveryStatus deliveryStatus
MUST return the delivery status of the SMS message.
readonly attribute Date? deliveryTimestamp
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.
readonly attribute MessageClass messageClass
MUST return the SMS message class, according to the value indicated in the TP-Data-Coding-Scheme (TP-DCS) field of the SMS.

MmsMessage Interface

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

readonly attribute DOMString messageID
MUST return the identifier of the message.
readonly attribute MessageType type
MUST return the type of message, i.e. 'mms'.
readonly attribute DOMString serviceID
MUST return the messaging service id used to send / receive this message.
readonly attribute DOMString from
MUST return the sender of the message, i.e. the 'From' field of the MMS message.
readonly attribute Date timestamp
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.
readonly attribute unsigned long? expiry
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.
readonly attribute boolean read
MUST return 'true' if the message has been marked as read, or 'false' otherwise.
readonly attribute DOMString[] to
MUST return an array containing the recipient(s) included in the 'To' field of the MMS message.
readonly attribute DOMString[] cc
MUST return an array containing the recipient(s) included in the 'Cc' field of the MMS message.
readonly attribute DOMString[] bcc
MUST return an array containing the recipient(s) included in the 'Bcc' field of the MMS message.
readonly attribute DOMString subject
MUST return the subject of the MMS message, corresponding to the 'Subject' field of the MMS message.
readonly attribute DOMString smil
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.
readonly attribute MmsAttachment[]? attachments
MUST return the set of attachments of the MMS message.
readonly attribute MmsState state
MUST return the status of the MMS message.
readonly attribute MmsDeliveryInfo[] deliveryInfo
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.
readonly attribute boolean? readReportRequested
MUST return true in case the originator of a received message requested a read report and false otherwise. MUST return null for sent messages.

MmsContent Dictionary

DOMString subject
Indicates the subject of the MMS message, corresponding to the 'Subject' field of the MMS message.
DOMString[] to
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.
DOMString[] cc
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.
DOMString[] bcc
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.
DOMString smil
Contains the SMIL component, i.e. the presentation element that determines the way the content of the MMS message MUST be displayed.
MmsAttachment[] attachments
Contains the set of attachments of the MMS message.

MmsAttachment Dictionary

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

MmsDeliveryInfo Dictionary

DOMString recipient
The recipient of the MMS to which the delivery status is related.
DeliveryStatus deliveryStatus
The delivery status of the MMS message to a specific recipient.
Date deliveryTimestamp
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 readStatus
The read status of the MMS message to a specific recipient.
Date readTimestamp
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.

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.

readonly attribute DOMString conversationID
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.
readonly attribute MessageType type
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.
readonly attribute DOMString[] participants
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.
readonly attribute DOMString subject
MUST return the subject of the conversation, if there is a single one.
readonly attribute DOMString[] messageTypes
MUST return an array contining the different types of messages included in the conversation.
readonly attribute unsigned long messageCount
MUST return the number of messages in the conversation.
readonly attribute unsigned long unreadCount
MUST return the number of unread messages in the conversation.
readonly attribute DOMString lastMessageID
MUST return the identifier of the message in the conversation with the most recent timestamp.
readonly attribute MessageCursor cursor
MUST return the MessageCursor to access the messages in this conversation.

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.

readonly attribute any? element
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.
void 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]].
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]].

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.

readonly attribute (SmsMessage or MmsMessage) message
MUST return the SmsMessage or MmsMessage object to which this system message is related.

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.

readonly attribute DOMString serviceID
MUST return the identifier of the service used to send the message to which this delivery report is related.
readonly attribute DOMString messageID
MUST return the identifier of the message to which this delivery report is related.
readonly attribute DOMString[] recipients
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.
readonly attribute Date[]? deliveryTimestamps
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)

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.

readonly attribute DOMString serviceID
MUST return the identifier of the service used to send the message to which this read report is related.
readonly attribute DOMString messageID
MUST return the identifier of the message to which this read report is related.
readonly attribute DOMString[] recipients
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.
readonly attribute Date[]? readTimestamps
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.

MessagingEvent Interface

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

readonly attribute (SmsMessage or MmsMessage) message
MUST return the SmsMessage or MmsMessage object to which this event is related.

DeliveryReportEvent Interface

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

readonly attribute DOMString serviceID
MUST return the identifier of the service used to send the message to which this delivery report event is related.
readonly attribute DOMString messageID
MUST return the identifier of the message to which this delivery report event is related.
readonly attribute DOMString[] recipients
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.
readonly attribute Date[]? deliveryTimestamps
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)

ReadReportEvent Interface

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

readonly attribute DOMString serviceID
MUST return the identifier of the service used to send the message to which this read report event is related.
readonly attribute DOMString messageID
MUST return the identifier of the message to which this read report event is related.
readonly attribute DOMString[] recipients
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.
readonly attribute Date[]? readTimestamps
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.

ServiceChangeEvent Interface

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

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

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

MessageType type
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'.
Date startDate
Indicates that messages with timestamp previous to this date will not be provided in the results of this filter.
Date endDate
Indicates that messages with timestamp after this date will not be provided in the results of this filter.
DOMString from
Indicates that just messages sent from this number are to be provided in the results of this filter.
sequence<DOMString> recipients
Indicates that just messages sent to one of these numbers are to be provided in the results of this filter.
(SmsState or MmsState) state
Indicates whether the results of this filter just needs to return the messages matching the indicated state.
DOMString serviceID
Indicates that just messages associated to the messaging service with this identifier are to be provided in the results of this filter.
boolean read
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'.

FilterOptions Dictionary

DOMString sortBy
Indicates the attribute on which the filtered messages are sorted.
DOMString sortOrder
Indicates the order on which the filtered messages are sorted with possible values 'ascending' and 'descending'.
unsigned long limit
Indicates the maximum number of messages that can be returned as a result of applying the corresponding filter.

Enumerations

The attibute type can have the following values:

sms
Corresponding to SMS message(s).
mms
Corresponding to MMS message(s).

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

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:

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:

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:

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:

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:

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.

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.