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

/**
 * @module car.hvac
 * @static
 *
 * @description Controls the HVAC system 
 * 
 */
 
/* 
 * @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 temperature setting
_self.HvacSetting = require('./enum/HvacSetting');

//to refer to the defrost direction
_self.HvacFanDirection = require('./enum/HvacFanDirection');

//to refer to the unknown error
_self.HvacError = require('./enum/HvacError');

/**
 * Watch for hvac 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.hvac
 * @method watchHvac
 * @example
 * 
 * //define a callback function
 * function myCallback(hvacItems) {
 *		//iterate through the changed items
 *		for (var i=0; i<hvacItems.length; i++) {
 *			console.log("hvac item setting = " + hvacItems[i].setting + '\n' +	//a car.hvac.HvacSetting value
 *						"hvac item zone = " + hvacItems[i].zone + '\n' +		//a car.zone value
 *						"hvac item value = " + hvacItems[i].value + '\n\n');	//a mixed value type, depending on the
 *		}
 * }
 * 
 * var watchId = car.hvac.watchHvac(myCallback);
 */
_self.watchHvac = function (callback) {
	return _callback.watch(Event.UPDATE, callback);
}

/**
 * Stop watching hvac items
 * @param {Number} watchId The watch ID returned by car.hvac.watchHvac.
 * @memberOf module:car.hvac
 * @method cancelWatch
 * @example
 * 
 * car.hvac.cancelWatch(watchId);
 */
_self.cancelWatch = function (watchId) {
	_callback.cancelWatch(watchId);
}


/**
 * @desc <p>Return HVAC settings for the specified filter
 * <p>If successful, <b>get()</b> calls the successCallback with an array of setting objects.
 * containing the setting (car.hvac.HvacSetting), the zone (car.zone) and the value (number/string/boolean).
 * @param {Function} successCallback The callback that is called with the result.
 * @param {Function} [errorCallback] The callback that is called if there is an error.
 * @param {Array} [settings] An array of car.hvac.HvacSetting values to whitelist.
 * @param {Array} [zones] An array of car.zone values to whitelist. 
 * @memberOf module:car.hvac
 * @method get
 * @see car.hvac.HvacSetting  
 * @see car.Zone  
 * @example 
 *
 * //define your callback function(s)
 * function successCallback(hvacItems) {
 *		//iterate through all the hvac items
 *		for (var i=0; i<hvacItems.length; i++) {
 *			console.log("hvac item setting = " + hvacItems[i].setting + '\n' +	//a car.hvac.HvacSetting value
 *						"hvac item zone = " + hvacItems[i].zone + '\n' +		//a car.zone value
 *						"hvac item value = " + hvacItems[i].value + '\n\n');	//a mixed value type, depending on the
 *		}
 * }
 *
 * function errorCallback(error) {
 *		console.log(error.code, error.msg);
 * }
 *
 * //optional: define a filter. See car.hvac#HvacFilter for details
 *
 * //call the method
 * car.hvac.get(successCallback, errorCallback);
 *
 *
 * @example REST - without any filters
 *
 * Request:
 * http://<car-ip>/car/hvac/get
 *
 * Success Response:
 * {
 *		code: 1,
 *		data: [
 *			{ setting: 'temperature', zone: 'frontLeft', value:  20 },
 *			{ setting: 'temperature', zone: 'frontRight', value: 22 },
 *			{ setting: 'temperature', zone: 'rear', value: 22 },
 *			{ setting: 'airConditioning', zone: 'everywhere', value: true },
 *			...
 *		]
 * }
 *
 * Error Response:
 * {
 *		code: -1,
 *		msg: "An error has occurred"
 * }
 *
 *
 * @example REST - with settings and zone filters
 *
 * Request:
 * http://<car-ip>/car/hvac/get?settings=temperature,heatedSeats&zones=frontLeft,frontRight
 *
 * Success Response:
 * {
 *		code: 1,
 *		data: [
 *			{ setting: 'temperature', zone: 'frontLeft', value:  20 },
 *			{ setting: 'temperature', zone: 'frontRight', value: 22 },
 *			{ setting: 'heatedSeat', zone: 'frontLeft', value:  5 },
 *			{ setting: 'heatedSeat', zone: 'frontLeft', value: 0 }
 *		]
 * }
 *
 * Error Response:
 * {
 *		code: -1,
 *		msg: "An error has occurred"
 * }
 */
_self.get = function(successCallback, errorCallback, settings, zones) {
	var args = {};

	if (typeof settings == 'object' && settings.length > 0) {
		args.settings = settings.join(',');
	}

	if (typeof zones == 'object' && zones.length > 0) {
		args.zones = zones.join(',');
	}

	window.webworks.exec(successCallback, errorCallback, _ID, 'get', args, false);
};

/**
 * Save an HVAC setting
 * @param {String} setting An HvacSetting value.   
 * @param {String} zone A car.zone value.   
 * @param {Mixed} value The value to save.   
 * @param {Function} [successCallback] The callback that is called with the result.
 * @param {Function} [errorCallback] The callback that is called if there is an error.
 * @memberOf module:car.hvac 
 * @method set
 * @see car.hvac.HvacSetting  
 * @see car.Zone    
 * @example
 *
 * //set the temperature in the entire car to 50
 * car.hvac.set(car.hvac.HvacSetting.TEMPERATURE, car.zone.EVERYWHERE, 50);
 * //NOTE: this is equivalent to doing: car.hvac.set('temperature', 'everywhere', 50);
 *
 *
 * @example REST
 *
 * Request:
 * http://<car-ip>/car/hvac/set?setting=temperature&zone=frontLeft&value=25
 *
 * 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;