mmir-lib/lib/tools/interfaces.js

MMIR (Mobile Multimodal Interaction and Relay) library

/**
 * @file This file contains interface definitions.
 * 		 The interface definitions are purely for documentation and
 * 		 should not be loaded / executed / or used in any way other
 * 		 than for reference purposes.
 */

/**
 * The Audio abstraction that is returned by {@link mmir.MediaManager#getURLAsAudio}.
 *
 * <p>
 * NOTE: when an audio object is not used anymore, its {@link #release} method should
 * 		 be called.
 *
 * <p>
 *
 * @interface
 * @name IAudio
 * @memberOf mmir.env.media
 * @public
 */
var IAudio = {
	/**
	 * The constructor.
	 *
	 * <p>
	 * NOTE that audio objects are created with a factory,
	 * e.g. via {@link mmir.MediaManager#getURLAsAudio}.
	 *
	 * @param {String} url
	 * 			the URL for the audio file
	 * @param {Function} [onPlayedCallback] OPTIONAL
	 * 			callback that is triggered when audio did play and has ended
	 * @param {Function} [failureCallBack] OPTIONAL
	 * 			callback that is triggered when an error occurs (usually during initialization)<br>
	 * 			NOTE: this argument is positional (i.e. onPlayedCallback must be specified, but may be <code>null</code>)
	 * @param {Function} [onLoadedCallBack] OPTIONAL
	 * 			callback that is triggered when audio has been initialized and is ready to be played
	 * 			NOTE: this argument is positional (i.e. onPlayedCallback and failureCallBack must be specified, but may be <code>null</code>)
	 *
	 * @protected
	 * @function
	 * @name _constructor
	 * @memberOf mmir.env.media.IAudio.prototype
	 *
	 * @see mmir.MediaManager#getURLAsAudio
	 *
	 * @example
	 *  var audio = mmir.MediaManager.getURLAsAudio(url, null, null, function onReady(){
	 *  	audio.play();
	 *  });
	 */
	_constructor: function(url, onPlayedCallback, failureCallBack, onLoadedCallBack){},
	/**
	 * Play audio.
	 *
	 * @returns {Boolean} <code>true</code>, if playing was started immediately.
	 *                    If <code>false</code>, the Audio object may have been disabled,
	 *                    or is still preparing (in which case it is auto-started, when
	 *                    preparing completes)
	 *
	 * @public
	 * @name play
	 * @function
	 * @memberOf mmir.env.media.IAudio.prototype
	 */
	play: function(){},
	/**
	 * Stop playing audio.
	 *
	 * @returns {Boolean} <code>true</code>, if stopping was successful.
	 *
	 * @public
	 * @name stop
	 * @function
	 * @memberOf mmir.env.media.IAudio.prototype
	 */
	stop: function(){},
	/**
	 * Enable audio (should only be used internally).
	 *
	 * @protected
	 * @name enable
	 * @function
	 * @memberOf mmir.env.media.IAudio.prototype
	 */
	enable: function(){},
	/**
	 * Disable audio (should only be used internally).
	 *
	 * @protected
	 * @name disable
	 * @function
	 * @memberOf mmir.env.media.IAudio.prototype
	 */
	disable: function(){},
	/**
	 * Release audio: should be called when the audio
	 * file is not used any more.
	 *
	 * <p>
	 * NOTE some environments - such as Android - have limited resources available.
	 *      Not releasing resources may result in not being able to instantiate new
	 *      (audio) resources.
	 *
	 * @public
	 * @name release
	 * @function
	 * @memberOf mmir.env.media.IAudio.prototype
	 */
	release: function(){},
	/**
	 * Set the volume of this audio file
	 *
	 * @param {Number} value
	 * 			the new value for the volume:
	 * 			a number between [0.0, 1.0]
	 *
	 * @public
	 * @name setVolume
	 * @function
	 * @memberOf mmir.env.media.IAudio.prototype
	 */
	setVolume: function(value){},
	/**
	 * Get the duration of the audio file
	 *
	 * @returns {Number} the duration in MS (or <code>-1</code> if unknown)
	 *
	 * @public
	 * @name getDuration
	 * @function
	 * @memberOf mmir.env.media.IAudio.prototype
	 */
	getDuration: function(){},
	/**
	 * Check if audio is currently paused.
	 *
	 * <p>
	 * NOTE: the state "paused" is a different status than state "stopped".
	 *
	 * @returns {Boolean} <code>true</code> if paused, <code>false</code> otherwise
	 *
	 * @public
	 * @name isPaused
	 * @function
	 * @memberOf mmir.env.media.IAudio.prototype
	 */
	isPaused: function(){},
	/**
	 * Check if audio is currently enabled
	 *
	 * @returns {Boolean} <code>true</code> if enabled
	 *
	 * @public
	 * @name isEnabled
	 * @function
	 * @memberOf mmir.env.media.IAudio.prototype
	 */
	isEnabled: function(){}
};

/**
 * Audio object that is used for the sound notifications
 * by the {@link mmir.NotificationManager}.
 *
 * @interface
 * @name INotificationSound
 * @augments mmir.env.media.IAudio
 * @memberOf mmir.env.media
 */
var INotificationSound = {
	/**
	 * The name / identifier for the sound.
	 *
	 * @public
	 * @type String
	 * @name name
	 * @memberOf mmir.env.media.INotificationSound.prototype
	 */
	name : null,
	/**
	 * Flag for the play status.
	 *
	 * @protected
	 * @type Boolean
	 * @name isNotificationPlaying
	 * @memberOf mmir.env.media.INotificationSound.prototype
	 */
	isNotificationPlaying : false,
	/**
	 * Field that holds the value for the repeat number:
	 * specifies how many times the sound should be played, before
	 * {@link #isNotificationPlaying} is set to <code>false</code>.
	 * <p>
	 * MUST be <code>>= 1</code>, otherwise the sound will not be played.
	 *
	 * @protected
	 * @type Number
	 * @name repeatNotification
	 * @memberOf mmir.env.media.INotificationSound.prototype
	 */
	repeatNotification : 0,
	/**
	 * The callback for "finished" events.
	 *
	 * @protected
	 * @type Function
	 * @name onFinishedListener
	 * @memberOf mmir.env.media.INotificationSound.prototype
	 */
	onFinishedListener : null,
	/**
	 * The callback for "error" events.
	 *
	 * @protected
	 * @type Function
	 * @name onErrorListener
	 * @memberOf mmir.env.media.INotificationSound.prototype
	 */
	onErrorListener : null,
	/**
	 * Field that holds the value for the repeat number:
	 * specifies how many times the sound should be played, before
	 * {@link #isNotificationPlaying} is set to <code>false</code>.
	 * <p>
	 * MUST be <code>>= 1</code>, otherwise the sound will not be played.
	 *
	 * @param {Number} repeatNTimes
	 * 					specifies how many times the sound should be played, before
	 * 					{@link #isNotificationPlaying} is set to <code>false</code>.
	 * 					<br>
	 * 					MUST be <code>>= 1</code>, otherwise the sound will not be played.
	 *
	 *
	 * @public
	 * @function
	 * @name playNotification
	 * @memberOf mmir.env.media.INotificationSound.prototype
	 */
	playNotification : function(repeatNTimes){},
	/**
	 * Set callback functions for when the sound has finished playing, and
	 * for errors.
	 * <p>
	 * The sound finishes playing, when its audio object has been played
	 * <code>repeatNTimes</code> as specified when invoking
	 * <code>function playNotification(repeatNTimes)</code>.
	 *
	 *
	 * @param {Function} onFinished
	 * 				the callback for the finished event
	 * @param {Function} onError
	 * 				the callback for errors
	 *
	 * @public
	 * @function
	 * @name setCallbacks
	 * @memberOf mmir.env.media.INotificationSound.prototype
	 */
	setCallbacks : function(onFinished, onError){},
	/**
	 * Clears the "finished" and "error" callbacks.
	 *
	 * @public
	 * @function
	 * @name clearCallbacks
	 * @memberOf mmir.env.media.INotificationSound.prototype
	 */
	clearCallbacks : function(){},
	/**
	 * Fires the "finished" event for its callback (if one is set).
	 *
	 * @protected
	 * @function
	 * @name fireFinished
	 * @memberOf mmir.env.media.INotificationSound.prototype
	 */
	fireFinished : function(){},
	/**
	 * Fires the "error" event for its callback (if one is set).
	 *
	 * @param {any} error
	 * 			the error that occurred
	 *
	 * @protected
	 * @function
	 * @name fireError
	 * @memberOf mmir.env.media.INotificationSound.prototype
	 */
	fireError : function(error){}
};


/**
 * Implementation for showing wait-/ready-indications:
 *
 * media-modules may signal that they are <code>preparing</code> a resource, and then that
 * they are <code>ready</code> via {@link mmir.MediaManager#_preparing} and
 * {@link mmir.MediaManager#_ready}.
 *
 * @interface
 * @name IWaitReadyIndicator
 * @memberOf mmir.env.media
 *
 * @see mmir.MediaManager#readyWaitImpl
 * @see mmir.env.media.WaitReadyIndicatorImpl
 *
 * @example
 *
 * var myWaitReadyImpl = {
 * 	preparing: function(n){
 * 		console.log('preparing: '+m);
 * 	},
 * 	ready: function(n){
 * 		console.log('ready: '+m);
 * 	}
 * }
 * mmir.media.readyWaitImpl = myWaitReadyImpl;
 */
var IWaitReadyIndicator = {
	/**
	 * Indicates that the media plugin <code>pluginName</code> is preparing
	 * something and that the user should wait.
	 *
	 * <p>
	 * For example, an implementation could show a wait dialog / overlay when this function is called.
	 *
	 * @param {String} moduleName
	 * 			the module name from which the function was invoked
	 *
	 * @public
	 * @memberOf mmir.env.media.IWaitReadyIndicator.prototype
	 *
	 * @see mmir.MediaManager#_preparing
	 */
	preparing: function (moduleName){},
	/**
	 * Indicates that the media plugin <code>pluginName</code> is now ready
	 * and that the user can begin interacting.
	 *
	 * <p>
	 * For example, an implementation could hide a wait dialog / overlay when this function is called
	 * (that was previously shown with {@link #preparing}).
	 *
	 * @param {String} moduleName
	 * 			the module name from which the function was invoked
	 *
	 * @public
	 * @memberOf mmir.env.media.IWaitReadyIndicator.prototype
	 *
	 * @see mmir.MediaManager#_ready
	 */
	ready: function(moduleName){}
};

/**
 * Disabled plugin information:
 *
 * returned by plugins that fail to initialize, supplying metainformtion for
 * creating non-functional stub-function for the plugin and error information/feedback.
 *
 * @interface
 * @name DisabledPluginInfo
 * @memberOf mmir.interface
 *
 * @property {String} mod name / ID of the (media) plugin
 * @property {Array<String> | PlainObject} [disabled] OPTIONAL
 * 																					if list of (disabled/non-functional) function names:<br>
 * 																					  stub functions will be created (which try to invoke an error-callback from the arguments or log an error)<br>
 * 																					if dictionary of functions:<br>
 * 																					  function implementations will be used as plugin implementation
 * @property {String} [message] OPTIONAL
 * 															a message to append to the error message for created stub-functions (see `disabled`)
 * @property {String} [errorCallbackName] name / ID of the (media) plugin
 *																					option-name for error-callbacks when supplied via options-argument
 * 																					(used created stub-functions, see `disabled`)
 * 																					DEFAULT: "error"
 *
 * @see mmir.MediaManager#onInitialized
 *
 */
var DisabledPluginInfo = {}