This specification defines an API that provides scripted access to messaging services associated with the hosting device.
Nokia hereby grants to the W3C a perpetual, nonexclusive, royalty-free, world-wide right and license under any Nokia copyrights on this contribution, to copy, publish and distribute the contribution under the W3C document licenses.
Additionally, should the submission be used as a contribution towards a W3C Activity, Nokia grants a right and license of the same scope to any derivative works prepared by the W3C and based on, or incorporating all or part of, the contribution. Nokia further agrees that any derivative works of this contribution prepared by the W3C shall be solely owned by the W3C.
Nokia Corporation agrees to offer W3C members and non-members granting reciprocal terms a non-assignable, non-sublicensable, worldwide and royalty free license to make, have made, use, sell, have sold, offer to sell, import, and distribute and dispose of implementations of any portion of the submission that is subsequently incorporated into a W3C Recommendation. Such license shall extend to all Essential Claims owned or controlled by Nokia Corporation and shall be available as long as the Recommendation is in effect.
This section is non-normative.
The Messaging API defines a high-level interface to access messaging service of the device.
The following example code illustrates how to work with a messaging service associated with the hosting device.
Example of instantiating a service object to access the device messaging service.
// Loads an instance of a messaging interface identified by a service name
// "device", an interface name "messaging" and an interface version "1" or later.
var myMessaging = org.w3c.device.load("device", "messaging", "1");
NOTE: the namespace for the service interface loader is tentative.
Example of retrieving a list of messages according to a specified match criteria.
// A callback function for getList(). Once invoked displays a
// summary of messages.
function callback(iterator, status, transactionId) {
var messageInfo, summary;
if (status) {
alert("Error: " + status);
}
while (messageInfo = iterator.next()) {
summary += messageInfo.message.subject + "\n";
}
alert(summary);
}
// Asynchronously retrieves a list of messages from a sender identified
// by a phone number "1234567890".
var transactionId = myMessaging.getList(callback, { senders: ["1234567890"] });
Example of sending a new SMS message.
// A callback function for send() to get a notification once the message
// has been sent.
function callback(status, transactionId) {
if (status) {
alert("Error sending the message: " + status);
} else {
alert("Message sent successfully.");
}
}
var transactionId = myMessaging.send(callback,
{ type: "sms", to: ["1234567890"], body: "Hello world!" });
Example of displaying new incoming messages.
// A callback function invoked once a new message is received
// to display the message
function callback(messageId, status, transactionId) {
if (status) {
alert("Error: " + status);
// Unregister the callback.
myMessaging.cancelNotification();
return;
}
var messageInfo = myMessaging.getMessage(messageId);
alert ("New message: " + messageInfo.message.subject);
// Set the message status as read.
myMessaging.setStatus(messageId, 0);
}
// Registers callback function to receive notifications of incoming messages.
var transactionId = myMessaging.setNotifier(callback);
This section is non-normative.
This specification is limited to [define scope].
To be written ...
The API defined in this specification can be used to retrieve messages on the hosting device thus a conforming implementation should ensure no messaging information is made available without the user's informed consent.
A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that privacy information is not revealed without user's informed consent.
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].
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 [WebIDL].
The Messaging object can be used by scripts to pragmatically access the messaging service of the hosting device.
interface Messaging {
void startEditor(in MessageData message);
int getList(in MessageListCallback callback);
int getList(in MessageListCallback callback, in MatchCriteria matchCriteria);
int getList(in MessageListCallback callback, in MatchCriteria matchCriteria, in SORT_BY sortKey);
int getList(in MessageListCallback callback, in MatchCriteria matchCriteria, in SORT_BY sortKey, in SortOrder sortOrder);
int send(in SendCallback callback, in MessageData message);
int send(in SendCallback callback, in MessageData message, in DOMString messageId);
void setNotifier(in NotifierCallback callback);
void cancelNotifier();
MessageInfo getMessage(in DOMString messageId);
void deleteMessage(in DOMString messageId);
void setStatus(in DOMString messageId, in MESSAGE_STATUS status);
void cancel(in int transactionId);
};
interface MessageListCallback {
void handleEvent(in MessageIterator messageIterator,
in int status,
in int transactionId);
};
interface SendCallback {
void handleEvent(in int status,
in int transactionId);
};
interface NotifierCallback {
void handleEvent(in DOMString messageId,
in int status,
in int transactionId);
};
The startEditor() method
takes a MessageData object
as an argument and launches the device messaging editor with pre-populated
message data.
An alternative mechanism for launching a device messaging editor for e.g. desktop user agents must be specified. One option would be to use the mailto URL scheme as a standards compliant fallback mechanism.
The getList() method takes one,
two, three or four arguments. When called it must immediately return a unique
transactionId. Next it must asynchronously retrieve a
MessageIterator object
based on a specified
MatchCriteria object,
sortKey and sortOrder and invoke its associated
callback argument with the transactionId, the
status and the MessageIterator object as arguments.
matchCriteria argument is null or undefined the
MessageIterator
to all messages must be retrieved and passed to the associated callback function.sortKey argument is null or
undefined the default value is the representation of the
SORT_BY_DATE as specified in
Sort By Constants.sortOrder argument is null or
undefined the default value is the representation of the
SORT_ASCENDING as specified in
Sort Order Constants.
The send() takes two or three
arguments. When called it must immediately return a unique
transactionId and asynchronously send the message. The
MessageData object contains
the message to be sent. The messageId argument is used to forward
the existing message.
The use of messageId argument in the send()
method must be specified.
The setNotifier() method
takes a callback argument. When called it must immediately return
a unique transactionId. The associated callback
function is asynchronously invoked each time a new incoming message is
received with transactionId, status and
messageId of the incoming message as arguments. If the
callback has already been registered the new handler will replace
it. Invoking the cancelNotifier()
method must stop the notifications.
transactionId returned by this method
should not be used in cancel() method to stop
further notifications from the requested channel, instead user must invoke the
cancelNotifier() method.The cancelNotifier()
method unregisters the callback function registered with the
setNotifier() method and
stops incoming message notifications.
The getMessage() method
takes a messageId of an existing message and must retrieve
associated MessageInfo
object synchronously.
The deleteMessage()
method takes messageId of an existing message.This method must
remove the the associated message from the device messaging store.
The setStatus() method
takes two arguments. The method must change the state of an existing message
identified by a messageId in the messaging store to the
status as specified in
Message Status Constants.
The cancel() method takes a
unique transactionId of the ongoing asynchronous request and
cancels it.
MatchCriteria objects are
regular ECMAScript objects that have the following properties:
interface MatchCriteria {
attribute sequence<DOMString> type;
attribute sequence<DOMString> senders;
attribute DOMString subject;
attribute DOMTimeStamp start;
attribute DOMTimeStamp end;
};
All the attributes in MatchCriteria
object are optional.
The type attribute represents an
array of specified message types to be searched as specified in
Message Type Constants. If this is
undefined or null then all the message types must be
considered.
The senders attribute
represents an array of senders to be searched. The search is case-insensitive
and must support substring searching. If this is undefined or
null then messages from all the senders must be considered.
The substring search algorithm must be specified.
The subject attribute
represents the text to be searched in a subject field of a
MessageInfo object. The
search is case-insensitive and must support substring searching.
The start attribute specifies
the start date for the search, that is the lower bound.
The end attribute specifies the
end date data for the search, that is the upper bound.
AttachmentData objects are
regular ECMAScript objects that have the following properties:
interface AttachmentData {
attribute DOMString uri;
};
The uri attribute
specifies a path to the attachment file as a Uniform Resource Identifier (URI)
conforming to [RFC3986].
MessageData objects are regular
ECMAScript objects that have the following properties:
interface MessageData {
attribute DOMString type;
attribute sequence<DOMString> to;
attribute DOMString body;
attribute DOMString subject;
attribute sequence<DOMString> cc;
attribute sequence<AttachmentData> attachments;
};
All the attributes except type
and to in a
MessageData object are
optional for send()
and startEditor() methods.
The type attribute
represents the type of the message. All implementations must support the
message types defined in
Message Type Constants.
For compliancy with non-mobile User Agents the requirement for supporting mobile-specific message types must be relaxed.
The to attribute
represents an array of message recipients' phone numbers.
The body attribute
represents the message, that is the actual textual message body.
The subject
attribute represents the subject of the message. The attribute is only
applicable if the type of the message is mms.
The cc attribute
represents an array of secondary message recipients' phone numbers.
The attachments
contains an array of AttachmentData
objects to be added to the message.
MessageInfo objects are regular
ECMAScript objects that have the following properties:
interface MessageInfo {
attribute DOMString id;
attribute MessageData message;
attribute DOMString sender;
attribute DOMTimeStamp time;
attribute boolean unread;
};
The id attribute
represents the unique identifier of a message in the device message store.
The message
attribute represents the
MessageData object.
The sender attribute
contains the sender contact phone number of the message.
The time attribute
represents the creation date and time of the message.
The unread attribute
represents the status of the message. The value is true if the
message is unread and false if it has been read, ie. opened.
MessageIterator objects are
regular ECMAScript objects that have the following properties:
interface MessageIterator {
MessageInfo next();
boolean hasNext();
};
The next() method
returns the next MessageInfo object
in the list. If the last message information in the list is reached the method
will return null.
The hasNext() method
returns true if the next
MessageInfo object exists, otherwise
it returns false.
On error, the APIs throw DeviceException with an informative
error code. The DeviceException interface and error constants are
defined in Appendix A.
MESSAGE_STATUS must take these constant values of type
unsigned short int.
STATUS_READ 0 represents a read message.STATUS_UNREAD 1 represents an unread message. SORT_BY must take these constant values of type
unsigned short int.
SORT_BY_DATE 0 represents message sorting by date.SORT_BY_SENDER 1 represents message sorting by sender.SORT_ORDER must take these constant values of type
unsigned short int.
SORT_ASCENDING0 represents ascending sort order.SORT_DESCENDING1 represents descending sort order.The type attribute in
MessageData and
MatchCriteria must take
these case insensitive constant values of type DOMString.
sms mms