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