Camera API Specification

This specification defines an API that provides scripted access to camera services in the hosting device.

Status of this document

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.

Introduction

The Camera API defines a high level interface for accessing the camera of a hosting device.

The following code extract illustrates how to work with a camera service in the hosting device:

Example of instantiating a service object to access the device camera.


    // Loads an instance of a camera interface identified by a service name

    // "device", an interface name "camera" and an interface version "1" or later. 

    var myCamera = org.w3c.device.load("device", "camera", "1");

Example of launching a device camera application and retrieving the pictures taken.


    // Creates a container div element and append it to the document body.

    var container = document.createElement("div");

    // The browser viewport width in pixels.

    var screenWidth = window.innerWidth;

    // Appends the container element into the document.

    document.body.appendChild(container);

    

    // A callback function which retrieves the pictures taken by the device

    // camera application and appends them into the container div element.  

    function callback(data, status, transactionId) {

        for (var i in data) {

            var img = document.createElement("img");

            img.src = data[i].uri;

            // If the image width exceeds that of the browser viewport,

            // the image to scaled to fit the screen keeping the aspect ratio intact.

            if (data[i].format.width > screenWidth) {

                img.style.width = screenWidth + "px";

                img.style.height = (data[i].format.height/data[i].format.width)*screenWidth + "px";    

            }

            container.appendChild(img);

        }

    }

    // Launch the device camera application and invokes the callback once the user exits

    // the camera application.

    transactionId = myCamera.startCamera(callback);

Example of retrieving image sizes and formats supported by hosting device camera.


    var summary;

    var formats = myCamera.supportedFormats;

    

    for (var key in formats) {

        summary += key + ": " + formats[key] + "\n";

    }

    
    alert(summary);

Scope

Use-Cases and Requirements

Use-Cases

Requirements

Security and privacy considerations

The API defined in this specification launches the camera application which allows the user to take pictures and provides a handle to the taken pictures. This information can potentially compromise user privacy and a conforming implementation of this specification must provide a mechanism that protects the user's privacy and this mechanism should ensure that such operations must be authenticated.

Privacy considerations for implementers of Contacts API

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.

Conformance requirements

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].

API Description

Camera interface

The Camera object can be used by scripts to provide programmatic access to the camera application of the hosting device.

The supportedFormats attribute represents an array of PictureData objects which contain image sizes and formats supported by the hosting device camera.

The startCamera() method takes the callback argument. When called it must immediately launch the device camera application and return a transactionId. When the user exits the camera application, the associated callback function must be invoked asynchronously, with an array of PictureData objects representing pictures takes between the time period of invoking the startCamera() and exiting the camera application.

PictureData interface

PictureData objects are regular ECMAScript objects that have the following properties:

The uri attribute attribute specifies the path to the picture file taken by camera as a Uniform Resource Identifier (URI) conforming to [RFC3986].

FormatData interface

FormatData objects are regular ECMAScript objects that have the following properties:

The type attribute represents the MIME type of the captured image. For example, a valid MIME type for JPEG images is image/jpeg.

Exception handling

On error, the APIs throw DeviceException with an informative error code. The DeviceException interface and error constants are defined in Appendix A.