WebAPI/WebSMS

From MozillaWiki
Jump to: navigation, search

Steps

In a first time, we want an API that allows to do a SMS Messaging application with similar features that the stock one.

Some advanced functionality might be added after. For example, a "before-sms-send" event that would allow preventing sending a SMS with .preventDefault().

MMS support will be considered later.

Status

You can find some patches here: bug 674725. They are implementing some parts of the proposed API except delete, get and SmsRequest. Also, SmsMessage isn't fully implemented. Those patches are still work in progress.

Proposed API

This API is work in progress and mostly reflect what is implemented and is going to be really soon. Some changes are going to happen. See the comments below each interfaces.

navigator.sms returns an object with the following interface:

 interface SmsManager
 {
   SmsRequest       send(DOMString number, DOMString message);
   SmsRequest[]     send(DOMString[] number, DOMString message);
   unsigned short   getNumberOfMessagesForText(in DOMString text);
   SMSRequest       delete(in long id);                       // request.result == boolean
   SMSRequest       delete(in SmsMessage message);            // request.result == boolean
   SMSRequest       getMessage(in long id);                   // request.result == SMSMessage
   SMSRequest       getMessages(in SMSFilter filter, bool reverse); // request.result == SMSIterator
   SMSRequest       markMessageRead(long id, boolean aValue); // request.result == boolean
 };

Comments:

  • Should use opaque objects as message-identifiers rather than longs?
 interface SmsRequest
 {
   readonly attribute DOMString readyState; // "processing" or "done"
   readonly attribute DOMError? error;
   attribute EventListener      onsuccess;
   attribute EventListener      onerror;
   attribute readonly any?      result;
 };
 interface SmsMessage
 {
   readonly attribute long      id;
   readonly attribute DOMString delivery; // could be "sent" or "received"
   readonly attribute DOMString sender;
   readonly attribute DOMString receiver;
   readonly attribute DOMString body;
   readonly attribute Date      timestamp;
   readonly attribute boolean   read;
 };

Comments:

  • We have .sender and .receiver because someone can have multiple number or change numbers. We could merge them to .number if that seems necessary.
 [Constructor]
 interface SmsFilter {
   Date?        startDate;
   Date?        endDate;
   DOMString[]? numbers;
   [TreatNullAs=EmptyString, TreatUndefinedAs=EmptyString]
   DOMString?   delivery; // whether "sent" or "received"
   boolean?     read;
 };

Comments:

  • When we will have MMS support, we would have to add a .type property to allow looking for SMS or MMS.
  • For the moment, there is no way to filter according to the content of a message because we didn't find a nice way to do it. This could be added later though.
 interface SmsIterator {
   readonly SmsFilter   filter;
   readonly SMSMessage? message;
   void next();
 };

In addition of these interfaces, there is a new event:

 [Constructor(DOMString type, optional SmsEventInit smsEventInitDict)]
 interface SmsEvent : Event
 {
   readonly attribute SmsMessage message;
 };
 
 dictionary SmsEventInit : EventInit {
   SmsMessage message;
 }

The SmsEvent is used for the following events:

 smssent: happens on all window when a SMS is sent;
 smsdelivered: happens on all window when a SMS is delivered to the recipient;
 smsreceived: happens on all window when a SMS is received.

These events carry the SMS in event.message. A security story has to be defined for these events.