1 /*
2 * Sybase Hybrid App version 2.3
3 *
4 * Camera.js
5 * This file will not be regenerated, so it is possible to modify it, but it
6 * is not recommended.
7 *
8 * Copyright (c) 2012 Sybase Inc. All rights reserved.
9 */
10
11 /* The feature comment is necessary at the class level for the custom template to work.
12 */
13 /**
14 * The namespace for the Hybrid Web Container javascript
15 * @namespace
16 * @feature Camera
17 */
18 hwc = (typeof hwc === "undefined" || !hwc) ? {} : hwc; // SUP 'namespace'
19
20 (function(hwc, window, undefined) {
21
22 /**
23 * An array that holds all possible option codes for use with getPicture()
24 * @private
25 */
26 hwc.PictureOption = [];
27
28 /**
29 * @memberOf hwc.PictureOption
30 */
31 hwc.PictureOption.SourceType = {
32 /**
33 * Constant that specifies the built-in camera as the image source for selecting the image using the {@link hwc.getPicture} method.
34 * @memberOf hwc.PictureOption.SourceType
35 */
36 CAMERA: 1, // Specifies the built-in camera as the image source where image content is not persisted by the device
37 /**
38 * Constant that specifies the photo library as the image source
39 * @memberOf hwc.PictureOption.SourceType
40 */
41 PHOTOLIBRARY: 2, // Specifies the photo library as the image source where image content is already persisted on the device
42 /**
43 * Constant that specifies the built-in camera and the photo library be used as an image source for selecting the image using the {@link hwc.getPicture} method.
44 * @memberOf hwc.PictureOption.SourceType
45 */
46 BOTH: 3 // Specifies the built-in camera as the image source where image content is persisted by the device
47 };
48
49 /**
50 * @memberOf hwc.PictureOption
51 */
52 hwc.PictureOption.DestinationType = {
53 /**
54 * Use this constant to specify that base64 encoded image data be returned by the {@link hwc.getPicture} method.
55 * @memberOf hwc.PictureOption.DestinationType
56 * @deprecated
57 */
58 IMAGE_DATA: 0, // Returns base64 encoded string (deprecated)
59 /**
60 * Use this constant to specify that the image URI be returned by the {@link hwc.getPicture} method.
61 * @memberOf hwc.PictureOption.DestinationType
62 */
63 IMAGE_URI: 1 // Returns uniform reference identifier for the image
64 };
65
66 /**
67 * Open a platform-specific application allowing the user to capture an image
68 * using the built-in camera.
69 * @deprecated
70 */
71 hwc.PictureOption.CAMERA = hwc.PictureOption.SourceType.CAMERA;
72
73 /**
74 * Open a platform-specific application allowing the user to select an
75 * existing picture from a gallery.
76 * @deprecated
77 */
78 hwc.PictureOption.PHOTOLIBRARY = hwc.PictureOption.SourceType.PHOTOLIBRARY;
79
80 /**
81 * An array that holds all possible error codes
82 */
83 hwc.PictureError = [];
84
85 /**
86 * Constant indicating that the {@link hwc.getPicture} method was successful.
87 * @memberOf hwc
88 */
89 hwc.PictureError.NO_ERROR = 0;
90
91 /**
92 * Constant indicating that the {@link hwc.getPicture} method is not implemented, camera not present, etc.
93 * @memberOf hwc
94 */
95 hwc.PictureError.NOT_SUPPORTED = -1;
96
97 /**
98 * Constant indicating that the {@link hwc.getPicture} method has been invoked, but has not completed yet.
99 * @memberOf hwc
100 */
101 hwc.PictureError.IN_PROGRESS = -2;
102
103 /**
104 * Constant indicating that the user has cancelled the {@link hwc.getPicture} invocation.
105 * @memberOf hwc
106 */
107 hwc.PictureError.USER_REJECT = -3;
108
109 /**
110 * Constant indicating that the supplied options were not recognized by the {@link hwc.getPicture} method
111 * @memberOf hwc
112 */
113 hwc.PictureError.BAD_OPTIONS = -4;
114
115 /**
116 * Constant indicating that the returned image size was too large to be handled by JavaScript.
117 * @memberOf hwc
118 */
119 hwc.PictureError.TOO_LARGE = -5;
120
121 /**
122 * Constant indicating that the an unknown error occured during the execution of {@link hwc.getPicture} method.
123 * @memberOf hwc
124 */
125 hwc.PictureError.UNKNOWN = -6;
126
127 /**
128 * A namespace for our private use
129 * @private
130 */
131 var _Picture = new function() {}; // private object '_Picture' within 'hwc'
132
133 /**
134 * Requests retrieval of a picture asynchronously.
135 *
136 * @param {anonymous.onGetPictureError} onGetPictureError Function to be invoked if the attempt to get
137 * a picture fails. err will be one of the PictureError codes.
138 * @param {anonymous.onGetPictureSuccess} onGetPictureSuccess Function to be invoked if a picture is
139 * successfully retrieved. response will either be a Base64-encoded JPG string or a URI.
140 * @param {anonymous.PictureOptions} options the options to control the sourceType and destinationType.
141 * @feature Camera
142 * @memberOf hwc
143 * @public
144 * @example
145 * // Error handler. will be invoked asynchronously.
146 * fail = function(errorCode){
147 * // handle error code and take appropriate action.
148 * }
149 * // Success handler. will be invoked asynchronously.
150 * success = function(fileName, content){
151 * // handle the content. content may be a location or base64 encoded string that is
152 * // determined by the options passed to the destinationType argument.
153 * }
154 *
155 * getPicture(fail,
156 * success,
157 * { sourceType: PictureOption.SourceType.CAMERA,
158 * destinationType: PictureOption.DestinationType.IMAGE_URI
159 * });
160 */
161 hwc.getPicture = function(onGetPictureError, onGetPictureSuccess, options)
162 {
163 hwc.traceEnteringMethod("hwc.getPicture");
164 try {
165 // Return if callback functions are not provided
166 if (typeof onGetPictureError !== 'function' ||
167 typeof onGetPictureSuccess !== 'function') {
168 return;
169 }
170
171 if ("_onGetPictureSuccess" in _Picture &&
172 _Picture._onGetPictureSuccess !== null) {
173 // Already requested but not yet complete
174 onGetPictureError(hwc.PictureError.IN_PROGRESS);
175 return;
176 }
177
178 _Picture._onGetPictureError = onGetPictureError;
179 _Picture._onGetPictureSuccess = onGetPictureSuccess;
180
181 // Convert options parameter to object notation if number type and return image data to preserve behavior
182 // of previous release
183 if (typeof options === 'number') {
184 options = { destinationType: hwc.PictureOption.DestinationType.IMAGE_DATA,
185 sourceType: options
186 };
187 }
188
189 // Convert options object to serialized JSON text in preparation for submission to the container
190 options = JSON.stringify(options);
191
192 if (hwc.isWindowsMobile())
193 {
194 hwc.getDataFromContainer("getPicture", "PictureOptions=" + encodeURIComponent(options));
195 }
196 else if (hwc.isIOS())
197 {
198 // Only difference between iOS and WindowsMobile above is the leading '&'
199 hwc.getDataFromContainer("getPicture", "&PictureOptions=" + encodeURIComponent(options));
200 }
201 else
202 {
203 _HWC.getPicture(options);
204 }
205 } finally {
206 hwc.traceLeavingMethod("hwc.getPicture");
207 }
208 };
209
210 /**
211 * (Internal) Invoked asynchronously when the image arrives.
212 *
213 * @private
214 * @param result The PictureError code, or PictureError.NO_ERROR for
215 * success.
216 * @param {string} filename Filename corresponding to the image.
217 * @param {string} imageData Base64-encoded String containing the image data. Undefined
218 * if the result parameter indicates an error or the image URI was requested.
219 * @param {string} imageUri Uniform resource indicator of the image resource. Undefined
220 * if the result parameter indicates an error or the image data was requested.
221 */
222 _Picture._getPictureComplete = function(result, fileName, imageData, imageUri) {
223 var response, successFunc, errorFunc;
224
225 hwc.traceEnteringMethod("_Picture._getPictureComplete");
226 try {
227 successFunc = _Picture._onGetPictureSuccess;
228 errorFunc = _Picture._onGetPictureError;
229
230 _Picture._onGetPictureSuccess = null;
231 _Picture._onGetPictureError = null;
232
233 if (result === hwc.PictureError.NO_ERROR) {
234 if (imageData) {
235 // For WM client, the picture data is too big to be passed from url, so only
236 // the unique key is sent from container to JavaScript. JavaScript needs to send
237 // another xmlhttprequest to fetch the actual data
238 if (hwc.isWindowsMobile()) {
239 response = hwc.getDataFromContainer("getpicturedata", "pictureid=" + imageData);
240 successFunc(fileName, response);
241 } else {
242 successFunc(fileName, imageData);
243 }
244 } else if (imageUri) {
245 successFunc(fileName, imageUri);
246 } else {
247 errorFunc(hwc.PictureError.UNKNOWN);
248 }
249 } else {
250 errorFunc(result);
251 }
252 } finally {
253 hwc.traceLeavingMethod("_Picture._getPictureComplete");
254 }
255 };
256
257 window._Picture = _Picture;
258 })(hwc, window);
259
260
261 /**
262 * Used to group anonymous objects and callback functions used as method parameters. Methods and fields in this
263 * namespace cannot be instantiated. Used for API docs generation only.
264 * @namespace
265 */
266 anonymous = (typeof anonymous === "undefined" || !anonymous) ? {} : anonymous; // SUP 'namespace'
267
268 /**
269 * User provided function that is invoked when the {@link hwc.getPicture} function fails.
270 *
271 * @name anonymous.onGetPictureError
272 * @param {integer} err the error code returned. Possible values are
273 * <ol>
274 * <li>PictureError.NO_ERROR = 0;</li>
275 * <li>PictureError.NOT_SUPPORTED = -1; getPicture() not implemented, camera not present,</li>
276 * <li>PictureError.IN_PROGRESS = -2; getPicture() has already been requested but has not yet completed.</li>
277 * <li>PictureError.USER_REJECT = -3; the user has canceled the request.</li>
278 * <li>PictureError.BAD_OPTIONS = -4; supplied options were not recognized.</li>
279 * <li>PictureError.TOO_LARGE = -5; the returned image size was too large to be handled by JavaScript</li>
280 * <li>PictureError.UNKNOWN = -6; an unknown error occurred.</li>
281 * </ol>
282 * @feature Camera
283 * @function
284 */
285
286 /**
287 * User provided function that will be invoked when the {@link hwc.getPicture} function is successful.
288 *
289 * @name anonymous.onGetPictureSuccess
290 *
291 * @param {string} filename file name of the image
292 * @param {string} response the response will be either a Base64-encoded JPG string or a URI depending on the options passed to
293 * the {@link hwc.getPicture} function.
294 * <ul>
295 * <li> if options.destinationType == PictureOption.DestinationType.IMAGE_URI, response is an uniform reference identifier for the image. onGetPictureSuccess(fileName, imageURI)</li>
296 * <li> if options.destinationType == PictureOption.DestinationType.IMAGE_DATA, response is a Base64-encoded string. onGetPictureSuccess(fileName, imageData )</li>
297 * </ul>
298 * @function
299 */
300
301 /**
302 * Options object that is used with the {@link hwc.getPicture} method. Contains 2 fields that can be specified.
303 *
304 * <ul>
305 * <li> sourceType: One of {@link hwc.Picture.SourceType} values </li>
306 * <li> destinationType: One of {@link hwc.Picture.DestinationType} values </li>
307 * </ul>
308 * @name anonymous.PictureOptions
309 * @see hwc.getPicture for an example.
310 */