1/*
  2 *
  3 * Licensed to the Apache Software Foundation (ASF) under one
  4 * or more contributor license agreements.  See the NOTICE file
  5 * distributed with this work for additional information
  6 * regarding copyright ownership.  The ASF licenses this file
  7 * to you under the Apache License, Version 2.0 (the
  8 * "License"); you may not use this file except in compliance
  9 * with the License.  You may obtain a copy of the License at
 10 *
 11 *   http://www.apache.org/licenses/LICENSE-2.0
 12 *
 13 * Unless required by applicable law or agreed to in writing,
 14 * software distributed under the License is distributed on an
 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 16 * KIND, either express or implied.  See the License for the
 17 * specific language governing permissions and limitations
 18 * under the License.
 19 *
 20*/
 21
 22var argscheck = require('cordova/argscheck'),
 23    exec = require('cordova/exec'),
 24    Camera = require('./Camera');
 25    // XXX: commented out
 26    //CameraPopoverHandle = require('./CameraPopoverHandle');
 27
 28/**
 29 * @namespace navigator
 30 */
 31
 32/**
 33 * @exports camera
 34 */
 35var cameraExport = {};
 36
 37// Tack on the Camera Constants to the base camera plugin.
 38for (var key in Camera) {
 39    cameraExport[key] = Camera[key];
 40}
 41
 42/**
 43 * Callback function that provides an error message.
 44 * @callback module:camera.onError
 45 * @param {string} message - The message is provided by the device's native code.
 46 */
 47
 48/**
 49 * Callback function that provides the image data.
 50 * @callback module:camera.onSuccess
 51 * @param {string} imageData - Base64 encoding of the image data, _or_ the image file URI, depending on [`cameraOptions`]{@link module:camera.CameraOptions} in effect.
 52 * @example
 53 * // Show image
 54 * //
 55 * function cameraCallback(imageData) {
 56 *    var image = document.getElementById('myImage');
 57 *    image.src = "data:image/jpeg;base64," + imageData;
 58 * }
 59 */
 60
 61/**
 62 * Optional parameters to customize the camera settings.
 63 * * [Quirks](#CameraOptions-quirks)
 64 * @typedef module:camera.CameraOptions
 65 * @type {Object}
 66 * @property {number} [quality=50] - Quality of the saved image, expressed as a range of 0-100, where 100 is typically full resolution with no loss from file compression. (Note that information about the camera's resolution is unavailable.)
 67 * @property {module:Camera.DestinationType} [destinationType=FILE_URI] - Choose the format of the return value.
 68 * @property {module:Camera.PictureSourceType} [sourceType=CAMERA] - Set the source of the picture.
 69 * @property {Boolean} [allowEdit=true] - Allow simple editing of image before selection.
 70 * @property {module:Camera.EncodingType} [encodingType=JPEG] - Choose the  returned image file's encoding.
 71 * @property {number} [targetWidth] - Width in pixels to scale image. Must be used with `targetHeight`. Aspect ratio remains constant.
 72 * @property {number} [targetHeight] - Height in pixels to scale image. Must be used with `targetWidth`. Aspect ratio remains constant.
 73 * @property {module:Camera.MediaType} [mediaType=PICTURE] - Set the type of media to select from.  Only works when `PictureSourceType` is `PHOTOLIBRARY` or `SAVEDPHOTOALBUM`.
 74 * @property {Boolean} [correctOrientation] - Rotate the image to correct for the orientation of the device during capture.
 75 * @property {Boolean} [saveToPhotoAlbum] - Save the image to the photo album on the device after capture.
 76 * @property {module:CameraPopoverOptions} [popoverOptions] - iOS-only options that specify popover location in iPad.
 77 * @property {module:Camera.Direction} [cameraDirection=BACK] - Choose the camera to use (front- or back-facing).
 78 */
 79
 80/**
 81 * @description Takes a photo using the camera, or retrieves a photo from the device's
 82 * image gallery.  The image is passed to the success callback as a
 83 * Base64-encoded `String`, or as the URI for the image file.
 84 *
 85 * The `camera.getPicture` function opens the device's default camera
 86 * application that allows users to snap pictures by default - this behavior occurs,
 87 * when `Camera.sourceType` equals [`Camera.PictureSourceType.CAMERA`]{@link module:Camera.PictureSourceType}.
 88 * Once the user snaps the photo, the camera application closes and the application is restored.
 89 *
 90 * If `Camera.sourceType` is `Camera.PictureSourceType.PHOTOLIBRARY` or
 91 * `Camera.PictureSourceType.SAVEDPHOTOALBUM`, then a dialog displays
 92 * that allows users to select an existing image.
 93 *
 94 * The return value is sent to the [`cameraSuccess`]{@link module:camera.onSuccess} callback function, in
 95 * one of the following formats, depending on the specified
 96 * `cameraOptions`:
 97 *
 98 * - A `String` containing the Base64-encoded photo image.
 99 * - A `String` representing the image file location on local storage (default).
100 *
101 * You can do whatever you want with the encoded image or URI, for
102 * example:
103 *
104 * - Render the image in an `<img>` tag, as in the example below
105 * - Save the data locally (`LocalStorage`, [Lawnchair](http://brianleroux.github.com/lawnchair/), etc.)
106 * - Post the data to a remote server
107 *
108 * __NOTE__: Photo resolution on newer devices is quite good. Photos
109 * selected from the device's gallery are not downscaled to a lower
110 * quality, even if a `quality` parameter is specified.  To avoid common
111 * memory problems, set `Camera.destinationType` to `FILE_URI` rather
112 * than `DATA_URL`.
113 *
114 * __Supported Platforms__
115 *
116 * - Android
117 * - BlackBerry
118 * - Browser
119 * - Firefox
120 * - FireOS
121 * - iOS
122 * - Windows
123 * - WP8
124 * - Ubuntu
125 *
126 * More examples [here](#camera-getPicture-examples). Quirks [here](#camera-getPicture-quirks).
127 *
128 * @example
129 * navigator.camera.getPicture(cameraSuccess, cameraError, cameraOptions);
130 * @param {module:camera.onSuccess} successCallback
131 * @param {module:camera.onError} errorCallback
132 * @param {module:camera.CameraOptions} options CameraOptions
133 */
134cameraExport.getPicture = function(successCallback, errorCallback, options) {
135    argscheck.checkArgs('fFO', 'Camera.getPicture', arguments);
136    options = options || {};
137    var getValue = argscheck.getValue;
138
139    var quality = getValue(options.quality, 50);
140    var destinationType = getValue(options.destinationType, Camera.DestinationType.FILE_URI);
141    var sourceType = getValue(options.sourceType, Camera.PictureSourceType.CAMERA);
142    var targetWidth = getValue(options.targetWidth, -1);
143    var targetHeight = getValue(options.targetHeight, -1);
144    var encodingType = getValue(options.encodingType, Camera.EncodingType.JPEG);
145    var mediaType = getValue(options.mediaType, Camera.MediaType.PICTURE);
146    var allowEdit = !!options.allowEdit;
147    var correctOrientation = !!options.correctOrientation;
148    var saveToPhotoAlbum = !!options.saveToPhotoAlbum;
149    var popoverOptions = getValue(options.popoverOptions, null);
150    var cameraDirection = getValue(options.cameraDirection, Camera.Direction.BACK);
151
152    var args = [quality, destinationType, sourceType, targetWidth, targetHeight, encodingType,
153                mediaType, allowEdit, correctOrientation, saveToPhotoAlbum, popoverOptions, cameraDirection];
154
155    exec(successCallback, errorCallback, "Camera", "takePicture", args);
156    // XXX: commented out
157    //return new CameraPopoverHandle();
158};
159
160/**
161 * Removes intermediate image files that are kept in temporary storage
162 * after calling [`camera.getPicture`]{@link module:camera.getPicture}. Applies only when the value of
163 * `Camera.sourceType` equals `Camera.PictureSourceType.CAMERA` and the
164 * `Camera.destinationType` equals `Camera.DestinationType.FILE_URI`.
165 *
166 * __Supported Platforms__
167 *
168 * - iOS
169 *
170 * @example
171 * navigator.camera.cleanup(onSuccess, onFail);
172 *
173 * function onSuccess() {
174 *     console.log("Camera cleanup success.")
175 * }
176 *
177 * function onFail(message) {
178 *     alert('Failed because: ' + message);
179 * }
180 */
181cameraExport.cleanup = function(successCallback, errorCallback) {
182    exec(successCallback, errorCallback, "Camera", "cleanup", []);
183};
184
185module.exports = cameraExport;