WebIntents/MIME Types

From W3C Wiki

Passing MIME type data through Web Intents

A Web Intent payload can have either a string literal or a MIME type. This document describes the payload data format clients must use, and services can expect, when using MIME type specifiers.

There are seven top-level MIME type specifiers (see RFC 2046 and | http://www.iana.org/assignments/media-types/index.html). Four of these types contain binary data:

image/

video/

audio/

application/

For these types, the Web Intent payload data field must either be empty or contain a Blob type representing the binary contents of the resource in question.

For the other three types, the intent payload data field (if populated by the client) must contain the raw text of the payload. (The "example/" top-level specifier can be considered a raw text case.)

text/

multipart/

message/

In addition, the extras field may contain a key named "url" pointing to a fully qualified url value. This url can be any sort of url (i.e. a data url, a blob url, a file url, or a remote http url). Such a url, if present, is suitable for setting as the src attribute of an image or video tag, for example. A client may in some circumstances omit omit either of these data fields, or choose to include both. For instance, a client which does not wish to disclose the url of a particular resource may pass the contents as a Blob and not pass the url. A client which only has the url of the resource and not the contents may pass the url in extras and leave the data field blank.

Services accepting MIME types should be prepared to handle any of these three cases the client may prepare: data present as Blob or raw text contents and no url, url present but no resource content, or both present.

In addition to a "url" field, clients may prepare an optional "filename" field. This field's value is not a url, but is the filename (probably not fully qualified, but simply the name of the leaf file) of the resource being passed as assigned by the user. This is useful, for instance, in sharing a picture, or saving a file: the contents of the image or file can be sent, along with the filename on the local system, even if there is no assignable url.

Examples

Invoking an image edit intent for a url:

var imageUrl = document.getElementById("main-image").src;
var intent = new Intent(
   {"action":"http://webintents.org/edit",
    "type":"image/jpg",
    "extras":{"url":imageUrl}});
navigator.startActivity(intent, myCallback);

Preparing an application Blob of a feed for an intent:

var feedXmlContents = readXmlForFeed();
BlobBuilder bb = new BlobBuilder();
bb.append(feedXmlContents);
navigator.startActivity(new Intent(
  {"action":"http://webintents.org/subscribe",
   "type":"application/rss+xml",
   "data":bb.getBlob("application/rss+xml")}));

Since the feed contents likely doesn't have the url of the feed itself, the client may want to provide it so the service can more easily manage the subscription:

var feedXmlUrl;
navigator.startActivity(new Intent(
  {"action":"http://webintents.org/subscribe",
   "type":"application/rss+xml",
   "data":bb.getBlob(),
   "extras":{"url":feedXmlUrl}}));

Invoking the share intent for user-edited message:

var shareText = document.forms[0].textBox.value;
navigator.startActivity(new Intent(
  {"action":"http://webintents.org/share",
    "type":"text/plain",
    "data":shareText}));

Invoking the share intent for the current page:

navigator.startActivity(new Intent(
  {"action":"http://webintents.org/share",
   "type":"text/uri-list",
   "data":window.location}));

As these examples show, the preparation depends on the MIME type. For a binary data type (image/, audio/, video/, application/), the client must send the data as a Blob. Even if the content is really text, as for the application/rss+xml type feed in the example, it must be wrapped in a Blob container. If this data were passed as text/xml, it would need to be sent as raw text in the payload.

Note: It is expected that composite types (message/, multipart/) will play little role in the intents ecosystem.