1 
  2 /**
  3  * @file This file contains interface definitions. 
  4  * 		 The interface definitions are purely for documentation and 
  5  * 		 should not be loaded / executed / or used in any way other
  6  * 		 than for reference purposes.
  7  */
  8 
  9 /**
 10  * The Audio abstraction that is returned by {@link mmir.MediaManager#getURLAsAudio}.
 11  * 
 12  * <p>
 13  * NOTE: when an audio object is not used anymore, its {@link #release} method should
 14  * 		 be called.
 15  * 
 16  * <p>
 17  * 
 18  * @interface
 19  * @name IAudio
 20  * @memberOf mmir.env.media
 21  * @public
 22  */
 23 var IAudio = {
 24 	/**
 25 	 * The constructor.
 26 	 * 
 27 	 * <p>
 28 	 * NOTE that audio objects are created with a factory,
 29 	 * e.g. via {@link mmir.MediaManager#getURLAsAudio}.
 30 	 * 
 31 	 * @param {String} url
 32 	 * 			the URL for the audio file
 33 	 * @param {Function} [onPlayedCallback] OPTIONAL
 34 	 * 			callback that is triggered when audio did play and has ended
 35 	 * @param {Function} [failureCallBack] OPTIONAL
 36 	 * 			callback that is triggered when an error occurs (usually during initialization)<br>
 37 	 * 			NOTE: this argument is positional (i.e. onPlayedCallback must be specified, but may be <code>null</code>)
 38 	 * @param {Function} [onLoadedCallBack] OPTIONAL
 39 	 * 			callback that is triggered when audio has been initialized and is ready to be played
 40 	 * 			NOTE: this argument is positional (i.e. onPlayedCallback and failureCallBack must be specified, but may be <code>null</code>)
 41 	 * 
 42 	 * @protected
 43 	 * @function
 44 	 * @name _constructor
 45 	 * @memberOf mmir.env.media.IAudio.prototype
 46 	 * 
 47 	 * @see mmir.MediaManager#getURLAsAudio
 48 	 * 
 49 	 * @example
 50 	 *  var audio = mmir.MediaManager.getURLAsAudio(url, null, null, function onReady(){
 51 	 *  	audio.play();
 52 	 *  });
 53 	 */
 54 	_constructor: function(url, onPlayedCallback, failureCallBack, onLoadedCallBack){},
 55 	/**
 56 	 * Play audio.
 57 	 * 
 58 	 * @public
 59 	 * @name play
 60 	 * @function
 61 	 * @memberOf mmir.env.media.IAudio.prototype
 62 	 */
 63 	play: function(){},
 64 	/**
 65 	 * Stop playing audio.
 66 	 * 
 67 	 * @public
 68 	 * @name stop
 69 	 * @function
 70 	 * @memberOf mmir.env.media.IAudio.prototype
 71 	 */
 72 	stop: function(){},
 73 	/**
 74 	 * Enable audio (should only be used internally).
 75 	 * 
 76 	 * @protected
 77 	 * @name enable
 78 	 * @function
 79 	 * @memberOf mmir.env.media.IAudio.prototype
 80 	 */
 81 	enable: function(){},
 82 	/**
 83 	 * Disable audio (should only be used internally).
 84 	 * 
 85 	 * @protected
 86 	 * @name disable
 87 	 * @function
 88 	 * @memberOf mmir.env.media.IAudio.prototype
 89 	 */
 90 	disable: function(){},
 91 	/**
 92 	 * Release audio: should be called when the audio
 93 	 * file is not used any more.
 94 	 * 
 95 	 * <p>
 96 	 * NOTE some environments - such as Android - have limited resources available.
 97 	 *      Not releasing resources may result in not being able to instantiate new
 98 	 *      (audio) resources.
 99 	 * 
100 	 * @public
101 	 * @name release
102 	 * @function
103 	 * @memberOf mmir.env.media.IAudio.prototype
104 	 */
105 	release: function(){},
106 	/**
107 	 * Set the volume of this audio file
108 	 * 
109 	 * @param {Number} value
110 	 * 			the new value for the volume:
111 	 * 			a number between [0.0, 1.0]
112 	 * 
113 	 * @public
114 	 * @name setVolume
115 	 * @function
116 	 * @memberOf mmir.env.media.IAudio.prototype
117 	 */
118 	setVolume: function(value){},
119 	/**
120 	 * Get the duration of the audio file
121 	 * 
122 	 * @returns {Number} the duration in MS (or <code>-1</code> if unknown)
123 	 * 
124 	 * @public
125 	 * @name getDuration
126 	 * @function
127 	 * @memberOf mmir.env.media.IAudio.prototype
128 	 */
129 	getDuration: function(){},
130 	/**
131 	 * Check if audio is currently paused.
132 	 * 
133 	 * <p>
134 	 * NOTE: the state "paused" is a different status than state "stopped".
135 	 * 
136 	 * @returns {Boolean} <code>true</code> if paused, <code>false</code> otherwise
137 	 * 
138 	 * @public
139 	 * @name isPaused
140 	 * @function
141 	 * @memberOf mmir.env.media.IAudio.prototype
142 	 */
143 	isPaused: function(){},
144 	/**
145 	 * Check if audio is currently enabled
146 	 * 
147 	 * @returns {Boolean} <code>true</code> if enabled
148 	 * 
149 	 * @public
150 	 * @name isEnabled
151 	 * @function
152 	 * @memberOf mmir.env.media.IAudio.prototype
153 	 */
154 	isEnabled: function(){}
155 };
156 
157 /**
158  * Audio object that is used for the sound notifications
159  * by the {@link mmir.NotificationManager}.
160  * 
161  * @interface
162  * @name INotificationSound
163  * @augments mmir.env.media.IAudio
164  * @memberOf mmir.env.media
165  */
166 var INotificationSound = {
167 	/**
168 	 * The name / identifier for the sound.
169 	 * 
170 	 * @public
171 	 * @type String
172 	 * @name name
173 	 * @memberOf mmir.env.media.INotificationSound.prototype
174 	 */
175 	name : null,
176 	/**
177 	 * Flag for the play status.
178 	 * 
179 	 * @protected
180 	 * @type Boolean
181 	 * @name isNotificationPlaying
182 	 * @memberOf mmir.env.media.INotificationSound.prototype
183 	 */
184 	isNotificationPlaying : false,
185 	/**
186 	 * Field that holds the value for the repeat number:
187 	 * specifies how many times the sound should be played, before
188 	 * {@link #isNotificationPlaying} is set to <code>false</code>.
189 	 * <p>
190 	 * MUST be <code>>= 1</code>, otherwise the sound will not be played.
191 	 * 
192 	 * @protected
193 	 * @type Number
194 	 * @name repeatNotification
195 	 * @memberOf mmir.env.media.INotificationSound.prototype
196 	 */
197 	repeatNotification : 0,
198 	/**
199 	 * The callback for "finished" events.
200 	 * 
201 	 * @protected
202 	 * @type Function
203 	 * @name onFinishedListener
204 	 * @memberOf mmir.env.media.INotificationSound.prototype
205 	 */
206 	onFinishedListener : null,
207 	/**
208 	 * The callback for "error" events.
209 	 * 
210 	 * @protected
211 	 * @type Function
212 	 * @name onErrorListener
213 	 * @memberOf mmir.env.media.INotificationSound.prototype
214 	 */
215 	onErrorListener : null,
216 	/**
217 	 * Field that holds the value for the repeat number:
218 	 * specifies how many times the sound should be played, before
219 	 * {@link #isNotificationPlaying} is set to <code>false</code>.
220 	 * <p>
221 	 * MUST be <code>>= 1</code>, otherwise the sound will not be played.
222 	 * 
223 	 * @param {Number} repeatNTimes
224 	 * 					specifies how many times the sound should be played, before
225 	 * 					{@link #isNotificationPlaying} is set to <code>false</code>.
226 	 * 					<br>
227 	 * 					MUST be <code>>= 1</code>, otherwise the sound will not be played.
228 	 * 		
229 	 * 
230 	 * @public
231 	 * @function
232 	 * @name playNotification
233 	 * @memberOf mmir.env.media.INotificationSound.prototype
234 	 */
235 	playNotification : function(repeatNTimes){},
236 	/**
237 	 * Set callback functions for when the sound has finished playing, and
238 	 * for errors.
239 	 * <p>
240 	 * The sound finishes playing, when its audio object has been played
241 	 * <code>repeatNTimes</code> as specified when invoking
242 	 * <code>function playNotification(repeatNTimes)</code>.
243 	 * 
244 	 * 
245 	 * @param {Function} onFinished
246 	 * 				the callback for the finished event
247 	 * @param {Function} onError
248 	 * 				the callback for errors
249 	 * 
250 	 * @public
251 	 * @function
252 	 * @name setCallbacks
253 	 * @memberOf mmir.env.media.INotificationSound.prototype
254 	 */
255 	setCallbacks : function(onFinished, onError){},
256 	/**
257 	 * Clears the "finished" and "error" callbacks.
258 	 * 
259 	 * @public
260 	 * @function
261 	 * @name clearCallbacks
262 	 * @memberOf mmir.env.media.INotificationSound.prototype
263 	 */
264 	clearCallbacks : function(){},
265 	/**
266 	 * Fires the "finished" event for its callback (if one is set).
267 	 * 
268 	 * @protected
269 	 * @function
270 	 * @name fireFinished
271 	 * @memberOf mmir.env.media.INotificationSound.prototype
272 	 */
273 	fireFinished : function(){},
274 	/**
275 	 * Fires the "error" event for its callback (if one is set).
276 	 * 
277 	 * @param {any} error
278 	 * 			the error that occurred
279 	 * 
280 	 * @protected
281 	 * @function
282 	 * @name fireError
283 	 * @memberOf mmir.env.media.INotificationSound.prototype
284 	 */
285 	fireError : function(error){}
286 };
287 
288 
289 /**
290  * Audio object that is used for the sound notifications
291  * by the {@link mmir.MediaManager}.
292  * 
293  * @interface
294  * @name IWaitReadyIndicator
295  * @memberOf mmir.env.media
296  * 
297  * @see mmir.MediaManager#readyWaitImpl
298  */
299 var IWaitReadyIndicator = {
300 	/**
301 	 * Indicates that the media plugin <code>pluginName</code> is preparing
302 	 * something and that the user should wait.
303 	 * 
304 	 * <p>
305 	 * For example, an implementation could show a wait dialog / overlay when this function is called.
306 	 * 
307 	 * @param {String} moduleName
308 	 * 			the module name from which the function was invoked
309 	 * 
310 	 * @public
311 	 * @memberOf mmir.env.media.IWaitReadyIndicator.prototype
312 	 * 
313 	 * @see mmir.MediaManager#_preparing
314 	 */
315     preparing: function (moduleName){},
316     /**
317      * Indicates that the media plugin <code>pluginName</code> is now ready
318 	 * and that the user can begin interacting.
319 	 * 
320 	 * <p>
321 	 * For example, an implementation could hide a wait dialog / overlay when this function is called
322 	 * (that was previously shown with {@link #preparing}).
323 	 * 
324 	 * @param {String} moduleName
325 	 * 			the module name from which the function was invoked
326      * 
327 	 * @public
328 	 * @memberOf mmir.env.media.IWaitReadyIndicator.prototype
329 	 * 
330 	 * @see mmir.MediaManager#_ready
331 	 */
332 	ready: function(moduleName){}
333 };