WebAPI/WebMMS: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
No edit summary
 
(17 intermediate revisions by one other user not shown)
Line 3: Line 3:
On the surface, MMS messages are very similar to multipart HTML emails. One part is responsible for the layout of the message, though MMS uses SMIL rather than HTML. The other parts are attachments, such as text, picture, video, and sound files. Much like in multipart emails, the attachments have "file names" and are referred to by those from the presentation part.
On the surface, MMS messages are very similar to multipart HTML emails. One part is responsible for the layout of the message, though MMS uses SMIL rather than HTML. The other parts are attachments, such as text, picture, video, and sound files. Much like in multipart emails, the attachments have "file names" and are referred to by those from the presentation part.


The API proposal below exposes the SMIL document as a DOM tree and the attachments as Blobs (or, rather, an extension thereof, akin to how File is an extension of Blob). On a User Agent capable of rendring SMIL, the web application may simply render the DOM right away. On other User Agents, it may use XSLT or some other method to convert SMIL to HTML.
The API proposal below tries to reuse as many existing Web technologies as applicable. The SMIL document is exposed as a [https://developer.mozilla.org/en/DOM:document DOM document] and the attachments as [https://developer.mozilla.org/en/DOM/Blob Blob] objects. On a User Agent capable of rendering SMIL, the web application may simply render the DOM right away. On other User Agents, it may use XSLT or some other method to convert SMIL to HTML.


To read the attachments, the web application may use the FileReader API. However, it's not that useful or efficient to have image/audio/video data in memory (e.g. as a typed array). For display purposes the web application just needs a URI that resolves to the data, so that it can point to it in a <video>, <audio>, <img> element. In the simplest case this could be a data: URI, but for large data it might just want to stream the data directly from a file on the disk. (This would be a generally useful feature to provide for all blobs, e.g. when storing multimedia data in IndexedDB.)
To read the attachments, the web application may use the [https://developer.mozilla.org/en/DOM/FileReader FileReader] API. However, it's not that useful or efficient to have image/audio/video data in memory (e.g. as a typed array). For display purposes the web application just needs a URI that resolves to the data, so that it can point to it in a <video>, <audio>, <img> element. This is possible with the [https://developer.mozilla.org/en/DOM/window.URL.createObjectURL window.URL] API.


= API =
= API =
== MmsManager ==


   /**
   /**
Line 40: Line 42:
     DOMRequest  cancelMessage(MmsMessage message);
     DOMRequest  cancelMessage(MmsMessage message);
   }
   }
== MmsMessage ==
  /**
  * MmsMessage constructor.
  */
  MmsMessage MmsMessage(
    DOMString receiver,
    Document document
  );
    
    
   [Constructor]
   [Constructor]
Line 79: Line 91:
     readonly attribute MmsAttachmentStorage attachments;     
     readonly attribute MmsAttachmentStorage attachments;     
   }
   }
== MmsAttachmentStorage ==
    
    
   /**
   /**
   * This object implements a mapping to look up attachments by their name.
   * This object implements a mapping to look up attachments (blobs) by their name.
   *
   *
   *  var text = message.attachments["text.txt"];
   *  var text = message.attachments["text.txt"];
   *  message.attachments["movie.mov"] = new MmsAttachment([data], {type: "application/video"});
   *  message.attachments["movie.mov"] = new Blob([data], {type: "application/video"});
   *  delete message.attachments["picture.png"];
   *  delete message.attachments["picture.png"];
   */
   */
   interface MmsAttachmentStorage
   interface MmsAttachmentStorage
   {
   {
     getter MmsAttachment getAttachment(DOMString name);
     getter Blob getAttachment(DOMString name);
     setter creator void setAttachment(DOMString name, MmsAttachment attachment);
     setter creator void setAttachment(DOMString name, Blob attachment);
     deleter void deleteAttachment(DOMString name);
     deleter void deleteAttachment(DOMString name);
  }
 
  /**
  * MmsAttachment constructor (cf. Blob constructor)
  */
  MmsAttachment MmsAttachment(
    [optional] Array parts,
    [optional] BlobPropertyBag properties
  );
 
  /**
  * MMS attachments extend the DOM Blob type, akin to how File extends Blob.
  */
  [Constructor]
  interface MmsAttachment : Blob
  {
    /**
    * Name of the attachment as it is referenced within the SMIL document (cf. File::name)
    */
    readonly attribute DOMString name;
   
    /**
    * An absolute URI under which User Agent makes the attachment available for download.
    * This is provided so that the data does not have to be loaded into memory first, but
    * can directly be linked to from an <img>, <video>, or <audio> element.
    */
    readonly attribute DOMString uri;
   
    /**
    * Inherited from Blob. See https://developer.mozilla.org/en/DOM/Blob
    */
    readonly attribute unsigned long long size;
    readonly attribute DOMString type;
   }
   }


= Example =
= Examples =


== Receiving an MMS ==
== Receiving an MMS ==


  // Listen for incoming MMS. If the message contents hasn't been fetched yet, do so.
   navigator.mms.onreceived = function (event) {
   navigator.mms.onreceived = function (event) {
     var message = event.message;
     var message = event.message;
Line 142: Line 124:
   }
   }
    
    
  // Deconstruct and display an MMS. For simplicity's sake, this only supports one
  // slide and one multimedia element per slide.
   function handleNewMessage(message) {
   function handleNewMessage(message) {
     var pars = message.contentDocument.querySelectorAll("par");
     var firstPar = message.contentDocument.querySelectorAll("par")[0];
     for (var i = 0; i < pars.length; i++) {
     var mediaEl = firstPar.querySelectorAll("img|audio|video")[0];
      //TODO
    var importedEl = document.importNode(mediaEl);
     }
    var mediaUrl = window.URL.createObjectURL(message.attachments[importedEl.src]);
    importedEl.src = mediaUrl;
    messageDisplayContainer.appendChild(importedEl);
     window.URL.revokeObjectURL(mediaUrl);
   }
   }


== Sending an MMS ==
== Sending an MMS ==


   var smil = "&lt;smil>&lt;body>&lt;par>&lt;video src="lolcat.mov"/>&lt;/par>&lt;/body>&lt;/smil>";
   &lt;html>
  var parser = new DOMParser();
  &lt;body>
  var doc = parser.parseFromString(smil, "application/smil");
    &lt;input type="file" id="picture" accept="image/*">
 
    &lt;div>
  var message = new MmsMessage(recipient, doc);
      &lt;input type="text" id="number">
  message.attachments["lolcat.mov"] = new MmsAttchment("lolcat.mov", "application/video", videoData);
      &lt;button onclick="sendMMS();">Send</button>
 
    &lt;/div>
  navigator.mms.send(message);
    &lt;script>
      function sendMMS() {
        var smil = "&lt;smil>&lt;body>&lt;par>&lt;video src="lolcat.mov"/>&lt;/par>&lt;/body>&lt;/smil>";
        var doc = (new DOMParser()).parseFromString(smil, "application/smil");
        var number = document.getElementById("number").value;
        var message = new MmsMessage(number, doc);
       
        var pictureEl = document.getElementById("picture");
        var pictureBlob = pictureEl.files[0];
        message.attachments["picture.jpg"] = pictureBlob;
       
        navigator.mms.send(message);
      }
    &lt;/script>
  &lt;/body>
  &lt;/html>
 
[[Category:Web APIs]]

Latest revision as of 23:23, 1 October 2014

Overview

On the surface, MMS messages are very similar to multipart HTML emails. One part is responsible for the layout of the message, though MMS uses SMIL rather than HTML. The other parts are attachments, such as text, picture, video, and sound files. Much like in multipart emails, the attachments have "file names" and are referred to by those from the presentation part.

The API proposal below tries to reuse as many existing Web technologies as applicable. The SMIL document is exposed as a DOM document and the attachments as Blob objects. On a User Agent capable of rendering SMIL, the web application may simply render the DOM right away. On other User Agents, it may use XSLT or some other method to convert SMIL to HTML.

To read the attachments, the web application may use the FileReader API. However, it's not that useful or efficient to have image/audio/video data in memory (e.g. as a typed array). For display purposes the web application just needs a URI that resolves to the data, so that it can point to it in a <video>, <audio>, <img> element. This is possible with the window.URL API.

API

MmsManager

 /**
  * TODO should we merge with this with SmsManager? There are good reasons for and against it.
  * Pro: One API to rule them all, less API clutter, easier to write integrated SMS/MMS app
  *      (which is what everybody wants anyway) 
  * Con: MMS is vastly more complex than SMS, both in terms of API as in terms of implementation
  *      and storing; implementations need to be acutely aware of MMS and how to deal with them.
  */
 interface MmsManager
 {
   DOMRequest   send(MmsMessage message);
   DOMRequest[] send(MmsMessage message[]);
   DOMRequest   delete(long id);
   DOMRequest   delete(MmsMessage message);
   DOMRequest   getMessage(long id);
   DOMRequest   getMessages(SMSFilter filter, bool reverse);
   
   /**
    * Fetch a message's data. Only applicable if message.delivery == "unfetched"
    */
   DOMRequest   fetchMessage(MmsMessage message);
   
   /**
    * Forward a message to a different number.
    */
   DOMRequest   forwardMessage(MmsMessage message, recipient);
   
   /**
    * Cancel a message's delivery with the MMSC.
    */
   DOMRequest   cancelMessage(MmsMessage message);
 }

MmsMessage

 /**
  * MmsMessage constructor.
  */
 MmsMessage MmsMessage(
   DOMString receiver,
   Document document
 );
 
 [Constructor]
 interface MmsMessage
 {
   /**
    * Cf. SmsMessage
    */
   readonly attribute long                 id;
   
   /**
    * Like SmsMessage::delivery, but with an additional possible value: "unfetched"
    */
   readonly attribute DOMString            delivery;
   
   /**
    * Cf. SmsMessage
    */
   readonly attribute DOMString            sender;
   
   /**
    * TODO Should this be plural? (AFAIK MMS supports group messaging.)
    */
   readonly attribute DOMString            receiver;
   
   /**
    * Cf. SmsMessage
    */
   readonly attribute Date                 timestamp;
   
   /**
    * DOM document object representing the SMIL document.
    */
   readonly attribute Document             contentDocument;
   
   /**
    * Object containing all other parts.
    */
   readonly attribute MmsAttachmentStorage attachments;     
 }

MmsAttachmentStorage

 /**
  * This object implements a mapping to look up attachments (blobs) by their name.
  *
  *   var text = message.attachments["text.txt"];
  *   message.attachments["movie.mov"] = new Blob([data], {type: "application/video"});
  *   delete message.attachments["picture.png"];
  */
 interface MmsAttachmentStorage
 {
   getter Blob getAttachment(DOMString name);
   setter creator void setAttachment(DOMString name, Blob attachment);
   deleter void deleteAttachment(DOMString name);
 }

Examples

Receiving an MMS

 // Listen for incoming MMS. If the message contents hasn't been fetched yet, do so.
 navigator.mms.onreceived = function (event) {
   var message = event.message;
   if (message.delivery == "unfetched") {
     message.fetch().onsuccess(function (event) {
       handleNewMessage(event.target.result);
     });
   } else {
     handleNewMessage(message);
   }
 }
 
 // Deconstruct and display an MMS. For simplicity's sake, this only supports one
 // slide and one multimedia element per slide.
 function handleNewMessage(message) {
   var firstPar = message.contentDocument.querySelectorAll("par")[0];
   var mediaEl = firstPar.querySelectorAll("img|audio|video")[0];
   var importedEl = document.importNode(mediaEl);
   var mediaUrl = window.URL.createObjectURL(message.attachments[importedEl.src]);
   importedEl.src = mediaUrl;
   messageDisplayContainer.appendChild(importedEl);
   window.URL.revokeObjectURL(mediaUrl);
 }

Sending an MMS

 <html>
 <body>
   <input type="file" id="picture" accept="image/*">
   <div>
     <input type="text" id="number">
     <button onclick="sendMMS();">Send</button>
   </div>
   <script>
     function sendMMS() {
       var smil = "<smil><body><par><video src="lolcat.mov"/></par></body></smil>";
       var doc = (new DOMParser()).parseFromString(smil, "application/smil");
       var number = document.getElementById("number").value;
       var message = new MmsMessage(number, doc);
       
       var pictureEl = document.getElementById("picture");
       var pictureBlob = pictureEl.files[0];
       message.attachments["picture.jpg"] = pictureBlob;
       
       navigator.mms.send(message);
     }
   </script>
 </body>
 </html>