Copyright © 2013 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
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.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document defines a System Level API for access to mobile messaging services including SMS and MMS messages. This can be contrasted with the earlier and discontinued draft messaging specification for the regular browser context.
This document was published by the System Applications Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-sysapps@w3.org (subscribe, archives). All feedback is welcome.
Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
Navigator
Interface
MessagingManager
Interface
SmsManager
Interface
SmsSegmentInfo
Dictionary
MmsManager
Interface
SmsMessage
Interface
MmsMessage
Interface
MmsContent
Dictionary
MmsAttachment
Dictionary
Conversation
Interface
MessagingCursor
Interface
ReceivedMessage
Interface
DeliveryReport
Interface
MessagingEvent
Interface
DeliveryReportEvent
Interface
ServiceChangeEvent
Interface
MessagingFilter
Dictionary
FilterOptions
Dictionary
This section is non-normative.
The Messaging API provides operations to get access to the primitives offered by mobile messaging services (send, receive) as well as those that allow to manage a mobile messaging client inbox (delete, store, mark as read)
An example of use is provided below:
navigator.messaging.sms.send ( '+1234567890', 'How are you?').done( function(message) { window.console.log('Message with identifier ' + message.messageID + ' sent at ' + message.timestamp); }, function(error) { window.console.error('Error: ' + error); } )
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification and terminology.
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].
This API must be only exposed to trusted content
MessagingManager
InterfaceThe 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;
Future findMessages (MessagingFilter
filter, FilterOptions
options);
Future findConversations (DOMString groupBy, MessagingFilter
filter, FilterOptions
options);
Future getMessage (DOMString messageID);
Future deleteMessage (DOMString messageID);
Future deleteConversation (DOMString conversationID);
Future markMessageRead (DOMString messageID, optional boolean value = true);
Future markConversationRead (DOMString conversationID, optional boolean value = true);
};
sms
of type
SmsManager
,
readonlymms
of type
MmsManager
,
readonlyfindMessages
filter
parameter and according to the filtering options
described in the options
. It returns a new
Future
that will be used to notify the
caller about the result of the operation, which is a
MessagingCursor to access the set of messages.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
filter |
|
✘ | ✘ | Filter that identifies the set of messages that are requested to be retrieved |
options |
|
✘ | ✘ | Indicates the filtering options (i.e. sorting criteria, sorting order, limit of results). |
Future
findConversations
groupBy
parameter. Only those messages matching the filter
described in the filter
parameter SHALL be included in the
resulting conversations, what can be useful for instance
to filter just a specific type of messages (e.g. SMS) or
to implement message search in a conversational messaging
client. It returns a new Future
that will be
used to notify the caller about the result of the
operation, which is a MessagingCursor to access the set
of conversations.
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 |
|
✘ | ✘ | Filter that identifies the set of messages that are requested to be included in the resulting conversations. |
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. |
Future
getMessage
messageID
parameter. It
returns a new Future
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 |
Future
deleteMessage
messageID
parameter.
A new Future
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 |
Future
deleteConversation
conversationID
parameter. A new
Future
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 |
Future
markMessageRead
messageID
parameter. The method returns a
new Future
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 =
true |
✘ | ✔ | Indicates whether the message is to be marked as read ('true', which is the default) or unread ('false') |
Future
markConversationRead
conversationID
parameter. The method returns
a new Future
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 =
true |
✘ | ✔ | Indicates whether the messages in the conversation are to be marked as read ('true', which is the default) or unread ('false') |
Future
The findMessages
method
when invoked MUST run
the following steps:
filter
parameter and according to the filtering options described
in the options
parameter.Future
object and resolver its associated
resolver
reject(value)
method with
error as value
argument.MessagingCursor
object providing access to
the results of the retrieval, i.e. the set of
SmsMessage
and/or MmsMessage
elements.accept(value)
method with
messagingCursor as value
argument.The findConversations
method when invoked MUST run the following steps:
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.Future
object and resolver its associated
resolver
reject(value)
method with
error as value
argument.MessagingCursor
object providing access to
the results of the retrieval, i.e. the set of
Conversation
elements.accept(value)
method with
messagingCursor as value
argument.The getMessage
method when invoked MUST run the following steps:
messageID
parameter
passed in the request.Future
object and resolver its associated
resolver
reject(value)
method with
error as value
argument.SmsMessage
or MmsMessage
whose identifier matches the messageID
parameter.accept(value)
method with
message as value
argument.The deleteMessage
method
when invoked MUST run
the following steps:
messageID
parameter
passed in the request.Future
object and resolver its associated
resolver
reject(value)
method with
error as value
argument.messageID
parameter passed in the
requestaccept(value)
method with
messageID as value
argument.The deleteConversation
method when invoked MUST run the following steps:
conversationID
parameter passed in the
request.Future
object and resolver its associated
resolver
reject(value)
method with
error as value
argument.conversationID
parameter passed in the
requestaccept(value)
method with
conversationID as value
argument.The markMessageRead
method when invoked MUST run the following steps:
value
parameter being
respectively 'true' or 'false') the message with identifier
equal to the messageID
parameter passed in the
request.Future
object and resolver its associated
resolver
reject(value)
method with
error as value
argument.messageID
parameter passed in the
requestaccept(value)
method with
messageID as value
argument.The markConversationRead
method when invoked MUST run the following steps:
value
parameter being
respectively 'true' or 'false') the messages in the
conversation with identifier equal to the
conversationID
parameter passed in the
request.Future
object and resolver its associated
resolver
reject(value)
method with
error as value
argument.conversationID
parameter passed in the
requestaccept(value)
method with
conversationID as value
argument.SmsManager
InterfaceThe SmsManager
interface represents the
SMS messaging service manager.
interface SmsManager : EventTarget {
readonly attribute MessageType
type;
readonly attribute DOMString[] serviceIDs;
SmsSegmentInfo
segmentInfo (DOMString text, optional DOMString serviceID);
Future send (DOMString to, DOMString text, optional DOMString serviceID);
Future clear (DOMString serviceID);
attribute EventHandler onreceived;
attribute EventHandler onsent;
attribute EventHandler ondeliverysuccess;
attribute EventHandler ondeliveryfailure;
attribute EventHandler onserviceadded;
attribute EventHandler onserviceremoved;
};
type
of type
MessageType
,
readonlyserviceIDs
of type array of DOMString, readonlyonreceived
of type EventHandler,received
event of type MessagingEvent
, fired when a
new message is received on this messaging service
manager.
onsent
of type
EventHandler,sent
event of type MessagingEvent
, fired when a
new message is sent using this messaging service manager.
ondeliverysuccess
of type EventHandler,deliverysuccess
event of type
DeliveryReportEvent
, fired
when a new succesful delivery report is received on this
messaging service manager.
ondeliveryfailure
of type EventHandler,deliveryfailure
event of type
DeliveryReportEvent
, fired
when a new failure delivery report is received on this
messaging service manager.
onserviceadded
of type EventHandler,serviceadded
event of type
ServiceChangeEvent
, fired
whenever a new messaging service is enabled on this
messaging service manager.
onserviceremoved
of type EventHandler,serviceremoved
event of type
ServiceChangeEvent
, fired when
an existing messaging service is disabled on this
messaging service manager.
segmentInfo
SmsSegmentInfo
object
including information on the number of concatenated SMS
segments needed to send the text in the text
parameter, the number of characters available per segment
and the maximum number of available characters in the
last segment.
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. |
SmsSegmentInfo
send
text
parameter to the destination number
indicated in the to
parameter. A
Future
object will be returned in order to
notify the result of the request.
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. |
Future
clear
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
serviceID |
DOMString |
✘ | ✘ | Identifies the messaging service all whose messages are requested to be deleted. |
Future
The send
method when
invoked MUST run the
following steps:
SmsMessage
:
messageID
of the
SmsMessage
to the generated
identifier.type
of the
SmsMessage
to 'sms'.serviceID
of the
SmsMessage
to the identifier of the
service used to send the message, i.e. the one passed
in the serviceID
parameter, if provided,
or otherwise to the first element in the
serviceIDs
attribute of the
SmsManager
.from
of the
SmsMessage
to the number of the mobile
subscription used to send this SMS message.read
of the
SmsMessage
to 'true'.to
of the
SmsMessage
to the value of the
to
parameter.body
of the
SmsMessage
to the value of the
text
parameter.messageClass
of the
SmsMessage
to 'class1'.state
of the
SmsMessage
to 'sending'.deliveryStatus
of the
SmsMessage
to 'pending' if a delivery
report has been requested or to 'not-applicable'
otherwise.text
parameter to
the number of the recipient indicated in the
to
parameter, using the proper service as
described above.Future
object and resolver its associated
resolver
deliveryStatus
of the
SmsMessage
to 'error'.reject(value)
method with error
as value
argument.state
of the
SmsMessage
to 'sent'.timestamp
of the
SmsMessage
to the timestamp when the SMS
message reached the Short Message Center, i.e. the
value of the TP-Service-Centre-Time-Stamp (TP-SCTS)
parameter returned in the SMS-SUBMIT-REPORT Protocol
Data Unit [GSM-SMS].accept(value)
method with the sent
SmsMessage
as value
argument.sent
with the message
attribute set to the sent SmsMessage
.
The segmentInfo
method when
invoked MUST return a
SmsSegmentInfo
object that contains the
following elements:
segments
element indicating the number
of concatenated SMS segments needed to send the text passed
in the text
parameter using the service with
identifier equal to the one passed in the
serviceID
parameter, if provided, or otherwise
to the first element in the serviceIDs
attribute of the SmsManager
. Note that the
application SHOULD
NOT split the text in a set of strings that fit each
into a single SMS segment as it would result in different
independent SMS messages being sent, but SHOULD instead send the full
message in a single sendSMS
request. However
having information on the number of SMS segments may be
required by the application in order to inform the user
(e.g. in case the length of the text impacts on the price
charged for sending the message).charsPerSegment
element indicating the
number of characters available per SMS segment. This number
depends on the encoding to be used to send the SMS message,
which in turn depends on the language / special characters
included in the text.charsAvailableInLastSegment
element
indicating the maximum number of available characters in
the last segment that would be needed to send the input
string. This provides useful information to the user on the
number of characters that can type without requiring an
additional SMS segment to send the text.Upon a new SMS message being received, the user agent MUST:
SmsMessage
.messageID
of the
SmsMessage
to the generated identifier.type
of the
SmsMessage
to 'sms'.serviceID
of the
SmsMessage
to the identifier of the service at
which the message has been received.from
of the
SmsMessage
to the sender of the SMS message,
i.e. the value of the TP Originating Address (TP-OA) field
of the SMS message [GSM-SMS].timestamp
of the
SmsMessage
to the timestamp of the SMS
message, i.e. the value of the TP-Service-Centre-Time-Stamp
(TP-SCTS) parameter received in the SMS DELIVER Protocol
Data Unit [GSM-SMS].read
of the
SmsMessage
to 'false'.to
of the SmsMessage
to the recipient of the SMS message, i.e. the value of the
TP Destination Address (TP-DA) field of the SMS message
[GSM-SMS].messageClass
of the
SmsMessage
to the message class indicated in
the TP-Data-Coding-Scheme (TP-DCS) field of the SMS message
[GSM-SMS].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].state
of the
SmsMessage
to 'received'.deliveryStatus
of the
SmsMessage
to 'not-applicable'.received
with the message
attribute set to the newly
created SmsMessage
instance.
received
of type ReceivedMessage
with
the message
attribute set to the newly
created SmsMessage
instance.
Upon a delivery report of a previously sent SMS message being received, the user agent MUST
deliveryStatus
parameter of the
SmsMessage
to 'success' or 'error' depending
on the reported result.messageID
attribute set to the
identifier of the SmsMessage
to which this
confirmation is related,serviceID
attribute set to the
identifier of the service used to send such message,
andrecipients
attribute set to the
recipient of such message.DeliveryReport
named
deliverysuccess or deliveryfailure respectively if the
delivery was successfull or not, with
messageID
attribute set to the
identifier of the SmsMessage
to which this
confirmation is related,serviceID
attribute set to the
identifier of the service used to send such message,
andrecipients
attribute set to the
recipient of such message.The clear
method
when invoked MUST run
the following steps:
serviceID
parameter.Future
object and resolver its associated
resolver
reject(value)
method with
error as value
argument.serviceID
parameter passed in the
requestaccept(value)
method with
serviceID as value
argument.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 |
ondeliveryfailure |
deliveryfailure |
DeliveryReportEvent
|
handles failure delivery reports |
onserviceadded |
serviceadded |
ServiceChangeEvent
|
handle new messaging services |
onserviceremoved |
serviceremoved |
ServiceChangeEvent
|
handle disabled messaging services |
SmsSegmentInfo
DictionaryThe SmsSegmentInfo
dictionary contains
information about the segmentation of a given text to be sent
as SMS.
dictionary SmsSegmentInfo {
long segments;
long charsPerSegment;
long charsAvailableInLastSegment;
};
SmsSegmentInfo
Memberssegments
of type longcharsPerSegment
of type longcharsAvailableInLastSegment
of type
longMmsManager
InterfaceThe 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);
Future send (MmsContent
mmsContent, optional DOMString serviceID);
Future fetch (DOMString messageID);
Future clear (DOMString serviceID);
attribute EventHandler onreceived;
attribute EventHandler onsent;
attribute EventHandler ondeliverysuccess;
attribute EventHandler ondeliveryfailure;
attribute EventHandler onserviceadded;
attribute EventHandler onserviceremoved;
};
type
of type
MessageType
,
readonlyserviceIDs
of type array of DOMString, readonlyonreceived
of type EventHandler,received
event of type MessagingEvent
, fired when a
new message is received on this messaging service
manager.
onsent
of type
EventHandler,sent
event of type MessagingEvent
, fired when a
new message is sent using this messaging service manager.
ondeliverysuccess
of type EventHandler,deliverysuccess
event of type
DeliveryReportEvent
, fired
when a new succesful delivery report is received on this
messaging service manager.
ondeliveryfailure
of type EventHandler,deliveryfailure
event of type
DeliveryReportEvent
, fired
when a new failure delivery report is received on this
messaging service manager.
onserviceadded
of type EventHandler,serviceadded
event of type
ServiceChangeEvent
, fired
whenever a new messaging service is enabled on this
messaging service manager.
onserviceremoved
of type EventHandler,serviceremoved
event of type
ServiceChangeEvent
, fired when
an existing messaging service is disabled on this
messaging service manager.
getFetchMode
serviceID
attribute, if provided, or the
first element in the serviceIDs
attribute of
the MmsManager
otherwise).
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
serviceID |
DOMString |
✘ | ✔ | Identifier of the service whose fetch mode is queried. |
FetchMode
setFetchMode
serviceID
attribute, if
provided, or all services otherwise).
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
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. |
void
send
mmsContent
parameter. A
Future
object will be returned in order to
notify the result of the request.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mmsContent |
|
✘ | ✘ | Content and recipients of the MMS message to be sent. |
serviceID |
DOMString |
✘ | ✔ | Identifier of the service through which the message is requested to be sent. |
Future
fetch
messageID
parameter from the URL indicated
in the MMS notification. The method returns a new
Future
that will allow the caller to be
notified about the result (success, error) of the
operation.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
messageID |
DOMString |
✘ | ✘ | Identifier of the MMS message that is requested to be download. |
Future
clear
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
serviceID |
DOMString |
✘ | ✘ | Identifies the messaging service all whose messages are requested to be deleted. |
Future
The send
method
when invoked MUST run
the following steps:
MmsMessage
and:
messageID
of the
MmsMessage
to the generated
identifier.type
of the
MmsMessage
to 'mms'.serviceID
of the
MmsMessage
to the identifier of the
service used to send the message, i.e. the one passed
in the serviceID
parameter, if provided,
or otherwise to the first element in the
serviceIDs
attribute of the
MmsManager
.from
of the
MmsMessage
to the number of the mobile
subscription used to send this MMS message.read
of the
MmsMessage
to 'true'.to
of the
MmsMessage
to the to
in the
mmsContent
parameter.cc
of the
MmsMessage
to the cc
array in
the mmsContent
parameter.bcc
of the
MmsMessage
to the bcc
array
in the mmsContent
parameter.subject
of the
MmsMessage
to the value of the the
subject
parameter in
mmsContent
.smil
of the
MmsMessage
to the value of the the
smil
parameter in
mmsContent
.attachments
of the
MmsMessage
to the value of the the
attachments
array in
mmsContent
parameter.state
of the
MmsMessage
to 'sending'.deliveryStatus
array of the
MmsMessage
for each of the addresses
included in the to
, cc
and
bcc
parameters, with value 'pending' if a
delivery report has been requested or with value
'not-applicable' otherwise.content
parameter to the number(s) of indicated in the
to
parameter, using the proper service as
described above.Future
object and resolver its associated
resolver
deliveryStatus
array of the MmsMessage
to 'error'.reject(value)
method with error
as value
argument.state
of the
MmsMessage
to 'sent'.timestamp
of the
MmsMessage
to the timestamp when the MMS
message was sent, i.e. the date when the M-Send.req
Protocol Data Unit was send from the MMS Client to the
MMS Server.accept(value)
method with the sent
MmsMessage
as value
argument.sent
with the message
attribute set to the sent 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:
MmsMessage
.messageID
of the
MmsMessage
to the generated identifier.type
of the
MmsMessage
to 'mms'.serviceID
of the
MmsMessage
to the identifier of the service at
which the message has been received.read
of the
MmsMessage
to 'false'.from
of the
MmsMessage
to the value of the 'From'
field of the MMS notification, if present.timestamp
of the
MmsMessage
to the timestamp of the binary
SMS message used to transport the MMS notification,
i.e. the value of the TP-Service-Centre-Time-Stamp
(TP-SCTS) parameter received in the SMS-DELIVER
Protocol Data Unit [GSM-SMS].to
array of
the MmsMessage
for each of recipients in
the 'To' field of the MMS notification [MMS13], if
present.cc
array of
the MmsMessage
for each of recipients in
the 'Cc' field of the MMS notification [MMS13], if
present.bcc
array of
the MmsMessage
for each of recipients in
the 'Bcc' field of the MMS notification
[MMS13], if present.subject
element to the value
of the 'Subject' field of the MMS notification
[MMS13], if present.state
of the
MmsMessage
to 'not-downloaded'.MmsMessage
object with the
data contained in the MMS message enclosed in the
M-Retrieve.conf Protocol Data Unit.
from
of the
MmsMessage
to the value of the 'From'
field of the MMS message [MMS13].timestamp
of the
MmsMessage
to the value of the 'Date'
field of the MMS message [MMS13].to
array
of the MmsMessage
for each of
recipients in the 'To' field of the MMS message
[MMS13], if present.cc
array
of the MmsMessage
for each of
recipients in the 'Cc' field of the MMS message
[MMS13], if present.bcc
array
of the MmsMessage
for each of
recipients in the 'Bcc' field of the MMS message
[MMS13], if present.subject
element to the
value of the 'Subject' field of the MMS message
[MMS13], if present.smil
element to a
DOMString
containing the SMIL object
of the received MMS message [MMS13], if
present.attachments
array with:
Blob
object including
the media type and the actual content of the
attachment.contentID
attribute filled
with the Content-ID used to reference this
element from the SMIL object in the incoming
MMS message [MMS13], if
present.contentLocation
attribute
filled with the Content-Location used to
reference this element from the SMIL object in
the incoming MMS message [MMS13],
if present.state
of the
MmsMessage
to 'received'.deliveryStatus
array of the
MmsMessage
for each of recipients in the
'To', 'Cc' and 'Bcc' fields with value
'not-applicable'.received
with the message
attribute set to the newly
created MmsMessage
instance.
received
of type ReceivedMessage
with
the message
attribute set to the newly
created MmsMessage
instance.
The fetch
method
can be invoked to fetch an MMS message that has not been
automatically fetched upon receiving the corresponding MMS
notification due to the fetch mode being manual. When this
method is invoked the User Agent MUST run the following steps:
messageID
parameter passed in the
request matches with an MMS message that has already been
fetched, or to an SMS message go to next step, otherwise
make a request to the system to fetch the MMS message.Future
object and resolver its associated
resolver
reject(value)
method with
error as value
argument.MmsMessage
that has been fetched.accept(value)
method with
message as 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);} ); } } }
Upon a delivery report of a previously sent MMS message being received, the user agent MUST
deliveryStatus
array of the MmsMessage
corresponding to the
recipients to which the delivery report refers to 'success'
or 'error' depending on the reported result.messageID
attribute set to the
identifier of the MmsMessage
to which this
confirmation is related,serviceID
attribute set to the
identifier of the service used to send such message,
andrecipients
attribute set to the
subset of the original recipients to which this
delivery report is related.DeliveryReport
named
deliverysuccess or deliveryfailure respectively if the
delivery was successfull or not, with
messageID
attribute set to the
identifier of the MmsMessage
to which this
confirmation is related,serviceID
attribute set to the
identifier of the service used to send such message,
andrecipients
attribute set to the
recipient of such message.The clear
method
when invoked MUST run
the following steps:
serviceID
parameter.Future
object and resolver its associated
resolver
reject(value)
method with
error as value
argument.serviceID
parameter passed in the
requestaccept(value)
method with
serviceID as value
argument.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 |
ondeliveryfailure |
deliveryfailure |
DeliveryReportEvent
|
handles failure delivery reports |
onserviceadded |
serviceadded |
ServiceChangeEvent
|
handle new messaging services |
onserviceremoved |
serviceremoved |
ServiceChangeEvent
|
handle disabled messaging services |
SmsMessage
InterfaceThe 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 MessageClass
messageClass;
};
messageID
of type DOMString,
readonlytype
of type
MessageType
,
readonlyserviceID
of type DOMString,
readonlyfrom
of type
DOMString,
readonlytimestamp
of type Date,
readonlyread
of type
boolean,
readonlyto
of type
DOMString,
readonlybody
of type
DOMString,
readonlystate
of type
SmsState
,
readonlydeliveryStatus
of type DeliveryStatus
, readonly
, nullablemessageClass
of type MessageClass
,
readonlyMmsMessage
InterfaceThe 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 boolean read;
readonly attribute DOMString[] to;
readonly attribute DOMString[] cc;
readonly attribute DOMString[] bcc;
readonly attribute DOMString subject;
readonly attribute DOMString smil;
readonly attribute MmsAttachments[]? attachments;
readonly attribute MmsState
state;
readonly attribute DeliveryStatus
[] deliveryStatus;
};
messageID
of type DOMString,
readonlytype
of type
MessageType
,
readonlyserviceID
of type DOMString,
readonlyfrom
of type
DOMString,
readonlytimestamp
of type Date,
readonlyread
of type
boolean,
readonlyto
of type array
of DOMString,
readonlycc
of type array
of DOMString,
readonlybcc
of type array
of DOMString,
readonlysubject
of
type DOMString,
readonlysmil
of type
DOMString,
readonlyattachments
of type array of MmsAttachments, readonly ,
nullablestate
of type
MmsState
,
readonlydeliveryStatus
of type array of DeliveryStatus
,
readonlyMmsContent
Dictionary
dictionary MmsContent {
DOMString subject;
DOMString[] to;
DOMString[] cc;
DOMString[] bcc;
DOMString smil;
MmsAttachment
[] attachments;
};
MmsContent
Memberssubject
of
type DOMStringto
of type array
of DOMStringto
, cc
or bcc
attributes.cc
of type array
of DOMStringto
, cc
or bcc
attributes.bcc
of type array
of DOMStringto
, cc
or bcc
attributes.smil
of type
DOMStringattachments
of type array of MmsAttachment
MmsAttachment
Dictionary
dictionary MmsAttachment {
DOMString contentID;
DOMString contentLocation;
Blob content;
};
MmsAttachment
MemberscontentID
of type DOMStringcontentLocation
of type DOMStringcontent
of
type BlobConversation
InterfaceThe 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;
};
conversationID
of type DOMString, readonlytype
of type
MessageType
,
readonlyparticipants
of type array of DOMString, readonlysubject
of
type DOMString,
readonlymessageTypes
of type array of DOMString, readonlymessageCount
of type unsigned long, readonlyunreadCount
of type unsigned long, readonlylastMessageID
of type DOMString, readonlycursor
of
type MessageCursor,
readonlyMessageCursor
to access the messages in this
conversation.MessagingCursor
InterfaceThe 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 Future 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 ();
};
element
of type any,
readonly , nullablenext
"InvalidStateError"
error as defined in
[DOM4].
void
previous
"InvalidStateError"
error as defined in
[DOM4].
void
ReceivedMessage
InterfaceThe 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;
};
message
of type (SmsMessage or
MmsMessage), readonlySmsMessage
or MmsMessage
object
to which this system message is related.DeliveryReport
InterfaceThe 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;
};
serviceID
of type DOMString, readonlymessageID
of type DOMString, readonlyrecipients
of type array of DOMString, readonlyMessagingEvent
InterfaceThe MessagingEvent
interface represents
events related to a message sent or received.
interface MessagingEvent {
readonly attribute (SmsMessage
or MmsMessage
) message;
};
message
of type (SmsMessage or
MmsMessage), readonlySmsMessage
or MmsMessage
object
to which this event is related.DeliveryReportEvent
InterfaceThe 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;
};
serviceID
of type DOMString, readonlymessageID
of type DOMString, readonlyrecipients
of type array of DOMString, readonlyServiceChangeEvent
InterfaceThe ServiceChangeEvent
interface
represents events related to messaging services enabled or
disabled.
interface ServiceChangeEvent : Event {
readonly attribute DOMString serviceID;
};
serviceID
of type DOMString, readonlyMessagingFilter
DictionaryThe 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;
};
MessagingFilter
Memberstype
of
type MessageType
startDate
of type DateendDate
of type Datefrom
of
type DOMStringrecipients
of type sequence<DOMString>state
of
type (SmsState or
MmsState)serviceID
of type DOMStringread
of
type booleanFilterOptions
Dictionary
dictionary FilterOptions {
DOMString sortBy;
DOMString sortOrder;
unsigned long limit;
};
FilterOptions
MemberssortBy
of
type DOMStringsortOrder
of type DOMStringlimit
of
type unsigned
longThe 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",
"draft",
"sending",
"sent",
"failed"
};
Enumeration description | |
---|---|
received |
The message is an inbound message. |
draft |
The message is a draft, i.e. it has not yet been sent. |
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",
"received",
"draft",
"sending",
"sent",
"failed"
};
Enumeration description | |
---|---|
not-downloaded |
The message is an inbound message, for which an MMS mnotification has been received but that has not yet been downloaded. |
received |
The message is an inbound message. |
draft |
The message is a draft, i.e. it has not yet been sent. |
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 MMS fetch mode can have the following values:
enum FetchMode {
"automatic",
"manual"
};
Enumeration description | |
---|---|
automatic |
MMS message is fecthed right after the reception of the MMS notification. |
manual |
The message is not fecthed until the user manually requests it. |
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.