Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
A Powerbox facilitates the creation of links between customer content and resources hosted at Web sites or created on-the-fly from sensors built into the user's Web browsing device. By using the Powerbox, customer content can request access to a user's private resources, regardless of where those resources reside or how they are created.
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 is for review by the Device APIs Working Group and is subject to change without notice. This document has no formal standing within W3C. Please consult the group's home page and the W3C technical reports index for information about the latest publications by this group.
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.
This section is non-normative.
Today's users have a great variety of private resources beyond the files stored on their local computing device. Web sites maintain user collections of photos, email, contact information, documents, videos and other types of content. In addition to static content, these sites also offer interactive resources such as discussion forums and event planning. A great variety of such sites exist and ever more are created. Today's computing devices are also typically equiped with many sensors, such as a camera, microphone, geolocation and even physical orientation of the device. These sensors enable quick creation of new resources. In such a resource rich environment, a particular resource might want to support linking and interaction with other resources without being tightly coupled to where these resources are hosted or how they are produced. To meet this need, we introduce a mechanism that enables:
Using this mechanism, customer content can acquire a link to a resource in a uniform way, independent of where the resource is hosted or how it is created. The resource may be created on-the-fly from local sensors, such as the camera, or hosted at a web site, such as a photo sharing site. Similarly, a resource host or creator can offer its resources in a way that makes them readily accessible from customer content. To maintain privacy and security, this facilitated exchange of links between providers and customers remains under the control and direction of the user.
To support compatibility with legacy user-agents and legacy customer content,
we reuse the existing file input control in HTML as the mechanism for declaring
interest in a particular type of resource. Without changing the syntax or
semantics of this HTML element, we extend its scope to also include resources
hosted by web sites or dynamically created from local sensors. To support the
decentralized development of an ever evolving set of resource types, we reuse
the class
and accept
attributes of the file input
control as the namespace for resource types. Customer content declares interest
in a particular type of resource by annotating a file input control with
particular MIME media types and/or class names. To enable customer content to
initiate interactive selection of provided resources, we define an HTTP request
pattern for launching a resource provider's resource selection presentation.
This specification is written for resource authors and user-agents.
As well as sections and appendices marked as non-normative, all diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
In this specification, the terms MUST and MUST NOT are to be interpreted as described in [RFC2119].
A conformant resource is one that implements all the requirements listed in this specification that are applicable to resources.
A conformant user-agent is one that implements all the requirements listed in this specification that are applicable to user-agents.
This section provides an overview of the interaction model and definitions of the various actors and artifacts involved in these interactions.
We aim to facilitate user directed introduction of resources to customer content. Customer content declares interest in a particular type of resource identified by MIME media types and/or HTML class names. A Provider is a resource that responds to an HTTP request asking for a provided resource. A Powerbox is the part of a user-agent that mediates introductions of provided resources to Customers. When a user acts on a Customer request, the Powerbox presents the user with a choice of registered Providers. The Powerbox typically does not interpret any part of a Customer request and so does not perform any filtering of Providers. The Powerbox simply forwards a Customer request to a user selected Provider. A Provider responds to this request with a URL for a provided resource, which the Powerbox forwards to the Customer content. An interactive Provider additionally returns a representation to be presented to the user, but withheld from the Customer content. This presentation typically supports user selection or configuration of the provided resource. A non-interactive Provider requires no user interaction to provide a resource and so only returns a URL for the provided resource.
It is expected that Providers will be coarse grained, acting as a gateway to a great number of resources. For example, a given Provider might provide all user accessible resources at a particular Web site. Once selected for a particular Customer request, a Provider can use the specified type identifiers and user interaction to choose among the Provider's resources. Although there may exist a great number of Providers, it is expected that any particular user will only register a small subset of offered Providers with their Powerbox. Consequently, the list of Providers a Powerbox presents to a user is expected to be relatively short.
Content offers a Provider for registration with a Powerbox by including a link with a rel
attribute of value Provider
. The link's href
attribute
specifies the Provider URL.
For example, a page offers a Provider by including a
<LINK>
such as:
<LINK rel="Provider" href="/myvideos" title="Video Selector">
Alternatively, page content offers a Provider by
including a <A>
such as:
<a rel="Provider" href="/myvideos">Video Selector</a>
A Web site might announce the availability of a Provider in much the same way it does an RSS feed. A site might link to a Provider from all of its pages or only on pages where it's most relevant. Similarly, a browser might signal an offered Provider in much the same way it signals an offered RSS feed, using a passive indicator instead of prompting the user.
A user-agent MUST provide a presentation of an offered Provider that enables the user to request it be registered, unless it is already registered. URI equivalence, using any of the techniques defined in [RFC3986], can be used to determine if an offered Provider is the same as a registered one.
Customer content makes a requisition for a resource by including a file select control [HTML4].
For example, a requisition for a video is expressed as:
<input type="file" accept="video/*" class="trailer" alt="Video for your profile page">
The following [HTML4] attributes of a requisition control are requisition parameters:
alt
: Customer's reason for the requesttitle
: Customer's reason for the requestclass
: requested resource typesaccept
: accepted MIME media typesmultiple
: can a Provider provide a collection of resources for this requisitionIf a Customer has additional data to transfer, it can be sent in a subsequent request to the provided resource. The data in the requisition is only intended to support designation of the provided resource.
When a user activates a requisition control, the
Powerbox MUST enable user selection of
a registered Provider. If the user selects one, the
Powerbox sends the selected Provider a request for a provided resource. This provision request MUST be a uniform request [UMP] to the Provider URL with
method POST
and entity media type
application/x-www-form-urlencoded
. For any requisition parameters specified on the requisition control, the entity content MUST include a parameter with the same name and value.
For example, a Powerbox might send a provision request like the following one:
POST /myvideos HTTP/1.1 Host: example.com Content-Type: application/x-www-form-urlencoded accept=video%2F*&class=trailer&alt=Video+for+your+profile+page
To provide a resource, a Provider MUST respond to a provision request with
a 200
-level uniform response [UMP] that specifies a provided resource URL in the
Location
response header. The Powerbox MUST assign this URL to the corresponding requisition control's value
attribute. If
the response also includes a response entity, the Powerbox MUST present it.
For example, an interactive Provider might return a provision response like:
HTTP/1.1 201 Created Access-Control-Allow-Origin: * Location: https://example.com/video123 Content-Type: text/html <html> …
The Powerbox displays the HTML content of the response in a new browser tab.
A provided resource URL can be obtained
from the corresponding requisition control's
value
attribute. This URL may be used with any API supported by the
user-agent.
For example, Customer content may extract a provided resource URL from an
<INPUT>
's value
attribute and assign it to a
<IMG>
's src
attribute.
<FORM>
SubmissionTo retain compatibility with existing content, the behavior of a file input
control populated by a provision request is compatible
with one populated by selection of a file from the local filesystem. If the
file control is part of a <FORM>
submission, the Powerbox MUST fetch the content to be
included in the submission by making a uniform request [UMP] to the provided
resource URL with method GET
. If the provided resource URL identifies a collection
of resources, a success response to this request MUST be of
MIME type multipart/mixed
, the same format specified by [HTML4] for submission of multiple files. The filename
reported in the <FORM>
submission MUST be
the last segment of the path component of the provided resource URL, where the terms "path"
and "segment" are as defined in [RFC3986].
A uniform request is necessary since the provided resource URL is chosen by a remote
site. Consequently, it might not be safe for the <FORM>
submission to include content that was fetched using credentials.
This section is non-normative.
This section offers advice to resource authors.
Different types of provided resources differ
in their support for: types of entity content, URL construction patterns and
HTTP methods. A particular Customer may only be able to
interact with a provided resource that conforms
to some profile of this range of possible behavior. To support interaction with
many Customers, a resource author should create
resources that conform to existing profiles, such as those defined in standards
and identified by a specific MIME media type. When new or custom behavior is
required, a new profile can be defined and identified by a MIME media type or a
globally unique class
attribute. A MIME media type is best used to
coordinate entity content syntax. A custom class
attribute is
especially useful for coordinating URL construction patterns or additional
semantics for entity data. A globally unique class name can be generated by
extending the namespace defined by the DNS, such as
org.example.MyInterface
. When responding to a provision request, a Provider
should use these identifiers to assist selection of an appropriate resource. A
Provider should ignore unrecognized identifiers.
The Powerbox is a general purpose mechanism for introducing Customer content to new and potentially private resources.
New types of resources can be made accessible to Web content by using the
Powerbox for discovery and introduction, existing user-agent APIs such as
XMLHttpRequest for interaction, existing MIME media types for syntax, and HTTP
methods for general semantics. In some cases, new class
identifiers
may need to be defined to coordinate custom interaction patterns, but otherwise,
these techniques should often be sufficient to Web-enable a wide variety of
hardware and software artifacts.
When deciding how to represent some computer artifact as a collection of resources, aiming for a finer granularity can often make access control issues more easily solved. For example, in the Examples section of this document, a design for making a computer's video camera accessible to Web content is presented. Rather than representing the camera as a single resource to which Web content may be granted access, the presented design instead represents the camera as a sequence of short-lived video capture events. Instead of getting access to the camera itself, Web content only gets access to one of these capture events. When the capture event ends, so does all of the Web content's permission to the camera. Other kinds of artifacts can similarly be subdivided into fine grained resources that match the granularity of typical user interaction patterns.
Since a provided resource URL may be an alias for another resource URL, clients should keep in mind the Web's URI opacity good practice and so not infer any properties of the referenced resource based on the content of a provided resource URL. In particular, a provided resource URL may redirect to a completely different URL identifying a resource hosted at a different Web site.
This appendix is non-normative.
This section illustrates use of the Powerbox mechanism in a variety of scenarios.
In this scenario, a Customer receives access to a live video stream from a camera attached to the user's computer. The Provider is built into the user-agent, instead of being hosted on the Web.
The Customer content includes a requisition control like:
<input type="file" accept="video/*" class="org.w3c.Broadcast" alt="Video for your profile page">
The user activates this requisition control,
prompting the Powerbox to present a choice of registered
Providers. The user selects the built-in video capture
Provider. This non-interactive Provider turns on the computer's video camera and
microphone and activates a video recording status indicator in the user-agent's
chrome. The Provider responds to the Powerbox with a newly created provided resource URL that identifies the
in-progress video stream. The value of this URL is specific to the particular Provider, but it might look like:
chrome://camera/live?s=mhbqcmmva5ja3
. By including an unguessable
secret in the URL, the Provider ensures that, initially,
only the Customer has access to the video stream. The
Powerbox assigns this URL to the corresponding requisition control's value
attribute.
The Customer, knowing it requested a resource of type
org.w3c.Broadcast
, sends a request to the provided resource asking it to send it's content
to the Customer's server. Using an XMLHttpRequest-like
API, the Customer sends the following JSON request to
the provided resource:
POST chrome://camera/live?s=mhbqcmmva5ja3 HTTP/1.1 Content-Type: text/plain; charset=UTF-8 [ { "@" : "https://example.org/user123/upload/?s=erigsadaslgwu" } ]
In response to this request, the provided resource sends the following request:
POST /user123/upload/?s=erigsadaslgwu HTTP/1.1 Host: example.org Content-Type: video/mpeg …
The Customer's site begins receiving the live video stream from the user-agent.
When done recording, the user selects a "Stop" option from the video
indicator in the user-agent's chrome. The user-agent turns off the computer's
camera and microphone, thus terminating the live video stream. The video upload
ends as it reaches the end of the video stream. Further requests to the video
stream URL return 410
responses.
This appendix is non-normative.
The editors thank Adam Barth, Anne van Kesteren, Arthur Barstow, Arve Bersvendsen, Bryan Sullivan, Claes Nilsson, Dirk Pranke, Frederick Hirsch, Kenton Varda, Ian Hickson, Mark Miller, Max Froumentin, Robin Berjon, Thomas Roessler.