QNX CAR Platform for Infotainment 2.1 -- JavaScript API (Cordova)

/**
 * @module car.audiomixer
 * @static
 *
 * @description Controls the audio mixer 
 */
 
 /*
  * @author mlapierre
  * $Id: client.js 4326 2012-09-27 17:43:24Z mlapierre@qnx.com $
  */


var _self = {},
	_ID = require("./manifest.json").namespace,
	_callback = require('./../../lib/callback'),
	Event = require('./enum/Event');

// to refer to the audio mixer setting
_self.AudioMixerSetting = require('./enum/AudioMixerSetting');

/**
 * Watch for audio mixer changes
 * @param {Function} callback The function to be called when a change is detected.
 * @return {Number} An ID for the added watch.
 * @memberOf module:car.audiomixer 
 * @method watchAudioMixer
 * @example
 * 
 * //define a callback function
 * function myCallback(audioMixerItems) {
 *		//iterate through the changed items
 *		for (var i=0; i<audioMixerItems.length; i++) {
 *			console.log("audio mixer item setting = " + audioMixerItems[i].setting + '\n' +	//a car.audiomixer.AudioMixerSetting value
 *						"audio mixer item zone = " + audioMixerItems[i].zone + '\n' +		//a car.Zone value
 *						"audio mixer item value = " + audioMixerItems[i].value + '\n\n');	//a numeric value
 *		}
 * }
 * 
 * var watchId = car.audiomixer.watchAudioMixer(myCallback);
 */
_self.watchAudioMixer = function (callback) {
	return _callback.watch(Event.UPDATE, callback);
}


/**
 * Stop watching audio mixer changes
 * @param {Number} watchId The watch ID returned by car.audiomixer.watchAudioMixer.
 * @memberOf module:car.audiomixer
 * @method cancelWatch
 * @example
 * 
 * car.audiomixer.cancelWatch(watchId);
 */
_self.cancelWatch = function (watchId) {
	_callback.cancelWatch(watchId);
}


/**
 * @desc <p>Return the audio mixer settings for a specific zone
 * <p>If successful, <b>get()</b> calls the successCallback with a Zone object for the specific zone.
 * @param {Function} successCallback The callback that is called with the result on success.
 * @param {Function} [errorCallback] The callback that is called if there is an error.
 * @param {String} [zone] The Zone to filter the results by.
 * @memberOf module:car.audiomixer
 * @method get
 * @see car.Zone 
 * @example 
 *
 * //define your callback function(s)
 * function successCallback(audioMixerItems) {
 *		//iterate through all the audio mixer items
 *		for (var i=0; i<audioMixerItems.length; i++) {
 *			console.log("audio mixer item setting = " + audioMixerItems[i].setting + '\n' +	//a car.audiomixer.AudioMixerSetting value
 *						"audio mixer item zone = " + audioMixerItems[i].zone + '\n' +		//a car.Zone value
 *						"audio mixer item value = " + audioMixerItems[i].value);			//a numeric value
 *		}
 * }
 *
 * function errorCallback(error) {
 *		console.log(error.code, error.msg);
 * }
 *
 * //optional: provide a car.Zone filter to retrieve only values for that zone.
 * //if omitted, settings for all zones will be returned
 * var zone = car.Zone.FRONT;
 *
 * //call the method
 * car.audiomixer.get(successCallback, errorCallback, zone);
 *
 * NOTE: considerations and being made for allowing an array of zones to be accepted
 *
 *
 * @example REST - single zone
 *
 * Request:
 * http://<car-ip>/car/audiomixer/get?zone=all
 *
 * Response:
 * {
 *		code: 1,
 *		data: [
 * 			{ setting: 'volume', zone: 'all', value: 50 }
 *		]
 * }
 *
 *
 * @example REST - multi zone
 *
 * Request:
 * http://<car-ip>/car/audiomixer/get
 *
 * Success Response:
 * {
 *		code: 1,
 *		data: [
 *			{ setting: 'volume', zone: 'all', value: 50 },
 *			{ setting: 'bass', zone: 'all', value: 6 },
 *		]
 * }
 *
 * Error Response:
 * {
 *		code: -1,
 *		msg: "An error has occurred"
 * }
 */
_self.get = function(successCallback, errorCallback, zone) {
	var args = {};
	if (zone) {
		args.zone = (typeof zone == 'string' && zone.length > 0) ? zone : null;
	}
	window.webworks.exec(successCallback, errorCallback, _ID, 'get', args, false);
};


/**
 * Save an audio mixer setting
 * @param {String} setting A car.audiomixer.AudioMixerSetting value.  
 * @param {String} zone A car.Zone value.   
 * @param {Number} value The value to save.
 * @param {Function} [successCallback] The callback that is called on success.
 * @param {Function} [errorCallback] The callback that is called if there is an error.
 * @memberOf module:car.audiomixer
 * @method set
 * @see car.audiomixer.AudioMixerSetting
 * @see car.Zone  
 *
 * @example
 * //option 1: set the volume in the entire car to 50 using constants
 * car.audiomixer.set(car.audiomixer.AudioMixerSetting.VOLUME, car.Zone.ALL, 50);
 *
 * //option 2: set the volume in the entire car to 50 without using constants
 * car.audiomixer.set('volume', 'all', 50);
 *
 *
 * @example REST
 *
 * Request:
 * http://<car-ip>/car/audiomixer/set?setting=volume&zone=all&value=50
 *
 * Success Response:
 * {
 *		code: 1
 * }
 *
 * Error Response:
 * {
 *		code: -1,
 *		msg: "An error has occurred"
 * }
 */
_self.set = function(setting, zone, value, successCallback, errorCallback) {
	var args = { 
		setting: setting, 
		zone: zone, 
		value: value 
	};
	window.webworks.exec(successCallback, errorCallback, _ID, 'set', args, false);
};


//Export
module.exports = _self;