Bondi logo

The Bondi Camera Module: bondi.camera - Version 1.0

28 May 2009

Authors

© 2009 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

The camera API allows the use of device cameras. Cameras can be used for video recording and still pictures.

Table of Contents

Summary of Methods

InterfaceMethod
CameraSuccessCallbackvoid onSuccess(DOMString file)
CameraErrorCallbackvoid onError(CameraError error)
ViewFinderSuccessCallbackvoid onSuccess(DOMString uri)
ViewFinderErrorCallbackvoid onError(CameraError error)
CameraError
CameraResolution
CameraManagerCameraArray getCameras()
CameraFeatureArray getSupportedFeatureKeys()
FeatureValueArray getSupportedFeatureValues(unsigned short featureKey)
unsigned integer getMaximumFeatureValue(unsigned short featureKey)
unsigned integer getMinimumFeatureValue(unsigned short featureKey)
any getFeatureValue(unsigned short featureKey)
void setFeatureValue(unsigned short featureKey, any featureValue)
PendingOperation startViewFinderStreaming(ViewFinderSuccessCallback successCallback, ViewFinderErrorCallback errorCallback)
void stopViewFinderStreaming()
PendingOperation takePicture(CameraSuccessCallback successCallback, CameraErrorCallback errorCallback)
PendingOperation beginRecording(CameraSuccessCallback successCallback, CameraErrorCallback errorCallback)
void endRecording(CameraSuccessCallback successCallback, CameraErrorCallback errorCallback)

1. Introduction

The camera API allows for the capturing pictures and videos with the available cameras. Cameras available on the system are provided to the user and the preferred one can be selected based on the camera's name and desired resolution. To influence the camera's behavior, the API provides various configuration parameters, e.g., camera resolution, flash light, and zoom.

The configuration parameters can be filled with discrete and continuous values. Parameters, such as camera resolution can only take fixed value pairs, due to camera's physical limitations. On the other hand, parameters, such as (digital/optical) zoom can be set continuously between lower and upper limits.

The camera's video data is provided as a video stream to allow access to the media from any streaming client. This may be, for example, the upcoming HTML5 <video> tag or an embedded control. Thus, the embedded object is responsible for the relative positioning of the video content within the surrounding Web page. However, the streaming client may also be a stand-alone application.

The video stream, which is identified via an URI, is of no specific format (codec), but platform dependent. The handling, i.e., rendering of the video format is in scope of the client rendering the Web content or the standalone application.

1.1. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions provided is provided.

http://bondi.omtp.org/api/camera.get

Feature that allows for the detection of available cameras.

Device capabilities: camera.get

http://bondi.omtp.org/api/camera.show

Feature that allows for enabling a camera preview.

Device capabilities: camera.show

http://bondi.omtp.org/api/camera.hide

Feature that allows for disabling a camera preview.

Device capabilities: camera.hide

http://bondi.omtp.org/api/camera.capture

Feature that allows for capturing a picture from a selected camera.

Device capabilities: camera.captureio.file.write

http://bondi.omtp.org/api/camera.record

Feature that allows for capturing a video from a selected camera.

Device capabilities: camera.recordio.file.write

1.2. Device capabilities

camera.get

Retrieving camera hardware devices available on the device

camera.show

Providing a camera's video stream

camera.hide

Disabling providing a camera's video stream

camera.capture

Capturing an image by using a camera hardware device

camera.record

Recording a video by using a camera hardware device

io.file.write

Write directory or file

Security parameters:

  • name: Name of directory or file, in virtual filesystem, e.g. rootlocation/filename

2. Type Definitions

2.1. CameraArray

Array that contains the available camera objects. 

        typedef sequence<Camera> CameraArray;

2.2. FeatureArray

Array that contains keys that representing features supported by the camera device. 

        typedef sequence<unsigned short> FeatureArray;

2.3. FeatureValueArray

Array that contains allowed values according to a desired feature. 

        typedef sequence<any> FeatureValueArray;

3. Interfaces

3.1. CameraSuccessCallback

The camera API specific success callback. 

        [Callback] interface CameraSuccessCallback {
                void onSuccess([optional] in DOMString file);
        };

This callback defines the interface to use for all asynchronous methods of the camera API which make use of a success callback. The callback is called without any parameter if video capturing was started successfully or if an ongoing capture process was canceled. The callback is called with a file identifier (full filename) as input parameter if it is invoked as a result of taking a picture or when a recording has ended.

3.2. CameraErrorCallback

The camera API specific error callback. 

        [Callback] interface CameraErrorCallback {
                void onError(in CameraError error);
        };

This error callback defines the interface to use for all asynchronous methods of the camera API which are using an error callback. The callback is invoked with a CameraError object that describes the occurred error.

3.3. ViewFinderSuccessCallback

The callback for a successful viewfinder start. 

        [Callback] interface ViewFinderSuccessCallback {
                void onSuccess(in DOMString uri);
        };

This callback defines the interface to use for the asynchronous start method of the viewfinder start. The input parameter of the callback is a URI representing the multimedia stream of the user's camera that should be embedded into the Web page.

3.4. ViewFinderErrorCallback

The callback for a fault viewfinder start. 

        [Callback] interface ViewFinderErrorCallback {
                void onError(in CameraError error);
        };

This error callback defines the interface to use for the asynchronous method of the viewfinder start. The callback is invoked with a CameraError object that describes the occurred error in more detail.

3.5. CameraError

The camera errors defining error codes that are thrown if camera API specific errors occurred. 

        interface CameraError : GenericError {

                const unsigned short CAMERA_ALREADY_IN_USE_ERROR = 0;

                const unsigned short CAMERA_FEATURE_NOT_SUPPORTED_ERROR = 1;

                const unsigned short CAMERA_VIEWFINDER_SHOW_ERROR = 2;

                const unsigned short CAMERA_CAPTURE_ERROR = 3;

        };

This interface inherits from: GenericError

Constants

unsigned short CAMERA_ALREADY_IN_USE_ERROR

Error thrown when Camera already in use.

unsigned short CAMERA_FEATURE_NOT_SUPPORTED_ERROR

Error thrown when a Camera Feature is not supported

unsigned short CAMERA_VIEWFINDER_SHOW_ERROR

Error thrown if view finder streaming is not possible.

unsigned short CAMERA_CAPTURE_ERROR

Error thrown in event unpredicted error occurrs while a picture or video is being captured or if endRecording is called when no video is captured.

3.6. CameraResolution

This data type represents a possible camera resolution in pixels. 

        interface CameraResolution {

                attribute unsigned long horizontal;

                attribute unsigned long vertical;
        };

A camera may capture pictures and videos in different resolutions. This data type represents the allowed resolutions for a selected camera.

Camera.getAllowedValuesForFeature(camera.RESOLUTION_VIDEO) retrieves all supported video resolutions and Camera.getAllowedValuesForFeature(camera.RESOLUTION_PICTURE) retrieves all supported picture resolutions which can be used to set the desired capturing resolution by using camera.setFeatureValue(...). Camera.getFeatureValue(camera.RESOLUTION_VIDEO) and Camera.getFeatureValue(camera.RESOLUTION_PICTURE) can be used to retrieve the actual assigned resolutions.

Code example
 
        try {
                // Extract the current resolution
                var res = bondi.camera.getFeatureValue(bondi.camera.Camera.RESOLUTION_VIDEO);
                alert("Current video capturing resolution is: " + res.horizontal + "x" + res.vertical);
        }
        catch(e) { 
                alert(e);
        }

Attributes

unsigned long horizontal

The horizontal part of the resolution in pixels.

unsigned long vertical

The vertical part of the resolution in pixels.

3.7. CameraManager

Camera Manager that provides access to available cameras. 

        interface CameraManager {

                CameraArray getCameras()
                        raises(SecurityError);
        };

The camera manager provides access to the list of available cameras. The number and type of available cameras depends on the supported devices of the API implementations.

Code example
 
        try {
                var cameras = bondi.camera.getCameras();
                for (var i = 0; i  cameras.length; i++){
                        //select the desired camera by checking
                        //id, name, or supported features
                }
        }
        catch(e) {
                alert(e);
        }

Methods

getCameras

Returns representations of available cameras.

Signature
CameraArray getCameras();

The number of cameras that are accessible by the camera API depends on the number of available hardware devices as well as on the number of cameras that are supported by the implementation. To distinguish between multiple cameras the camera id and camera name properties can be used to select a desired device.

Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
API features
http://bondi.omtp.org/api/camera.get
Code example
 
        try {
                var cameras = bondi.camera.getCameras();
                for (var i = 0; i  cameras.length; i++){
                        //select the desired camera by checking
                        //id, name, or supported features
                }
        }
        catch(e) {
                alert(e);
        }

3.8. Camera

The camera interface allows to use features provided by a camera device. 

        interface Camera {

                const unsigned short QUALITY = 0;

                const unsigned short RESOLUTION_VIDEO = 1;

                const unsigned short RESOLUTION_PICTURE         = 2;

                const unsigned short ZOOM_LEVEL_OPTICAL = 3;

                const unsigned short ZOOM_LEVEL_DIGITAL = 4;

                const unsigned short BRIGHTNESS = 5;

                const unsigned short WHITE_BALANCE_MODE = 6;

                const unsigned short CONTRAST = 7;

                const unsigned short NIGHT_MODE = 8;

                const unsigned short FOCUS_MODE = 9;

                const unsigned short FOCUS = 10;

                const unsigned short FLASH = 11;

                const unsigned short LIGHT = 12;

                const unsigned short FRAME_RATE = 13;

                const unsigned short AUDIO = 14;

                readonly attribute unsigned short id;

                readonly attribute DOMString name;

                FeatureArray getSupportedFeatureKeys();

                FeatureValueArray getSupportedFeatureValues(in unsigned short featureKey)
                        raises(DeviceAPIError, CameraError);

                unsigned short getMaximumFeatureValue(in unsigned short featureKey)
                        raises(DeviceAPIError, CameraError);

                unsigned short getMinimumFeatureValue(in unsigned short featureKey)
                        raises(DeviceAPIError, CameraError);

                any getFeatureValue(in unsigned short featureKey)
                        raises(DeviceAPIError, CameraError);

                void setFeatureValue(in unsigned short featureKey, in any featureValue)
                        raises(DeviceAPIError, CameraError);

                PendingOperation startViewFinderStreaming(in ViewFinderSuccessCallback successCallback,
                                                                                                  in ViewFinderErrorCallback errorCallback)
                        raises(SecurityError, CameraError);

                void stopViewFinderStreaming()
                        raises(SecurityError);

                PendingOperation takePicture(in CameraSuccessCallback successCallback,
                                             in CameraErrorCallback errorCallback)
                        raises(SecurityError, DeviceAPIError, CameraError);

                PendingOperation beginRecording(in CameraSuccessCallback successCallback,
                                                in CameraErrorCallback errorCallback)
                        raises(SecurityError, DeviceAPIError, CameraError);

                void endRecording(in CameraSuccessCallback successCallback,
                                  in CameraErrorCallback errorCallback)
                        raises(DeviceAPIError);
        };

The camera interface abstracts a hardware camera device that is accessible by the camera manager. In addition to providing an API to control the normal camera functions for taking pictures and videos it manages standard camera properties. e.g., resolution to use, optical and digital zoom factors, flash, and light. By providing mechanisms to retrieve the allowed values for each property the values of each property can be safely configured.

To expose the current video of the camera's view finder, the API provides a video stream that can be accessed from any video client, e.g., by using HTML5 video tags or embedding other video clients in the web context.

Code example
        try {
                var cameras = bondi.camera.getCameras();
                if(cameras.length > 0) {
                        // access the first camera
                        var camera = cameras[0];
                        // use the camera
                }
        }
        catch(e) {
                alert(e);
        }

Constants

unsigned short QUALITY

Key for the quality property of captured pictures and videos.

Use camera.getAllowedValuesForFeature(bondi.camera.Camera.QUALITY) to get a list of supported values for the 'QUALITY' feature. Common quality values that may be presented to the user for selection are 'low', 'medium', and 'high'. At least 'low' and 'high' shall be provided by an implementation. The supported quality feature values must be a human readable and understandable term.

Quite often, the quality of video and picture data can be influenced by the use of different compression codecs, different compression rates, or by adjusting the video or picture resolutions. The API makes no assumptions about the codecs used, thus, it depends on the implementation.

Use camera.getFeatureValue(bondi.camera.Camera.QUALITY) to get the current camera quality and camera.setFeatureValue(bondi.camera.Camera.QUALITY, newQuality) to set a new value for the quality feature.

The default value is the first element in the list that is returned by camera.getAllowedValuesForFeature(bondi.camera.Camera.QUALITY). The provided value list for the quality feature should be in descending order beginning with the value for the highest quality at the first position of the returned array.

Code example
 
        try {
                // Extract the current quality value
                var quality = camera.getFeatureValue(bondi.camera.Camera.QUALITY);
                var qualities;
                for (var i = 0; i  quality.length; i++){
                        qualities = qualities + quality[i];
                }
                alert("Available qualities: " + qualities);
                // Set the current quality value to the first available
                // quality that should be the highest possible one.
                camera.setFeatureValue(bondi.camera.Camera.QUALITY, quality[0]);
        }
        catch(e) {
                alert(e);
        }
unsigned short RESOLUTION_VIDEO

Key for the video resolution feature.

Use camera.getAllowedValuesForFeature(bondi.camera.Camera.RESOLUTION_VIDEO) to get all supported video resolutions.

Use camera.getFeatureValue(bondi.camera.Camera.RESOLUTION_VIDEO) to get the current camera resolution for video records and camera.setFeatureValue(bondi.camera.Camera.RESOLUTION_VIDEO, newResolution) to set a new value for the feature 'RESOLUTION_VIDEO';

Default value is the first element in the list returned by camera.getAllowedValuesForFeature(bondi.camera.Camera.RESOLUTION_VIDEO).

Code example
 
        try {
                // Extract the current resolution
                var res = camera.getFeatureValue(bondi.camera.Camera.RESOLUTION_VIDEO);
                alert(res.horizontal + ", " + res.vertical);
                // Set the current resolution
                camera.setFeatureValue(bondi.camera.Camera.RESOLUTION_VIDEO, {horizontal: 120 , vertical: 160});
        }
        catch(e) { 
                alert(e);
        }
unsigned short RESOLUTION_PICTURE

Key for the picture resolution feature.

Use camera.getAllowedValuesForFeature(bondi.camera.Camera.RESOLUTION_PICTURE ) to get all supported picture resolutions.

Use camera.getFeatureValue(bondi.camera.Camera.RESOLUTION_PICTURE ) to get the current camera resolution for picture records and camera.setFeatureValue(bondi.camera.Camera.RESOLUTION_PICTURE , newResolution) to set a new value for the feature 'RESOLUTION_PICTURE ;

Default value is the first element in the list returned by camera.getAllowedValuesForFeature(bondi.camera.Camera.RESOLUTION_PICTURE ).

Code example
 
        try {
                // Extract the current resolution
                var res = camera.getFeatureValue(bondi.camera.Camera.RESOLUTION_PICTURE);
                alert(res.horizontal + ", " + res.vertical);
                // Set the current resolution
                camera.setFeatureValue(bondi.camera.Camera.RESOLUTION_PICTURE, {horizontal: 120 , vertical: 160});
        }
        catch(e) { 
                alert(e);
        }
unsigned short ZOOM_LEVEL_OPTICAL

Key for the optical zoom level feature.

Use camera.getMaximumFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_OPTICAL) to get the maximum possible optical zoom factor supported by the camera device and implementation and use camera.getMinimumFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_OPTICAL) to get the minimum possible supported optical zoom factor.

Use camera.getFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_OPTICAL) to get the current optical zoom level and camera.setFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_OPTICAL, new_zoom) to set a new value for the feature 'ZOOM_LEVEL_OPTICAL'.

The default value is the minimum optical zoom level that is commonly 1, which refers to no optical zoom.

Code example
        try {
                // Extract the zoom level
                var zoomLevel = camera.getFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_OPTICAL);
                // Sets a doubled zoom level
                camera.setFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_OPTICAL, 2 * zoomLevel);
        }
        catch(e) { 
                alert(e);
        }
unsigned short ZOOM_LEVEL_DIGITAL

Key for the digital zoom level feature.

Use camera.getMaximumFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_DEGITAL) to get the maximum possible digital zoom factor supported by the camera device and implementation and use camera.getMinimumFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_DIGITAL) to get the minimum possible supported digital zoom factor.

Use camera.getFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_DIGITAL) to get the current digital zoom level and camera.setFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_DIGITAL, new_zoom) to set a new value for the feature 'ZOOM_LEVEL_DIGITAL'.

The default value is the minimum digital zoom level that is commonly 1, which refers to a disabled digital zoom.

Code example
        try {
                // Extract the zoom level
                var zoomLevel = camera.getFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_DIGITAL);
                // Sets a doubled zoom level
                camera.setFeatureValue(bondi.camera.Camera.ZOOM_LEVEL_DIGITAL, 2 * zoomLevel);
        }
        catch(e) { 
                alert(e);
        }
unsigned short BRIGHTNESS

Key for the brightness feature.

Use camera.getMaximumFeatureValue(bondi.camera.Camera.BRIGHTNESS) to get the maximum brightness level and use camera.getMinimumFeatureValue(bondi.camera.Camera.BRIGHTNESS) to get the minimum brightness level.

Use camera.getFeatureValue(bondi.camera.Camera.BRIGHTNESS) to get the current brightness value and camera.setFeatureValue(bondi.camera.Camera.BRIGHTNESS, new_brightness) to set a new value for the brightness feature.

The default value is the minimal brightness value.

Code example
 
        try {
                // Extract the brightness value
                var brightness = camera.getFeatureValue(bondi.camera.Camera.BRIGHTNESS);
                // Set the camera brightness value
                camera.setFeatureValue(bondi.camera.Camera.BRIGHTNESS, 50);
        }
        catch(e) {
                alert(e);
        }
unsigned short WHITE_BALANCE_MODE

Key for the white balance mode feature.

Use camera.getAllowedValuesForFeature(bondi.camera.Camera.WHITE_BALANCE_MODE) to get a list of allowed values for the WHITE_BALANCE_MODE feature.

Use camera.getFeatureValue(bondi.camera.Camera.WHITE_BALANCE_MODE) to get the current white balance mode and camera.setFeatureValue(bondi.camera.Camera.WHITE_BALANCE_MODE, new_white_bal_mode) to set a new value for this feature.

The default value is the first entry in the list returned by camera.getAllowedValuesForFeature(bondi.camera.Camera.WHITE_BALANCE_MODE).

Code example
 
        try {
                // Extract the white balance mode value
                var white_bal_mode = camera.getFeatureValue(bondi.camera.Camera.WHITE_BALANCE_MODE);
                // Set the white balance mode: "auto" is always the first supported mode. 
                var supported_modes = camera.getAllowedValuesForFeature(bondi.camera.Camera.WHITE_BALANCE_MODE);
                camera.setFeatureValue(bondi.camera.Camera.WHITE_BALANCE_MODE, supported_modes[0]); 
        }
        catch(e) {
                alert(e);
        }
unsigned short CONTRAST

Key for the contrast feature.

Use camera.getMaximumFeatureValue(bondi.camera.Camera.CONTRAST) to get the maximum contrast value and use camera.getMinimumFeatureValue(bondi.camera.Camera.CONTRAST) to get the minimum contrast value.

Use camera.getFeatureValue(bondi.camera.Camera.CONTRAST) to get the current contrast value and camera.setFeatureValue(bondi.camera.Camera.CONTRAST, new_contrast) to set a new value for the feature 'CONTRAST'.

The default value is the minimal contrast value.

Code example
 
        try{
                // Extract the contrast value
                var contrast = camera.getFeatureValue(bondi.camera.Camera.CONTRAST);
                // Set the camera contrast value
                camera.setFeatureValue(bondi.camera.Camera.CONTRAST, 50);
        }
        catch(e) {
                alert(e);
        }
unsigned short NIGHT_MODE

Key for the night mode feature.

This key can be used to toggle the camera's night mode on (true) or off (false) if available.

Use camera.getAllowedValuesForFeature(bondi.camera.Camera.NIGHT_MODE) to get a list of allowed values for the night mode feature. In this case, the returned list contains two elements representing a disabled night mode (value is 'false') and a enabled night mode (value is 'true').

Use camera.getFeatureValue(bondi.camera.Camera.NIGHT_MODE) to get the current night mode and camera.setFeatureValue(bondi.camera.Camera.NIGHT_MODE, new_night_mode) to set a new night mode.

The default value for the night mode feature is false, resp., disabled.

Code example
 
        try {
                // gets current night mode
                var night_mode = camera.getFeatureValue(bondi.camera.Camera.NIGHT_MODE);
                // Switch on nightmode
                camera.setFeatureValue(bondi.camera.Camera.NIGHT_MODE, true);
        }
        catch(e) {
                alert(e);
        }
unsigned short FOCUS_MODE

Key for the focus mode feature.

Use camera.getAllowedValuesForFeature(bondi.camera.Camera.FOCUS_MODE) to get the list of allowed values for the focus mode feature. In this case, the returned list contains two elements representing an automatic focus mode (value is 'auto') and a manual focus mode (value is 'manual').

Use camera.getFeatureValue(bondi.camera.Camera.FOCUS_MODE) to get the current focus mode and camera.setFeatureValue(bondi.camera.Camera.FOCUS_MODE, new_focus_mode) to set a new focus mode.

The default value is 'manual'.

Code example
 
        try {
                // gets the current focus mode
                var focusMode = camera.getFeatureValue(bondi.camera.Camera.FOCUS_MODE);
                // set focus mode to 'auto'
                camera.setFeatureValue(bondi.camera.Camera.FOCUS_MODE, 'auto');
        }
        catch(e) {
                alert(e);
        }
unsigned short FOCUS

Feature key for setting the focus value manually.

The focus value can be manipulated to sharpen a viewed object that should be recorded or rendered. The set focus value is only used if the value of the 'FOCUS_MODE' feature is set to 'manual'.

Use camera.getMaximumFeatureValue(bondi.camera.Camera.FOCUS) to get the maximum focus value and use camera.getMinimumFeatureValue(bondi.camera.Camera.FOCUS) to get the minimum focus value.

Use camera.getFeatureValue(bondi.camera.Camera.FOCUS) to get the current focus value and camera.setFeatureValue(bondi.camera.Camera.FOCUS, new_focus) to set a new focus value.

The default value is the minimal focus value.

Code example
        try {
                // gets the current focus value
                var focus = camera.getFeatureValue(bondi.camera.Camera.FOCUS);
                // set focus to 30%
                camera.setFeatureValue(bondi.camera.Camera.FOCUS, 30);
        }
        catch(e) {
                alert(e);
        }
unsigned short FLASH

Feature key for setting the flash light feature value that enables or disables the camera's flash.

Use camera.getAllowedValuesForFeature(bondi.camera.Camera.FLASH) (returns {'auto','on','off'}) to get the list of allowed values of the flash light feature. In this case, the returned list contains three elements representing an forced flash light for every picture shot (value is 'on'), an disabled flash light (value is 'off'), and an automatic flash light mode (value is 'auto').

Use camera.getFeatureValue(bondi.camera.Camera.FLASH) to get the current value and camera.setFeatureValue(bondi.camera.Camera.FLASH, new_flash) to set a new flash value.

The default value is set to an automatic flash light mode.

Code example
        try{
                // get flash value
                var flash = camera.getFeatureValue(bondi.camera.Camera.FLASH);
                // Enable the camera flash
                camera.setFeatureValue(bondi.camera.Camera.FLASH, true)
        }
        catch(e) {
                alert(e);
        }
unsigned short LIGHT

Key for the light feature that turns on or off the camera's light.

Allowed values are true for switching the light on and false for turning of the light.

Use camera.getAllowedValuesForFeature(bondi.camera.Camera.LIGHT) to get the list of allowed values of the light feature. In this case, the returned list contains two values representing an enabled light (value is 'true') and a disabled light (value is 'false').

Use camera.getFeatureValue(bondi.camera.Camera.LIGHT) to get the current state of the camera light and camera.setFeatureValue(bondi.camera.Camera.LIGHT, new_light) to change the state of the camera light.

The default value is set to a disabled light.

Code example
        try {
                // get the current state of the camera light
                var light = camera.getFeatureValue(bondi.camera.Camera.LIGHT);
                // Switch on light
                camera.setFeatureValue(bondi.camera.Camera.LIGHT, true);
        }
        catch(e) {
                alert(e);
        }
unsigned short FRAME_RATE

Key for the frameRate feature that sets the preferred frame rate.

The frame rate feature allows to define the number of frames that should be recorded per second in video capturing mode,e.g. 24fps (24 frames per second).

Use camera.getAllowedValuesForFeature(bondi.camera.Camera.FRAME_RATE) to get a list of allowed values for the frame rate feature. In this case, the returned list contains all possible frame rates that may be integer or decimal values.

use camera.getFeatureValue(bondi.camera.Camera.FRAME_RATE) to get the current sequence time value and camera.setFeatureValue(bondi.camera.Camera.FRAME_RATE, frame_rate) to set a new value for the feature 'SEQUENCE_TIME'.

The default value is the first entry in the list returned by camera.getAllowedValuesForFeature(bondi.camera.Camera.FRAME_RATE) and should be a common value like 25fps or 30 fps if supported by the camera.

Code example
        try{
                // get the current frame rate
                var frameRate = camera.getFeatureValue(bondi.camera.Camera.FRAME_RATE);
                // set the max frame rate
                var allowedFrameRates = camera.getAllowedValuesForFeature(bondi.camera.Camera.FRAME_RATE);
                camera.setFeatureValue(bondi.camera.Camera.FRAME_RATE, allowedFrameRates[allowedFrameRates.length-1]);
        }
        catch(e){
                alert(e);
        }
unsigned short AUDIO

Key for the audio feature that turns on or off audio recording for video.

Use camera.getAllowedValuesForFeature(bondi.camera.Camera.AUDIO) to get a list of allowed values for the audio feature. In this case, the returned list contains two values representing enabled (value is 'true') and disabled (value is 'false') audio capturing.

Use camera.getFeatureValue(bondi.camera.Camera.AUDIO) to get the current state of the audio feature and camera.setFeatureValue(bondi.camera.Camera.AUDIO, new_audio) to change the state for the audio feature.

The default value is set to an enabled audio capturing mode if the device supports audio capturing. Otherwise, the default value is set to a disabled audio capturing.

Code example
        try {
                // gets the current state of feature audio
                var audio = camera.getFeatureValue(bondi.camera.Camera.AUDIO);
                // Switch off audio 
                camera.setFeatureValue(bondi.camera.Camera.AUDIO, false);
        }
        catch(e){
                alert(e);
        }

Attributes

[readonly] unsigned short id

Unique camera identifier.

The unique camera identifier allows for a system wide uniqely identificaton of the camera and may be used to select a specific camera if multiple cameras with the same name are available.

Code example
 
        var wantedCamera = "uniqueID";
        var myCamera;
        var cameras = bondi.camera.getCameras();
        for (var i = 0; i  cameras.length; i++){
                if (cameras[i].id == wantedCamera) 
                        myCamera = cameras[i];
        }
        // use the desired camera...
[readonly] DOMString name

A human readable label for the camera.

A human readable label for the camera that is exposed by the camera driver resp. the operating system, e.g., "Generic USB WebCam" or "Integrated Capturing Device" that can be used to select a specific camera if multiple cameras are available.

Code example
 
        var availableCameras;
        var cameras = bondi.camera.getCameras();
        for (var i = 0; i  cameras.length; i++){
                availableCameras += cameras[i].name + ", ";
        }
        alert("The following " + cameras.length + " cameras are available: " +
                availableCameras);

Methods

getSupportedFeatureKeys

Returns a list of keys represents all supported features by the camera device.

Signature
FeatureArray getSupportedFeatureKeys();

Depending on the available camera devices or on the implementation different camera features may be possible. To provide information about the properties that are useable getSupportedFeatureKeys can be used.

The returned list is a subset of the constants defined in the camera interface, e.g., bondi.camera.Camera.NIGHT_MODE, bondi.camera.Camera.FOCUS_MODE, etc.

Return value
a set of supported feature keys.
Code example
 
        var features = camera.getSupportedFeatureKeys();
        for(var i in features){
                alert(features[i]+" is supported");
        }
getSupportedFeatureValues

Returns a set of allowed values for a supported feature.

Signature
FeatureValueArray getSupportedFeatureValues(unsigned short featureKey);

Depending on the selected feature different discrete or continuous feature values are possible. GetSupportedFeatureValues is responsible to retrieve allowed values for features that using discrete values. Which values are allowed as well as the default values for a feature are described in the documentation of the according feature.

This function returns NULL If the feature's values are specified through an interval. In this case, camera.getMaximumFeatureValue and camera.getMinimumFeatureValue can be used to get the interval trhesholds of the allowed value range.

Parameters
  • featureKey: the key of the feature.
Return value
a list of allowed values if the feature is supported and the feature is an enumeration. If the feature is represented by an interval getMaximumFeatureValue resp. getMinimumFeatureValue should be used.
Exceptions
  • DeviceAPIError: INVALID_ARGUMENT if the feature key is invalid.
  • CameraError: CAMERA_FEATURE_NOT_SUPPORTED_ERROR if feature is not supported.
Code example
 
        try {
                // gets the allowed values for the light feature.
                var lightValues = camera.getSupportedFeatureValues(bondi.camera.Camera.LIGHT);
                for(var i in lightValues){
                        alert('allowed light value ['+i+'] = '+lightValues[i]);
                }
        }
        catch(e) {
                alert(e);
        }
getMaximumFeatureValue

Returns the maximum value of a feature.

Signature
unsigned short getMaximumFeatureValue(unsigned short featureKey);

Depending on the selected feature different discrete or continuous feature values are possible. GetMaximumFeatureValue is responsible to retrieve the maximal allowed value for continuous features. Which values are allowed as well as the default values for a feature are described in the documentation of the according feature.

This function returns NULL if the value range of the feature is not an interval. In this case, camera.getSupportedFeatureValues can be used to get a set of allowed values.

Parameters
  • featureKey: the key of the feature.
Return value
the maximum value for the given feature or null if the value range is an enumeration. In this case getAllowedValuesForFeature() can be used.
Exceptions
  • DeviceAPIError: INVALID_ARGUMENT if the feature key is invalid.
  • CameraError: CAMERA_FEATURE_NOT_SUPPORTED_ERROR if feature is not supported.
Code example
 
        try {
                // gets the allowed values for the feature contrast.
                var maxContrastValue = camera.getMaximumFeatureValue(bondi.camera.Camera.CONTRAST);
                var minContrastValue = camera.getMinimumFeatureValue(bondi.camera.Camera.CONTRAST);
                var contrast = camera.getFeatureValue(bondi.camera.Camera.CONTRAST);
                alert('current contrast value = '+contrast);
                alert('max contrast value = '+maxContrastValue);
                alert('min contrast value = '+minContrastValue);
        }
        catch(e) {
                alert(e);
        }
getMinimumFeatureValue

Returns the minimum value of a feature.

Signature
unsigned short getMinimumFeatureValue(unsigned short featureKey);

Depending on the selected feature different discrete or continuous feature values are possible. GetMinimumFeatureValue is responsible to retrieve the minimum allowed value for continuous features. Which values are allowed as well as the default values for a feature are described in the documentation of the according feature.

This function returns NULL if the value range of the feature is not an interval. In this case, camera.getSupportedFeatureValues can be used to get a set of allowed values.

Parameters
  • featureKey: the key of the feature.
Return value
the minimum value for the given feature or null if the value range is an enumeration. In this case getAllowedValuesForFeature() can be used.
Exceptions
  • DeviceAPIError: INVALID_ARGUMENT if the feature key is invalid.
  • CameraError: CAMERA_FEATURE_NOT_SUPPORTED_ERROR if feature is not supported.
Code example
 
        try {
                // gets the allowed values for the feature contrast.
                var maxContrastValue = camera.getMaximumFeatureValue(bondi.camera.Camera.CONTRAST);
                var minContrastValue = camera.getMinimumFeatureValue(bondi.camera.Camera.CONTRAST);
                var contrast = camera.getFeatureValue(bondi.camera.Camera.CONTRAST);
                alert('current contrast value = '+contrast);
                alert('max contrast value = '+maxContrastValue);
                alert('min contrast value = '+minContrastValue);
        }
        catch(e) {
                alert(e);
        }
getFeatureValue

Returns the current value of a supported feature.

Signature
any getFeatureValue(unsigned short featureKey);

Retriving the current feature value allows for verifying the settings and presenting them to the user. The returned value type depends on the desired feature.

Parameters
  • featureKey: the key of the feature.
Return value
the value of the feature
Exceptions
  • DeviceAPIError: INVALID_ARGUMENT if the feature key is invalid.
  • CameraError: CAMERA_FEATURE_NOT_SUPPORTED_ERROR if feature is not supported.
Code example
 
        try {
                var focusMode = getFeatureValue(bondi.camera.Camera.FOCUS_MODE);
                alert("Focus mode: "+focusMode);
        }
        catch(e) {
                alert(e);
        }
setFeatureValue

Sets the value of a supported feature.

Signature
void setFeatureValue(unsigned short featureKey, any featureValue);
Parameters
  • featureKey: the key of the feature.
  • featureValue: the value of the feature to set.
Exceptions
  • DeviceAPIError: INVALID_ARGUMENT if parameter 'featureKey' is unsupported, used 'featureValue' is not an allowed value, or the input parameters are invalid.
  • CameraError: CAMERA_FEATURE_NOT_SUPPORTED_ERROR if feature is not supported.
Code example
 
        try {
                var flash = setFeatureValue(bondi.camera.Camera.FLASH, true);
        }
        catch(e){
                // handle FeatureNotSupportedException or InvalidParameterException
                alert(e);
        }
startViewFinderStreaming

Start streaming a camera view finder video.

Signature
PendingOperation startViewFinderStreaming(ViewFinderSuccessCallback successCallback, ViewFinderErrorCallback errorCallback);

By starting a streaming server that streams the current camera view finder video any streaming client is able to embed the content in the web context. Thus, a preview can be shown to the user and the camera API can be used to take pictures or record videos while the user is watching the current preview. The used streaming codec depends on the platform.

If video streaming is already running the associated URI is returned.

Parameters
  • successCallback: The callback handler that is fired when the camera's viewfinder stream is available.
  • errorCallback: The callback handler that is fired when the camera's viewfinder cannot be streamed.
Return value
PendingOperation enabling the requester to cancel this request.
Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
  • CameraError: CAMERA_VIEWFINDER_SHOW_ERROR if view finder cannot be shown.
API features
http://bondi.omtp.org/api/camera.show
Code example
 
        try {
                // start the camera view finder streaming service
                var streamURI = camera.startViewFinderStream();
                //DOM manipulation of the according video tag
        }
        catch(e) {
                alert(e);
        }
stopViewFinderStreaming

Stops the local camera view finder streaming server.

Signature
void stopViewFinderStreaming();

A previously activated camera view finder stream is deactivated. As a result, the showing of a preview, e.g., within a HTML 5 video tag and other streaming clients is no longer possible. If this function is called when streaming is disabled the call will have no effect.

Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
API features
http://bondi.omtp.org/api/camera.hide
Code example
 
        // Stop the camera view finder stream
        camera.stopViewFinderStream();
takePicture

Requests the camera to capture a still image.

Signature
PendingOperation takePicture(CameraSuccessCallback successCallback, CameraErrorCallback errorCallback);

TakePicture requests the API capture a picture using the current configuration's supported features. The picture file is stored in the user's home folder if available. If no user folder is available on the host system, the implementation selects the storage path.

After the picture is taken, the passed in success callback is called and the user is provided with an identifier that points to the file of the captured picture. The scheme of the file identifier depends on the host system and may differ between multiple devices.

Picture capturing can be canceled by calling the cancel() operation of the PendingOperation output. This will result in the abort of the picture shot, wherefore no file is created in the filesystem. If a file was already created it is removed. A cancelation will result in no callback, neither successCallback nor errorCallback.

Parameters
  • successCallback: The callback handler that is fired when a picture or video has completed capture.
  • errorCallback: The callback handler that is fired when the recording has failed.
Return value
PendingOperation enabling the requester to cancel this request.
Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
  • DeviceAPIError: INVALID_ARGUMENT_ERROR if 'successCallback' or 'errorCallback' are missing.
  • CameraError: CAMERA_CAPTURE_ERROR if picture capturing cannot be started. CAMERA_ALREADY_IN_USE_ERROR if the camera is already in use.
API features
http://bondi.omtp.org/api/camera.capture
Code example
        // Show the camera viewfinder
        camera.startViewFinderStreaming();
        // Take a picture in 10 seconds (10000 milliseconds) to implement a selfTimer, resp., to set a self shot time
        setTimeout(function() { camera.takePicture(onCapture, onError); }, 10000);

        // this function handles the record notification
        function onCapture(file) {
                // Picture has been taken - did it work?
                // Display the filename to the user
                alert('Picture taken: ' + file);
        }
 
        // this function handles the error case of video recording
        function onError(error) {
                alert(error.code);
        };
Code example
        // This example shows the cancelation of a picture shot (due to an imaginary user input)!
        // take a picture immediatelly
        var operation = camera.takePicture(onCapture, onError);
        // due to a user input, the previously picture shot should be canceled
        if (operation.cancel()) { alert('no picture taken'); } else { alert('picture already taken'); }

        // this function handles the record notification
        function onCapture(file) {
                // Picture has been taken - did it work?
                // Display the filename to the user
                alert('Picture taken: ' + file);
        }
 
        // this function handles the error case of video recording
        function onError(error) {
                alert(error.code);
        };
Code example
        // the following example shows how a multishot mode may be implemented:
        var time = 500; // time between two frames in milliseconds
        var frames = 10; // 10 Frames 
        var files = [];
        var idx = 0;

        // error callback
        var error = function(error) {
                alert(error.code);
        };

        // success callback
        var success = function(file) {
                files[idx++] = file;
                if(idx  frames){
                        setTimeout(function() { camera.takePicture(success, error); }, time);
                }
        };

        // initial take picture
        camera.takePicture(success,error);
beginRecording

Requests the camera to begin with video capturing.

Signature
PendingOperation beginRecording(CameraSuccessCallback successCallback, CameraErrorCallback errorCallback);

BeginRecord requests the API to begin capturing a video by using the current configuration's supported features. The video file is stored in the user's home folder if available. If no home folder is available on the host system, the implementation selects the storage path.

After video capturing is started successfully, the passed in success callback is called to inform the user about a started video capturing. To end video capturing endRecording must be called.

Video capturing can be canceled by calling the cancel() operation of the PendingOperation output. This will result in the abort of the video shot, wherefore no file is created in the filesystem. If a file was already created it is removed. A cancelation will result in no callback, neither successCallback nor errorCallback.

Parameters
  • successCallback: The callback handler that is fired when a picture or video has completed capture.
  • errorCallback: The callback handler that is fired when the recording has failed.
Return value
PendingOperation enabling the requester to cancel this request.
Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
  • DeviceAPIError: INVALID_ARGUMENT_ERROR if 'successCallback' or 'errorCallback' are missing.
  • CameraError: CAMERA_CAPTURE_ERROR if the camera cannot start video recording or any other unpredictable error occurred while capturing CAMERA_ALREADY_IN_USE_ERROR if the camera is already in use.
API features
http://bondi.omtp.org/api/camera.record
Code example
        // NOTE: this example does not include exception handling (try-catch blocks)
        // Show the camera viewfinder
        camera.startViewFinderStreaming();
        // begin recording in 10 seconds (10000 milliseconds)
        setTimeout(function() { camera.beginRecording(onBeginRecording, onError); }, 10000);

        // this function handles the begin record notification
        function onBeginRecording() {
                // End the recording after 5 seconds (5000 milliseconds)
                setTimeout(function(){camera.endRecording(onEndRecording, onError);}, 5000);
        }
 
        // this function handles the end record notification
        function onEndRecording(file) {
                // Display the filepath to the user
                alert('Picture taken: ' + file);
        }
 
        // this function handles the error case of video recording
        function onError(error) {
                alert(error.code);
        }
Code example
        // This example shows the cancelation of a video record (due to an imaginary user input)!
        // record a video immediatelly
        var operation = camera.beginRecording(onCapture, onError);
        // due to a user input, the previously picture shot should be canceled
        if (operation.cancel()) { alert('no video recorded'); } else { alert('video already recorded'); }

        // this function handles the record notification
        function onCapture() { alert("record started"); }
 
        // this function handles the error case of video recording
        function onError(error) { alert(error.code); };
endRecording

Requests the camera API to stop an ongoing video capturing process.

Signature
void endRecording(CameraSuccessCallback successCallback, CameraErrorCallback errorCallback);

EndRecording stops an ongoing video capturing process and performs any needed post processing. After video capturing is successfully finished, the passed in success callback is called and the user is provided with an identifier that points to the file of the captured video. The scheme of the file identifier depends on the host system and may differ between multiple devices.

If endRecording is invoked while no video capturing process is running or any error occurs while stopping the video capturing the passed in error callback is invoked.

Parameters
  • successCallback: The callback handler that is fired when the video recording is stopped.
  • errorCallback: The callback handler that is fired when stop recording or post-processing raises any errors has failed.
Return value
PendingOperation enabling the requester to cancel running post-processing of video material.
Exceptions
  • DeviceAPIError: CAMERA_CAPTURE_ERROR if stopping video capturing is not possible because currently no video is captured. INVALID_ARGUMENT_ERROR if 'successCallback' or 'successCallback' are missing.
Code example
 
        // NOTE: this example doesn't include any exception handling (try-catch blocks)
        // Show the camera viewfinder
        camera.startViewFinderStreaming();
        // begin recording in 10 seconds (10000 milliseconds)
        setTimeout(function() { camera.beginRecording(onBeginRec, onError); }, 10000);

        // this function handles the begin record notification
        function onBeginRec() {
                // End the recording after 5 seconds (5000 milliseconds)
                setTimeout(function(){camera.endRecording(onEndRecording, onError);}, 5000);
        }
 
        // this function handles the end record notification
        function onEndRec(file) {
                // Display the filepath to the user
                alert('Picture taken: ' + file);
        }
 
        // this function handles the error case of video recording
        function onError(error) {
                alert(error.code);
        }