1 /*
2 * Sybase PhoneGap AppLog plugin
3 *
4 * applog.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) 2013 Sybase Inc. All rights reserved.
9 */
10
11 /**
12 * The namespace for AppLog plugin
13 * @namespace
14 */
15 AppLog = (typeof AppLog === "undefined" || !AppLog) ? {} : AppLog; // 'namespace'
16
17 (function(AppLog, window, undefined) {
18 /**
19 * Constant indicating the operation failed with unknown error. Used in {@link anonymous.AppLogErrorCallbackParameter}.
20 * @type number
21 */
22 AppLog.ERR_UNKNOWN = -1;
23
24 /**
25 * Constant indicating an app log entry is associated with an unknown event. Used in {@link AppLog.LogEntry}.
26 * @type number
27 */
28 AppLog.STATUS_EVENT_UNKNOWN = 1;
29
30 /**
31 * Constant indicating an app log entry is associated with starting the client connection to the SUP server. Used in {@link AppLog.LogEntry}.
32 * @type number
33 */
34 AppLog.STATUS_EVENT_STARTUP = 2;
35
36 /**
37 * Constant indicating an app log entry is associated with shutting down the client connection to the SUP server. Used in {@link AppLog.LogEntry}.
38 * @type number
39 */
40 AppLog.STATUS_EVENT_SHUTDOWN = 3;
41
42 /**
43 * Constant indicating an app log entry is associated with restarting the client connection to the SUP server. Used in {@link AppLog.LogEntry}.
44 * @type number
45 */
46 AppLog.STATUS_EVENT_RESTART = 4;
47
48 /**
49 * Constant indicating an app log entry is associated with the client successfully connecting to the SUP server. Used in {@link AppLog.LogEntry}.
50 * @type number
51 */
52 AppLog.STATUS_EVENT_CONNECTED = 5;
53
54 /**
55 * Constant indicating an app log entry is associated with the client losing connection to the SUP server. Used in {@link AppLog.LogEntry}.
56 * @type number
57 */
58 AppLog.STATUS_EVENT_DISCONNECTED = 6;
59
60 /**
61 * Constant indicating an app log entry is associated with the client going into flight mode. Used in {@link AppLog.LogEntry}.
62 * @type number
63 */
64 AppLog.STATUS_EVENT_FLIGHT_MODE = 7;
65
66 /**
67 * Constant indicating an app log entry is associated with the client going out of network. Used in {@link AppLog.LogEntry}.
68 * @type number
69 */
70 AppLog.STATUS_EVENT_OUT_OF_NETWORK = 8;
71
72 /**
73 * Constant indicating an app log entry is associated with the client waiting to connect to the SUP server. Used in {@link AppLog.LogEntry}.
74 * @type number
75 */
76 AppLog.STATUS_EVENT_WAITING_TO_CONNECT = 9;
77
78 /**
79 * Constant indicating an app log entry is associated with the client losing connection to the SUP server due to roaming. Used in {@link AppLog.LogEntry}.
80 * @type number
81 */
82 AppLog.STATUS_EVENT_DISCONNECTED_ROAMING = 10;
83
84 /**
85 * Constant indicating an app log entry is associated with the client losing connection to the SUP server due to low storage. Used in {@link AppLog.LogEntry}.
86 * @type number
87 */
88 AppLog.STATUS_EVENT_DISCONNECTED_LOW_STORAGE = 11;
89
90 /**
91 * Constant indicating an app log entry is associated with the client starting registration. Used in {@link AppLog.LogEntry}.
92 * @type number
93 */
94 AppLog.STATUS_EVENT_REGISTRATION_STARTED = 12;
95
96 /**
97 * Constant indicating an app log entry is associated with the client receiving a notification. Used in {@link AppLog.LogEntry}.
98 * @type number
99 */
100 AppLog.STATUS_EVENT_NOTIFICATION_RECEIVED = 13;
101
102 /**
103 * Constant indicating an app log entry is associated with a default app being set from the server. Used in {@link AppLog.LogEntry}.
104 * @type number
105 */
106 AppLog.STATUS_EVENT_SET_DEFAULT_ITEM = 14;
107
108 /**
109 * Constant indicating an app log entry is associated with a default app being unset from the server. Used in {@link AppLog.LogEntry}.
110 * @type number
111 */
112 AppLog.STATUS_EVENT_UNSET_DEFAULT_ITEM = 15;
113
114 /**
115 * This object represents a log entry.
116 *
117 * @class
118 * @public
119 * @memberOf AppLog
120 * @param {number} logDate The date the log entry was recorded, in milliseconds since January 1, 1970, 00:00:00 GMT.
121 * @param {number} event The event ID of the log entry (will be one of the AppLog status events, or possibly a custom value).
122 * @param {string} msg The message of the log entry.
123 */
124 AppLog.LogEntry = function ( logDate, event, msg ) {
125 this.date = logDate;
126 this.statusCode = event;
127 this.message = msg;
128 };
129
130 /**
131 * Call this function to get an array of {@link AppLog.LogEntry} objects. There will be one
132 * {@link AppLog.LogEntry} object for each line in the app log.
133 *
134 * @public
135 * @memberOf AppLog
136 * @param {anonymous.getLogEntriesSuccessCallback} successCB The callback function that will receive the asynchronous
137 * callback with the log entries.
138 * @param {anonymous.getLogEntriesErrorCallback} errorCB The callback function that will be invoked on errors.
139 *
140 * @example
141 * // A global function called with the log entries.
142 * function onLogEntriesSuccessCallback(data) {
143 * for ( var i = 0; i < data.length; i++ )
144 * {
145 * var logEntry = data[ i ];
146 * alert('Log entry ' + ( i + 1 ) + ':\n' +
147 * 'Date (ms): ' + logEntry.date + '\n' +
148 * 'Status code: ' + logEntry.statusCode + '\n' +
149 * 'Message: ' + logEntry.message
150 * );
151 * }
152 * }
153 *
154 * // A global function called if there is an error retrieving log entries.
155 * function onLogEntriesFailureCallback(error) {
156 * alert('Error retrieving log entries: ' + error);
157 * }
158 *
159 * // Get the log entries
160 * AppLog.getLogEntries(onLogEntriesSuccessCallback, onLogEntriesFailureCallback);
161 */
162 AppLog.getLogEntries = function( successCB, errorCB ) {
163 try
164 {
165 cordova.exec( successCB, errorCB, "AppLog", "getLogEntries", [] );
166 }
167 catch (ex)
168 {
169 setTimeout( errorCB({errorCode : AppLog.ERR_UNKNOWN, description : ex.message}), 0 );
170 }
171 }
172
173 /**
174 * Registers a log listener.
175 *
176 * @public
177 * @memberOf AppLog
178 * @param {anonymous.startOrStopLogListenerSuccessCallback} successCB A callback function that will be invoked
179 * if the log listener is successfully registered.
180 * @param {anonymous.startOrStopLogListenerErrorCallback} errorCB A callback function that will be invoked if there
181 * is an error registering the log listener.
182 * @param {anonymous.logListener} logListener The callback to register. This will be invoked when new entries are added to the log.
183 * @param {Object} [containingObject] Object containing the definition for logListener. If a log listener callback function
184 * references variables in its containing object, then the containing object should be passed to this function.
185 *
186 * @example
187 * // This example shows how to use this function with a globally-scoped logListener.
188 * // A global function called by the log listener.
189 * var doSomething = function()
190 * {
191 * alert("this gets displayed when there is a new log entry.");
192 * }
193 *
194 * // The log listener callback function that will be passed to AppLog.startLogListener.
195 * // This function will be invoked whenever there is a new log entry.
196 * var logListener = function( date, statusCode, message )
197 * {
198 * doSomething();
199 * }
200 *
201 * function onStartLogListenerSuccessCallback() {
202 * // Do something here after listener has been added
203 * }
204 *
205 * function onStartLogListenerFailureCallback(error) {
206 * // React to error here
207 * }
208 *
209 * // Add the log listener.
210 * AppLog.startLogListener( onStartLogListenerSuccessCallback,
211 * onStartLogListenerFailureCallback,
212 * logListener );
213 *
214 * @example
215 * // This example shows how to use this function with a logListener contained in an object.
216 * // logListenerManager is an object that will contain the listener callback as well
217 * // as a function that will be invoked from the listener callback function.
218 * var logListenerManager = {};
219 *
220 * // This is a function that is called from the listener callback.
221 * logListenerManager.doSomething = function()
222 * {
223 * alert("this gets displayed when there is a new log entry.");
224 * }
225 *
226 * // This is the listener callback that will be passed to AppLog.startLogListener.
227 * // Since a variable is referenced from the containing object, the containing object
228 * // will need to be passed to AppLog.startLogListener.
229 * logListenerManager.listener = function( date, statusCode, message )
230 * {
231 * this.doSomething();
232 * }
233 *
234 * function onStartLogListenerSuccessCallback() {
235 * // Do something here after listener has been added
236 * }
237 *
238 * function onStartLogListenerFailureCallback(error) {
239 * // React to error here
240 * }
241 *
242 * // Pass both the listener callback and the containing object.
243 * AppLog.startLogListener( onStartLogListenerSuccessCallback,
244 * onStartLogListenerFailureCallback,
245 * logListenerManager.listener,
246 * logListenerManager );
247 */
248 AppLog.startLogListener = function( successCB, errorCB, logListener, containingObject ) {
249 try
250 {
251 if ( !logListener || ( typeof logListener !== "function" ) )
252 {
253 throw new Error( "AppLog.startLogListener Error: logListener is not a function" );
254 }
255
256 var newListener = new AppLog.logListenerCallBack( logListener, containingObject );
257 AppLog.logListeners_internal.push( newListener );
258 if ( AppLog.logListeners_internal.length === 1 )
259 {
260 cordova.exec( successCB, errorCB, "AppLog", "startLogListener", [] );
261 }
262 else
263 {
264 setTimeout( successCB(), 0 );
265 }
266 }
267 catch (ex)
268 {
269 setTimeout( errorCB( {errorCode : AppLog.ERR_UNKNOWN, description : ex.message} ), 0 ) ;
270 }
271 }
272
273 /**
274 * Removes a log listener. This function should be called with identical parameters that were used
275 * when adding the log listener with {@link AppLog.startLogListener}.
276 *
277 * @param {anonymous.startOrStopLogListenerSuccessCallback} successCB A callback function that will be invoked
278 * if the log listener is successfully removed.
279 * @param {anonymous.startOrStopLogListenerErrorCallback} errorCB A callback function that will be invoked if there
280 * is an error removing the log listener.
281 * @param {anonymous.logListener} logListener The callback that was added with {@link AppLog.startLogListener}.
282 * @param {Object} [containingObject] Object containing the definition for logListener.
283 * @public
284 * @memberOf AppLog
285 *
286 * @example
287 * // This example shows how to use this function with a globally-scoped logListener.
288 * // A global function called by the log listener.
289 * var doSomething = function()
290 * {
291 * alert("this gets displayed when there is a new log entry.");
292 * }
293 *
294 * // The log listener callback function that will be passed to AppLog.startLogListener.
295 * // This function will be invoked whenever there is a new log entry.
296 * var logListener = function( date, statusCode, message )
297 * {
298 * doSomething();
299 * }
300 *
301 * function onStartLogListenerSuccessCallback() {
302 * // Do something here after listener has been added
303 * }
304 *
305 * function onStartLogListenerFailureCallback(error) {
306 * // React to error here
307 * }
308 *
309 * function onStopLogListenerSuccessCallback() {
310 * // Do something here after listener has been removed
311 * }
312 *
313 * function onStopLogListenerFailureCallback(error) {
314 * // React to error here
315 * }
316 *
317 * // Add the log listener.
318 * AppLog.startLogListener( onStartLogListenerSuccessCallback,
319 * onStartLogListenerFailureCallback,
320 * logListener );
321 *
322 * // At some other point if we want to remove the listener, we use the following line.
323 * AppLog.stopLogListener( onStopLogListenerSuccessCallback,
324 * onStopLogListenerFailureCallback,
325 * logListener );
326 *
327 * @example
328 * // This example shows how to use this function with a logListener contained in an object.
329 * // logListenerManager is an object that will contain the listener callback as well
330 * // as a function that will be invoked from the listener callback function.
331 * var logListenerManager = {};
332 *
333 * // This is a function that is called from the listener callback.
334 * logListenerManager.doSomething = function()
335 * {
336 * alert("this gets displayed when there is a new log entry.");
337 * }
338 *
339 * // This is the listener callback that will be passed to AppLog.startLogListener.
340 * // Since a variable is referenced from the containing object, the containing object
341 * // will need to be passed to AppLog.startLogListener.
342 * logListenerManager.listener = function( date, statusCode, message )
343 * {
344 * this.doSomething();
345 * }
346 *
347 * function onStartLogListenerSuccessCallback() {
348 * // Do something here after listener has been added
349 * }
350 *
351 * function onStartLogListenerFailureCallback(error) {
352 * // React to error here
353 * }
354 *
355 * function onStopLogListenerSuccessCallback() {
356 * // Do something here after listener has been removed
357 * }
358 *
359 * function onStopLogListenerFailureCallback(error) {
360 * // React to error here
361 * }
362 *
363 * // Pass both the listener callback and the containing object.
364 * AppLog.startLogListener( onStartLogListenerSuccessCallback,
365 * onStartLogListenerFailureCallback,
366 * logListenerManager.listener,
367 * logListenerManager );
368 *
369 * // At some other point if we want to remove the listener, we use the following line.
370 * AppLog.stopLogListener( onStopLogListenerSuccessCallback,
371 * onStopLogListenerFailureCallback,
372 * logListenerManager.listener,
373 * logListenerManager );
374 */
375 AppLog.stopLogListener = function( successCB, errorCB, logListener, containingObject ) {
376 try
377 {
378 if ( !logListener || ( typeof logListener !== "function" ) )
379 {
380 throw new Error( "AppLog.stopLogListener Error: logListener is not a function" );
381 }
382
383 if ( AppLog.logListeners_internal.length > 0 )
384 {
385 var foundListener = false;
386 for ( var i = 0; i < AppLog.logListeners_internal.length; i++ )
387 {
388 var listener = AppLog.logListeners_internal[ i ];
389 if ( listener.listener === logListener &&
390 listener.containingObject === containingObject )
391 {
392 foundListener = true;
393 AppLog.logListeners_internal.splice(i, 1);
394 }
395 }
396
397 if ( !foundListener )
398 {
399 throw new Error( "AppLog.stopLogListener Error: logListener was not found. Nothing removed" );
400 }
401
402 if ( AppLog.logListeners_internal.length === 0 )
403 {
404 cordova.exec( null, null, "AppLog", "stopLogListener", [] );
405 }
406 else
407 {
408 setTimeout( successCB(), 0 );
409 }
410 }
411 else
412 {
413 throw new Error( "AppLog.stopLogListener Error: There are no registered listeners" );
414 }
415 }
416 catch (ex)
417 {
418 setTimeout( errorCB( {errorCode : AppLog.ERR_UNKNOWN, description : ex.message} ), 0 ) ;
419 }
420 }
421
422 /**
423 * @private
424 */
425 AppLog.logListenerCallBack = function( logListener, containingObject ) {
426 this.containingObject = containingObject;
427 this.listener = logListener;
428 }
429 AppLog.logListeners_internal = [];
430
431 /**
432 * @private
433 */
434 AppLog.logListener_internal = function( logEntry ) {
435 if (AppLog.logListeners_internal.length === 0)
436 {
437 return;
438 }
439
440 // The incoming date is number of millisecond, we need to change it to real JavaScript Date type.
441 var dateInJS = new Date(logEntry.date);
442
443 for (var i = 0; i < AppLog.logListeners_internal.length; i++)
444 {
445 var logCallBack = AppLog.logListeners_internal[ i ];
446 var containingObject = logCallBack.containingObject;
447 var callbackFunction = logCallBack.listener;
448 if (containingObject !== null && containingObject !== undefined)
449 {
450 callbackFunction.call(containingObject, dateInJS, logEntry.statusCode, logEntry.message);
451 }
452 else
453 {
454 callbackFunction(dateInJS, logEntry.statusCode, logEntry.message);
455 }
456 }
457 }
458 })(AppLog, window);
459
460 /**
461 * Used to group anonymous objects and callback functions used as method parameters. Methods and fields in this
462 * namespace cannot be instantiated. Used for API docs generation only.
463 * @namespace
464 */
465 anonymous = (typeof anonymous === "undefined" || !anonymous) ? {} : anonymous;
466
467 /**
468 * Callback function that will be invoked with all the entries in the app log. There will be one
469 * {@link AppLog.LogEntry} object for each line in the app log.
470 * Log entries can be retrieved with {@link AppLog.getLogEntries}.
471 *
472 * @name anonymous.getLogEntriesSuccessCallback
473 * @param {AppLog.LogEntry[]} data An array of AppLog.LogEntry objects.
474 * @function
475 */
476
477 /**
478 * Callback function that will be invoked when {@link AppLog.getLogEntries} fails.
479 *
480 * @name anonymous.getLogEntriesErrorCallback
481 * @param {anonymous.AppLogErrorCallbackParameter} data The error object.
482 * @function
483 */
484
485 /**
486 * Callback function that will be invoked upon successfully starting a log listener via {@link AppLog.startLogListener},
487 * or upon successfully removing a log listener via {@link AppLog.stopLogListener}.
488 *
489 * @name anonymous.startOrStopLogListenerSuccessCallback
490 * @function
491 */
492
493 /**
494 * Callback function that will be invoked upon failure to start a log listener via {@link AppLog.startLogListener},
495 * or upon failure to removing a log listener via {@link AppLog.stopLogListener}.
496 *
497 * @name anonymous.startOrStopLogListenerErrorCallback
498 * @param {anonymous.AppLogErrorCallbackParameter} data The error object.
499 * @function
500 */
501
502 /**
503 * Object used in {@link anonymous.getLogEntriesErrorCallback} and {@link anonymous.startOrStopLogListenerErrorCallback} functions.
504 *
505 * @class
506 * @name anonymous.AppLogErrorCallbackParameter
507 * @property {number} errorCode Predefined error code
508 * @property {string} description The description of the error
509 */
510
511 /**
512 * Callback function that will be invoked when events are logged to the app log. Log listeners can be added with {@link AppLog.startLogListener}.
513 *
514 * @name anonymous.logListener
515 *
516 * @param {Date} date The date of the log entry.
517 * @param {number} event The event ID of the log entry (will be one of the AppLog status events, or possibly a custom value).
518 * @param {string} message The string carrying the message of the log entry.
519 * @function
520 */
521