mmir-lib
Version:
MMIR (Mobile Multimodal Interaction and Relay) library
940 lines (840 loc) • 26.6 kB
JavaScript
define(['mmirf/resources', 'mmirf/mediaManager', 'mmirf/logger', 'module'],
/**
*
* @name NotificationManager
* @memberOf mmir
* @static
* @class
* @hideconstructor
*
* @requires mmir.MediaManager
*/
function(
res, mediaManager, Logger, module
){
//the next comment enables JSDoc2 to map all functions etc. to the correct class description
/** @scope mmir.NotificationManager.prototype *///for jsdoc2
//private members
/**
*
* @private
* @memberOf NotificationManager#
*/
var isCordovaEnv = res.isCordovaEnv();
/**
* @private
* @memberOf NotificationManager#
*/
var instance = null;
/**
* @private
* @memberOf NotificationManager#
*/
var logger = Logger.create(module);
//private methods
/**
* Constructor-Method of Singleton mmir.NotificationManager.<br>
*
* @constructs NotificationManager
* @memberOf NotificationManager#
* @ignore
*/
function constructor(){
/**
* @private
* @memberOf NotificationManager.prototype
*/
var INIT = 'init';
/**
* VIBRATE initialization status
* @private
* @memberOf NotificationManager.prototype
*/
var isHapticEnabled = true;
/**
* Implementation for vibrate-function:
* platform-dependent (if platform/device does not support it: as stub-function)
*
* @private
* @type {Function}
* @memberOf NotificationManager.prototype
*/
var doVibrate = null;
/**
* Implementation for confirm-function:
* shows "native" platform-specific confirm-dialog.
*
* <code>function(message, confirmCallback, title, buttonLabels)</code>
*
* @private
* @type {Function}
* @memberOf NotificationManager.prototype
*/
var doConfirm = null;
/**
* Implementation for confirm-function:
* shows "native" platform-specific alert-dialog.
*
* <code>(message, alertCallback, title, buttonName)</code>
*
* @private
* @type {Function}
* @memberOf NotificationManager.prototype
*/
var doAlert = null;
/**
* Initialize the NotificationManager.
*
* At the moment this set the internal vibrate-function,
* if available in the current execution environment
* (or with a dummy function, if not).
*
* In addition, the alert-, and confirm-functions are set to their
* platform-specific implementation.
*
* @memberOf NotificationManager.prototype
* @private
* @function
*/
var _init = function(){
var isNavigator = typeof navigator !== 'undefined';
if(isCordovaEnv){
if(navigator.vibrate){
// logger.debug('Vibrate: navigator (API)');
/** @ignore */
doVibrate = function vibrate(n){ navigator.vibrate(n); };
}
else if(navigator.notification && navigator.notification.vibrate){
// logger.debug('Vibrate: navigator.notification');
/** @ignore */
doVibrate = function vibrate(n){ navigator.notification.vibrate(n); };
}
else {
logger.warn('INIT: could not detect navigator.notification.vibrate, using NOOP dummy instead.');
/** @ignore */
doVibrate = function dummyVibrate(n){ logger.warn('NotificationManager.vibrate('+n+') triggered in CORDOVA environment, but no VIBRATE functionality available.'); };
}
}
else if (isNavigator && navigator.vibrate){
// logger.debug('Vibrate API');
/** @ignore */
doVibrate = function vibrate(n){ navigator.vibrate(n); };
}
else if (isNavigator && navigator.webkitVibrate){
// logger.debug('Vibrate: webkit');
/** @ignore */
doVibrate = function vibrate(n){ navigator.webkitVibrate(n); };
}
//set confirm-implementation
if(isNavigator && navigator.notification && navigator.notification.confirm){
// logger.debug('Confirm: navigator.notification');
/** @ignore */
doConfirm = function confirm(message, confirmCallback, title, buttonLabels){
var cbWrapper = confirmCallback;
if(confirmCallback){
var self = this;
cbWrapper = function(result){
//need to convert NUMBER result to BOOLEAN:
// result = [1,2,..]
// -> default is: OK = 1, CANCEL = 2, close-the-dialog = 0
var res = result === 1 ? true : false;
confirmCallback.call(self, res);
};
}
navigator.notification.confirm(message, cbWrapper, title, buttonLabels);
};
}
else if(typeof window !== 'undefined' && window && window.confirm) {
/** @ignore */
doConfirm = function confirmWindow(message, confirmCallback, _title, _buttonLabels){
//TODO use setTimeout here to "simulate" async execution?
var result = window.confirm(message);
if(confirmCallback){
confirmCallback.call(this, result);
}
};
}
//set alert-implementation
if(isNavigator && navigator.notification && navigator.notification.alert){
// logger.debug('Alert: navigator.notification');
/** @ignore */
doAlert = function confirm(message, alertCallback, title, buttonLabels){
navigator.notification.alert(message, alertCallback, title, buttonLabels);
};
}
else if(typeof window !== 'undefined' && window && window.alert){
/** @ignore */
doAlert = function confirmWindow(message, alertCallback, _title, _buttonLabels){
//TODO use setTimeout here to "simulate" async execution?
window.alert(message);
if(alertCallback){
alertCallback.call(this);
}
};
}
};
//SOUND / BEEP initialization:
/**
* @private
* @type Number
*
* @memberOf NotificationManager.prototype
*/
var beepVolume = 1.0;
/**
* The Audio object for the <em>beep</em> sound.
*
* @private
* @type AudioObject
*
* @memberOf NotificationManager.prototype
*/
var beepAudio = null;
/**
* Map for managing the currently loaded sounds
*
* @private
* @type Map
*
* @memberOf NotificationManager.prototype
*/
//TODO add option for limiting size of soundMap (-> e.g. how many resources are max. cached/occupied for Android)
var soundMap = new Map();
/**
* Factory function for creating "sounds objects",
* i.e. extend the basic Audio objects with needed functions/properties
*
* @private
* @function
*
* @param {mmir.env.media.IAudio} audioObj
* @param {String} name
*
* @returns {mmir.env.media.INotificationSound} the extended audio object, i.e. a NotificationSound
*
* @memberOf NotificationManager.prototype
*/
function initNotificationSound(audioObj, name){
audioObj.name = name;
audioObj.setVolume(beepVolume);
audioObj.isNotificationPlaying = false;
audioObj.repeatNotification = 0;
audioObj.playNotification = function(repeatNTimes){
// logger.debug('isPlaying: '+this.isNotificationPlaying+', repeat: '+this.repeatNotification+', args: '+repeatNTimes+'');
//"blocking mode": only re-start, if not already playing
if(!this.isNotificationPlaying){
this.repeatNotification = repeatNTimes ? repeatNTimes : 0;
}
if( this.repeatNotification < 1){
//end recurusion
this.isNotificationPlaying = false;
this.repeatNotification = 0;
}
else {
this.isNotificationPlaying = true;
--this.repeatNotification;
// this.stop();
this.play();
}
};
audioObj.setCallbacks = function(onFinished, onError){
this.onFinishedListener = onFinished;
this.onErrorListener = onError;
};
audioObj.clearCallbacks = function(){
this.onFinishedListener = null;
this.onErrorListener = null;
};
audioObj.fireFinished = function(){
var tempOnFinishedListener = this.onFinishedListener;
//clear callbacks
// NOTE: do this before triggering callback, in case the callback re-plays the notification with new callbacks!
// (if we would clear callbacks after invocation, we would delete the new callbacks!)
this.clearCallbacks();
if(tempOnFinishedListener){
tempOnFinishedListener();
}
};
audioObj.fireError = function(error){
var tempOnErrorListener = this.onErrorListener;
//clear callbacks
// NOTE: do this before triggering callback, in case the callback re-plays the notification with new callbacks!
// (if we would clear callbacks after invocation, we would delete the new callbacks!)
this.clearCallbacks();
//create error message with details
var id;
if(this.name){
var entry = soundMap.get(this.name);
id = '"' + this.name + '" -> ' + (entry? '"'+entry.url+'"' : 'UNDEF');
}
else {
id = '"BEEP" -> "'+res.getBeepUrl()+'"';
}
var msg = 'Notification: Error playing the sound for notification '+id;
//create Error object if necessary
if(!error){
error = new Error(msg);
msg = null;
}
if(tempOnErrorListener){
tempOnErrorListener(error, msg);
}
else {
//if no callback: print debug output in error stream:
logger.error( (msg? msg + ': ' : '') + error, error);
}
};
return audioObj;
};
/**
* Helper for creating an Audio object
*
* @private
* @function
*
* @param {String} url
* @param {Function} success
* @param {Function} fail
* @param {Function} init
*
* @returns {AudioObject} audio object
*
* @memberOf NotificationManager.prototype
*/
function createAudio(url, success, fail, init){
return mediaManager.getURLAsAudio(url, success, fail, init);
}
/**
* Helper for "registering" a NotificationSound.
*
* Stores the sound object in {@link #soundMap}
* with the ID <code>name</code>.
*
* The sound object will be initialized on first
* retrieval, ie. {@link #doGetSoundFromMap}
*
* @private
* @function
*
* @param {String} name
* @param {String} theUrl
* @param {Boolean} isKeepOnPause
*
* @memberOf NotificationManager.prototype
*/
function initAudioSoundEntry(name, theUrl, isKeepOnPause){
var config = {url: theUrl, audio: null};
if(isKeepOnPause){
config.isKeepOnPause = true;
}
soundMap.set(name, config);
}
/**
* Helper for retrieving an existing sound from
* the {@link #soundMap}.
*
* Initializes the sound if necessary.
*
* @private
* @function
*
* @param {String} name
* @param {Function} onErrorCallback
*
* @memberOf NotificationManager.prototype
*/
function doGetSoundFromMap(name, onErrorCallback){
var audioObj = null;
var audioUrl = null;
var keepOnPause = false;
//if no name: use default beep
if(!name){
audioObj = beepAudio;
audioUrl = res.getBeepUrl();
}
else {
//retrieve information for sound
var soundEntry = soundMap.get(name);
if(soundEntry === INIT){
//TODO set repeat-times?
//sound is still initializing -> return
return null; ////////////////////// EARLY EXIT //////////////////////
}
if(!soundEntry){
var errMsg = 'NotificationManager: no sound "'+name+'" initialized!';
if(onErrorCallback){
onErrorCallback(errMsg);
}
else {
logger.error(errMsg);
}
// throw new Error(errMsg);
return null; ////////////////////// EARLY EXIT //////////////////////
}
audioObj = soundEntry.audio;//<- may be null
audioUrl = soundEntry.url;//<- must NOT be null
keepOnPause = soundEntry.isKeepOnPause? true : false;
}
return {
sound: audioObj,
url: audioUrl,
isKeepOnPause: keepOnPause
};
}
/**
* Helper for playing a registered notification sound.
*
* Initializes the sound if necessary.
*
* @private
* @function
*
* @param {String} name
* ID of the sound
* @param {Number} times
* @param {Function} onFinishedCallback
* @param {Function} onErrorCallback
*
* @memberOf NotificationManager.prototype
*/
function playAudioSound(name, times, onFinishedCallback, onErrorCallback){
var soundEntry = doGetSoundFromMap(name, onErrorCallback);
if(soundEntry === null){
//could not retrieve sound-object
// (error callback will already have been invoked, so just return)
return;/////////////////////// EARYL EXIT ///////////
}
var audioObj = soundEntry.sound;
var audioUrl = soundEntry.url;
var isKeepOnPause = soundEntry.isKeepOnPause;
//create audio-object, if not existing yet
if(audioObj === null){
if(name){
soundMap.set(name, INIT);
}
audioObj = createAudio(
audioUrl,
function onFinished(){
this.playNotification();
audioObj.fireFinished();
},
function onError(e){
if(name) {
soundMap.delete(name);
};
if(audioObj && audioObj.fireError){
audioObj.fireError(e);
}
else {
if(onErrorCallback){
onErrorCallback(e);
}
else {
logger.error('Error playing the sound from "'+audioUrl+'": '+ (e && typeof e.code !== 'undefined'? 'code '+e.code : e), e);
}
}
},
function onInit(){
//FIX for Android/Cordova: return-value of createAudio will not set audioObj "fast enough"
// (i.e. may not use async-initialization, depending on where the audio-file is located)
// ... in order to be able to use keep variable audioObj useful -> do assignment now/here
audioObj = this;
initNotificationSound(audioObj, name);
audioObj.setCallbacks(onFinishedCallback, onErrorCallback);
//if no name: assume default beep
if(!name){
beepAudio = audioObj;
}
else {
var theEntry = {url: audioUrl, audio: audioObj};
if(isKeepOnPause){
theEntry.isKeepOnPause = true;
}
soundMap.set(name, theEntry);
}
audioObj.playNotification(times);
}
);
// //FIXME this is a QUICK-FIX:
// // Android needs invocation of a media-method, before it triggers the on-init callback.
// // We need to do this here, not within the
// if(isCordovaEnv){
// audioObj.init();
// }
}
else {
audioObj.setCallbacks(onFinishedCallback, onErrorCallback);
audioObj.playNotification(times);
}
}
/**
* Helper for stop playing a registered notification sound.
*
* Initializes the sound if necessary.
*
* @private
* @function
*
* @param {String} name
* ID of the sound
* @param {Function} onFinishedCallback
* @param {Function} onErrorCallback
*
* @memberOf NotificationManager.prototype
*/
function stopAudioSound(name, onFinishedCallback, onErrorCallback){
var soundEntry = doGetSoundFromMap(name, onErrorCallback);
// logger.error('Notification: invoked stop on notification-sound '+name+' -> '+JSON.stringify(soundEntry));//FIXM debug
if(soundEntry === null){
//could not retrieve sound-object
// (error callback will already have been invoked, so just return)
return;/////////////////////// EARYL EXIT ///////////
}
var audioObj = soundEntry.sound;
//NOTE audioObj may be null, e.g. if sound is still initializing.
if(audioObj != null){
if(audioObj.repeatNotification > 0)
audioObj.repeatNotification = 0;
if(audioObj.isNotificationPlaying === true)
audioObj.isNotificationPlaying = false;
if(audioObj.stop){
// logger.verbose('Notification: stopping notification-sound -> '+name);
audioObj.stop();
}
}
if(onFinishedCallback){
onFinishedCallback.call(audioObj);
}
};
//on Android: release resources on pause/exit, since they are limited
if(isCordovaEnv){
document.addEventListener("resume", function(_event){
//initialize beep sound:
playAudioSound(null, 0);
});
document.addEventListener(
"pause",
function(_event){
//use temporal variable for minimizing concurrency problems
var temp;
if(beepAudio !== null){
temp = beepAudio;
beepAudio = null;
temp.release();
logger.debug('released media resources for beep.');
}
soundMap.forEach(function(entry){
if(entry !== null && entry != INIT && ! entry.isKeepOnPause){
temp = entry.audio;
//audio may not be initialized yet:
if(temp != null){
entry.audio = null;
temp.release();
}
if(logger.isd()) logger.debug('released media resources for '+entry.url);
}
});
},
false
);
}
/** @lends mmir.NotificationManager.prototype */
return { //public members and methods
/** @scope mmir.NotificationManager.prototype */
/**
* Trigger a haptic vibration feedback.
*
* <p>Note: The device / execution environment may not support haptic vibration feedback
*
* @function
* @param {Number} milliseconds
* duration for vibration in milliseconds. Must be <code>> 0</code>
* @public
*
* @memberOf mmir.NotificationManager.prototype
*/
vibrate: function(milliseconds){
if (isHapticEnabled && doVibrate){
doVibrate(milliseconds);
}
},
/**
* Check if {@link #vibrate} is functional and enabled.
*
* <p>
* If <code>false</code> is returned, calling the <code>vibrate()</code>
* function will have no effect.
*
* @function
* @returns {Boolean} <code>true</code> if {@link #vibrate} is functional
* @public
*
* @memberOf mmir.NotificationManager.prototype
*/
isVibrateEnabled: function(){
if (isHapticEnabled && doVibrate){
return true;
}
else {
return false;
}
},
/**
* Check if the execution environment supports {@link #vibrate}.
*
* <p>
* If <code>false</code> is returned, calling the <code>vibrate()</code>
* function will have no effect.
*
* @function
* @returns {Boolean} <code>true</code> if {@link #vibrate} is functional
* @public
*
* @memberOf mmir.NotificationManager.prototype
*/
isVibrateAvailable: function(){
if (doVibrate){
return true;
}
else {
return false;
}
},
/**
* Enable or disable {@link #vibrate}.
* <p>
* NOTE: If {@ #isVibrateAvailable} returns <code>false</code>, enabling will have no effect.
*
* @function
* @public
*
* @param {Boolean} enabled
* set vibrate function to <code>enable</code>
*
* @memberOf mmir.NotificationManager.prototype
*/
setVibrateEnabled: function(enabled){
isHapticEnabled = enabled;
},
/**
* Opens a (native) alert-notification dialog.
*
* @param {String} message
* the alert message
* @param {Function} [alertCallback]
* callback that is triggered, after dialog was closed
* @param {String} [title] OPTIONAL
* the title for the alert dialog
* (may not be provided / settable in all execution environments)
* @param {String} [buttonName] OPTIONAL
* the label for the close button in the alert dialog
* (may not be provided / settable in all execution environments)
* @function
* @public
*
* @memberOf mmir.NotificationManager.prototype
*/
alert: function(message, alertCallback, title, buttonName){
if(doAlert){
doAlert.call(this, message, alertCallback, title, buttonName);
}
else if(logger.isw()) {
logger.warn('No alert dialog implementation available: (' + message + ', ' + alertCallback + ', ' + title + ', ' + buttonName + ')');
}
},
/**
* Opens a (native) confirm-notification dialog.
*
* @param {String} message
* the confirm message
* @param {Function} [alertCallback]
* callback that is triggered, after dialog was closed.
* The callback will be invoked with 1 argument:<br>
* <code>callback(wasConfirmed : Boolean)</code><br>
* if the OK/CONFIRM button was pressed, <code>wasConfirmed</code>
* will be <code>true</code>, otherwise <code>false</code>.
* @param {String} [title] OPTIONAL
* the title for the confirm dialog
* (may not be provided / settable in all execution environments)
* @param {Array<String>} [buttonLabels] OPTIONAL
* the labels for the buttons of the confirm dialog
* (may not be provided / settable in all execution environments)
*
* @function
* @public
*
* @memberOf mmir.NotificationManager.prototype
*/
confirm: function(message, confirmCallback, title, buttonLabels){
if(doConfirm){
doConfirm.call(this, message, confirmCallback, title, buttonLabels);
}
else if(logger.isw()) {
logger.warn('NotificationManager.confirm: No confirm dialog implementation available (' + message + ', ' + confirmCallback + ', ' + title + ', ' + (buttonLabels? JSON.stringify(buttonLabels) : buttonLabels) + ')');
}
},
/**
* Trigger a beep notification sound.
*
* @function
* @param {Number} times
* how many times should to beep repeated
* @public
*
* @memberOf mmir.NotificationManager.prototype
*/
beep: function(times){
if (times>0){
playAudioSound(null, times);
}
},
/**
* @memberOf mmir.NotificationManager.prototype
*/
getVolume: function(){
return beepVolume;
},
/**
* Set the volume for sound notifications.
*
* @param {Number} vol
* the new volume: a number between [0, 1]
*
* @see mmir.env.media.IAudio#setVolume
*
* @memberOf mmir.NotificationManager.prototype
*/
setVolume: function(vol){
if(typeof vol !== 'number'){
throw new TypeError('argument vol (value: '+vol+') must be a number, but is instead: '+(typeof vol));
}
if(vol !== beepVolume){
//set volume for beep notification
beepVolume = vol;
if(beepAudio){
beepAudio.setVolume(beepVolume);
}
//set volume for notification sounds
soundMap.forEach(function(entry){
if(entry.audio !== null){
entry.audio.setVolume(vol);
}
});
}
}
/**
* Trigger a sound notification by NAME (needs to be created first).
*
* @function
* @param {String} name
* the name / identifier for the sound (if <code>null</code>, beep notification is used)
* @param {Number} times
* how many times should to beep repeated
* @public
*
* @see #createSound
*
* @memberOf mmir.NotificationManager.prototype
*/
,playSound: function(name, times, onFinished, onError){
if (times>0){
playAudioSound(name, times, onFinished, onError);
}
},
/**
* Create a sound notification.
*
* <p>
* After creation, the sound "theSoundId" can be played via
* <code>playSound("theSoundId", 1)</code>
*
* @function
* @param {String} name
* the name / identifier for the sound
* @param {String} url
* the URL for the audio of the sound
* @param {Boolean} [isKeepOnPause] OPTIONAL
* flag indicating, if the audio resources should be keept
* when the device goes into <em>pause mode</em>
* (may not apply to all execution environments;
* e.g. relevant for Android environment)
* <br>
* DEFAULT: <code>false</code>
* @public
*
* @memberOf mmir.NotificationManager.prototype
*/
createSound: function(name, url, isKeepOnPause){ // TODO add callbacks? this would make the impl. more complex ..., successCallback, errorCallback){
initAudioSoundEntry(name, url, isKeepOnPause);
//DISABLED this triggers an error if MediaManager / LanguageManager etc. are not initialized yet!
// logger.error('created sound "'+name+'" for url "'+url+'", calling from: ' + new Error().stack);
// //immediately initialize the sound (but do not play it yet);
// playAudioSound(name, 0);
}
/**
* Stop a sound notification, if it is playing.
*
* Has no effect, if the notification is not playing.
*
* @function
* @param {String} name
* the name / identifier for the sound
*
* @memberOf mmir.NotificationManager.prototype
*/
,stopSound: function(name){
stopAudioSound(name);
}
/**
* <em>used by framework to initialize the default beep-sound</em>
* @private
* @memberOf mmir.NotificationManager.prototype
*/
, initBeep: function(){
//initialize beep sound:
playAudioSound(null, 0);
}
/**
* Initialize a sound notification.
*
* <p>
* NOTE a sound does not need to be explicitly initialized, <code>playSound</code> will
* automatically initialize the sound if necessary.
*
* <p>
* Initializing a sound prepares all resources, so that the sound can be immediately played.
*
* For instance, a sound that needs to loaded from a remote server first, may take some time
* before it can be played.
*
* <p>
* NOTE the sound must be {@link #createSound|created} first, before initializing it.
*
* @function
* @param {String} name
* the name / identifier for the sound
* @public
*
* @see #createSound
*
* @memberOf mmir.NotificationManager.prototype
*/
, initSound: function(name){
//initialize sound (identified by its name):
playAudioSound(name, 0);
}
/**
* <em>used by framework to initialize the NotificationManager</em>
*
* @memberOf mmir.NotificationManager.prototype
*/
, init: function(){//<- used by framework to initialize the NotificationManager
_init();
this.init = function(){ return this; };
return this;
}
};
}
instance = new constructor();
return instance;
});//END: define(..., function(){...