From 826aca3524be7ffd98587b7eed297101dbc17903 Mon Sep 17 00:00:00 2001 From: Richard Knoll Date: Thu, 10 Mar 2016 11:55:31 -0800 Subject: [PATCH] CB-10756: Adding sterner warnings about DATA_URL This closes #193 --- README.md | 68 +++++++++++++++++++++--------------------- jsdoc2md/TEMPLATE.md | 36 ++++++++++++---------- www/CameraConstants.js | 2 +- 3 files changed, 56 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index e71e364..6d175f0 100644 --- a/README.md +++ b/README.md @@ -73,20 +73,20 @@ Documentation consists of template and API docs produced from the plugin JS code * [camera](#module_camera) - * [.getPicture(successCallback, errorCallback, options)](#module_camera.getPicture) - * [.cleanup()](#module_camera.cleanup) - * [.onError](#module_camera.onError) : function - * [.onSuccess](#module_camera.onSuccess) : function - * [.CameraOptions](#module_camera.CameraOptions) : Object + * [.getPicture(successCallback, errorCallback, options)](#module_camera.getPicture) + * [.cleanup()](#module_camera.cleanup) + * [.onError](#module_camera.onError) : function + * [.onSuccess](#module_camera.onSuccess) : function + * [.CameraOptions](#module_camera.CameraOptions) : Object * [Camera](#module_Camera) - * [.DestinationType](#module_Camera.DestinationType) : enum - * [.EncodingType](#module_Camera.EncodingType) : enum - * [.MediaType](#module_Camera.MediaType) : enum - * [.PictureSourceType](#module_Camera.PictureSourceType) : enum - * [.PopoverArrowDirection](#module_Camera.PopoverArrowDirection) : enum - * [.Direction](#module_Camera.Direction) : enum + * [.DestinationType](#module_Camera.DestinationType) : enum + * [.EncodingType](#module_Camera.EncodingType) : enum + * [.MediaType](#module_Camera.MediaType) : enum + * [.PictureSourceType](#module_Camera.PictureSourceType) : enum + * [.PopoverArrowDirection](#module_Camera.PopoverArrowDirection) : enum + * [.Direction](#module_Camera.Direction) : enum * [CameraPopoverHandle](#module_CameraPopoverHandle) * [CameraPopoverOptions](#module_CameraPopoverOptions) @@ -249,7 +249,7 @@ Optional parameters to customize the camera settings. | Name | Type | Default | Description | | --- | --- | --- | --- | -| DATA_URL | number | 0 | Return base64 encoded string | +| DATA_URL | number | 0 | Return base64 encoded string. DATA_URL can be very memory intensive and cause app crashes or out of memory errors. Use FILE_URI or NATIVE_URI if possible | | FILE_URI | number | 1 | Return file uri (content://media/external/images/media/2 for Android) | | NATIVE_URI | number | 2 | Return native uri (eg. asset-library://... for iOS) | @@ -314,13 +314,7 @@ Matches iOS UIPopoverArrowDirection constants to specify arrow location on popov ## CameraPopoverOptions -iOS-only parameters that specify the anchor element location and arrow -direction of the popover when selecting images from an iPad's library -or album. -Note that the size of the popover may change to adjust to the -direction of the arrow and orientation of the screen. Make sure to -account for orientation changes when specifying the anchor element -location. +iOS-only parameters that specify the anchor element location and arrow direction of the popover when selecting images from an iPad's library or album. Note that the size of the popover may change to adjust to the direction of the arrow and orientation of the screen. Make sure to account for orientation changes when specifying the anchor element location. | Param | Type | Default | Description | @@ -363,21 +357,6 @@ window.onorientationchange = function() { #### Example -Take a photo and retrieve it as a Base64-encoded image: - - navigator.camera.getPicture(onSuccess, onFail, { quality: 50, - destinationType: Camera.DestinationType.DATA_URL - }); - - function onSuccess(imageData) { - var image = document.getElementById('myImage'); - image.src = "data:image/jpeg;base64," + imageData; - } - - function onFail(message) { - alert('Failed because: ' + message); - } - Take a photo and retrieve the image's file location: navigator.camera.getPicture(onSuccess, onFail, { quality: 50, @@ -392,6 +371,27 @@ Take a photo and retrieve the image's file location: alert('Failed because: ' + message); } +Take a photo and retrieve it as a Base64-encoded image: + + /** + * Warning: Using DATA_URL is not recommended! The DATA_URL destination + * type is very memory intensive, even with a low quality setting. Using it + * can result in out of memory errors and application crashes. Use FILE_URI + * or NATIVE_URI instead. + */ + navigator.camera.getPicture(onSuccess, onFail, { quality: 25, + destinationType: Camera.DestinationType.DATA_URL + }); + + function onSuccess(imageData) { + var image = document.getElementById('myImage'); + image.src = "data:image/jpeg;base64," + imageData; + } + + function onFail(message) { + alert('Failed because: ' + message); + } + #### Preferences (iOS) - __CameraUsesGeolocation__ (boolean, defaults to false). For capturing JPEGs, set to true to get geolocation data in the EXIF header. This will trigger a request for geolocation permissions if set to true. diff --git a/jsdoc2md/TEMPLATE.md b/jsdoc2md/TEMPLATE.md index 9260a3c..687b0fd 100644 --- a/jsdoc2md/TEMPLATE.md +++ b/jsdoc2md/TEMPLATE.md @@ -34,21 +34,6 @@ the system's image library. #### Example -Take a photo and retrieve it as a Base64-encoded image: - - navigator.camera.getPicture(onSuccess, onFail, { quality: 50, - destinationType: Camera.DestinationType.DATA_URL - }); - - function onSuccess(imageData) { - var image = document.getElementById('myImage'); - image.src = "data:image/jpeg;base64," + imageData; - } - - function onFail(message) { - alert('Failed because: ' + message); - } - Take a photo and retrieve the image's file location: navigator.camera.getPicture(onSuccess, onFail, { quality: 50, @@ -63,6 +48,27 @@ Take a photo and retrieve the image's file location: alert('Failed because: ' + message); } +Take a photo and retrieve it as a Base64-encoded image: + + /** + * Warning: Using DATA_URL is not recommended! The DATA_URL destination + * type is very memory intensive, even with a low quality setting. Using it + * can result in out of memory errors and application crashes. Use FILE_URI + * or NATIVE_URI instead. + */ + navigator.camera.getPicture(onSuccess, onFail, { quality: 25, + destinationType: Camera.DestinationType.DATA_URL + }); + + function onSuccess(imageData) { + var image = document.getElementById('myImage'); + image.src = "data:image/jpeg;base64," + imageData; + } + + function onFail(message) { + alert('Failed because: ' + message); + } + #### Preferences (iOS) - __CameraUsesGeolocation__ (boolean, defaults to false). For capturing JPEGs, set to true to get geolocation data in the EXIF header. This will trigger a request for geolocation permissions if set to true. diff --git a/www/CameraConstants.js b/www/CameraConstants.js index c2bbbf5..f4b0694 100644 --- a/www/CameraConstants.js +++ b/www/CameraConstants.js @@ -27,7 +27,7 @@ module.exports = { * @enum {number} */ DestinationType:{ - /** Return base64 encoded string */ + /** Return base64 encoded string. DATA_URL can be very memory intensive and cause app crashes or out of memory errors. Use FILE_URI or NATIVE_URI if possible */ DATA_URL: 0, /** Return file uri (content://media/external/images/media/2 for Android) */ FILE_URI: 1,