Camera API Specification

Abstract

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.

Table of contents

• 1. Introduction
• 2. Scope
• 3. Use-Cases and Requirements
  • 3.1 Use-Cases
  • 3.2 Requirements
• 4. Security and privacy considerations
  • 4.1 Privacy considerations for implementers of the device camera API
  • 4.2 Privacy considerations for recipients of device camera service
• 5. Conformance requirements
• 6. API Description
  • 6.1 Camera interface
  • 6.2 PictureData interface
  • 6.3 FormatData interface
  • 6.4 Exception handling
• References

Introduction

This section is non-normative.

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:

    // 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");
    

    // 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);
    

    var summary;
    var formats = myCamera.supportedFormats;
    
    for (var key in formats) {
        summary += key + ": " + formats[key] + "\n";
    }
    
    alert(summary);
    

Scope

This section is non-normative.

This specification is limited to [define scope].

Use-Cases and Requirements

Use-Cases

To be written ...

Requirements

• Camera API must allow an application to launch the camera application in the hosting device and show the camera user interface.
• Camera API must allow an application to retrieve all captured pictures from the launched camera application when it is closed.
• Camera API must allow an application to query image formats and sizes supportedby the hosting device camera.

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.

  interface Camera {
    // Attributes
    readonly attribute sequence<FormatData> supportedFormats;
    // Methods
    int startCamera(in CameraCallback callback);
  };
        
  interface CameraCallback {
    void handleEvent(in sequence<PictureData> pictures, 
                     in int status,
                     in int transactionId);
  };
  

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:

  interface PictureData { 
     attribute DOMString      uri; 
     attribute FormatData     format;
  };
  

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

The format attribute represents the picture FormatData object.

FormatData interface

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

  interface FormatData { 
     attribute DOMString type; 
     attribute int	  height;
     attribute int	  width;
  };
  

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

The height attribute represents height of the image in pixels.

The width attribute represents width of the image in pixels.

Exception handling

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

References

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels.

[RFC3986]

Uniform Resource Identifier (URI): Generic Syntax.

[WebIDL]

Web IDL.