Using the PPS interface

We will again use the existing qnx.volume extension as an example. You can use this existing extension as a framework for creating your own.

PPS activities of an extension are typically dealt with in the extension_name.js file (volume.js in our example). You can name your file anything you want, but we recommend following the extension_name.js convention. The code for volume.js is shown below, with explanations of its various components from top to bottom.

1. First, the file links to the PPS utilities file ppsUtils.js, which resides in the WebWorks folder:

   /**
   * The abstraction layer for volume functionality
    *
    * @author myName
    * $Id$
    */
   
   var	_pps = require('../../lib/pps/ppsUtils'),
   	_statusPPS,
   	_controlPPS,
   	_trigger;

2. A PPS status object is created and initialized. Then the object is opened. The first parameter in the open function gives the path where the object should be read from, in this case: /pps/services/audio/status. The second parameter, JNEXT.PPS_RDONLY, opens the object as a read-only entity. You need to set the onChange method to set up your callback handler for PPS events. Inside that handler you can do whatever you wish when an a PPS event is fired, including (but not limited to) calling your trigger functions to dispatch an event.

   /**
    * Exports are the publicly accessible functions
    */
   module.exports = {
   	/**
   	 * Initializes the extension 
   	 */
   	init: function() {
   		//statusPPS
   		_statusPPS = _pps.createObject();
   		_statusPPS.init();
   		_statusPPS.onChange = function(event) {
   			if (_trigger && event && event.data && !isNaN(event.data["output.speaker.volume"])) {
   				_trigger({ volume: event.data["output.speaker.volume"] });
   			}
   		};
   		_statusPPS.open('/pps/services/audio/status', JNEXT.PPS_RDONLY);

3. Next the PPS control object is created and initialized, and then opened. The first parameter in the open() function gives the path where the object should be written to. The second parameter in the open() function opens the entity for write-only actions using the JNEXT.PPS_WRONLY parameter.

   		//controlPPS
   		_controlPPS = _pps.createObject();
   		_controlPPS.init();
   		_controlPPS.open("/pps/services/audio/control", JNEXT.PPS_WRONLY);
   	},

4. The setTrigger method sets the trigger function to call when a volume event is fired.

   	/**
   	 * Sets the trigger function to call when a volume event is fired
   	 * @param trigger {Function} The trigger function to call when the event is fired
   	 */
   	setTrigger: function(trigger) {
   		_trigger = trigger;
   	},

5. Below this, the interaction of the two methods of the qnx.volume extension with PPS are defined. First, the get method involves the PPS status object and reads the volume ("output.speaker.volume").

   	/**
   	 * Returns the current volume
   	 * @returns {Number} The current audio parameters
   	 */
   	get: function() {
   		return _statusPPS.ppsObj["output.speaker.volume"];
   	},	

6. Now the set method involves the PPS control object. After checking for volume output validity (a volume between 0 and 100), the method writes (publishes) the appropriate attribute pairs to the PPS control object.

   	/**
   	 * Sets the volume
   	 * @param volume {Number} The new volume to set
   	 */
   	set: function(volume) {
   		//write volume to pps
   		if (!isNaN(volume) && volume >= 0 && volume <= 100) {
   			_controlPPS.write({
   				id: 4,
   				msg: "set_output_level", 
   				dat: { 
   					ctxt: 0, 
   					output_id: 0, 
   					level: volume 
   				}
   			});
   		}
   	},
   };

Remember to set the onChange method to set up your callback handler for PPS events.

The format and content of your PPS objects will depend on the extension you're writing. Use PPS object definitions appropriate to your extension.