slixmpp/sleekxmpp/plugins/xep_0325/device.py

"""
    SleekXMPP: The Sleek XMPP Library
    Implementation of xeps for Internet of Things
    http://wiki.xmpp.org/web/Tech_pages/IoT_systems
    Copyright (C) 2013 Sustainable Innovation, Joachim.lindborg@sust.se, bjorn.westrom@consoden.se
    This file is part of SleekXMPP.

    See the file LICENSE for copying permission.
"""

import datetime

class Device(object):
	"""
	Example implementation of a device control object.
    
    The device object may by any custom implementation to support 
    specific devices, but it must implement the functions:
          has_control_field
          set_control_fields
	"""

	def __init__(self, nodeId):
		self.nodeId = nodeId;
		self.control_fields = {};

	def has_control_field(self, field, typename):
		"""
		Returns true if the supplied field name exists
		and the type matches for control in this device.

        Arguments:
            field      -- The field name		
            typename   -- The expected type
		"""
		if field in self.control_fields and self.control_fields[field]["type"] == typename:
			return True;
		return False;

	def set_control_fields(self, fields, session, callback):
		"""
		Starts a control setting procedure. Verifies the fields,
		sets the data and (if needed) and calls the callback.

        Arguments:
            fields   -- List of control fields in tuple format: 
                        (name, typename, value)
            session  -- Session id, only used in the callback as identifier
            callback -- Callback function to call when control set is complete.

					The callback function must support the following arguments:

				session     -- Session id, as supplied in the 
				               request_fields call
				nodeId      -- Identifier for this device
            	result      -- The current result status of the readout. 
            	               Valid values are:
                               "error"  - Set fields failed.
                               "ok"     - All fields were set.
	            error_field -- [optional] Only applies when result == "error" 
    	                       The field name that failed 
    	                       (usually means it is missing)
        	    error_msg   -- [optional] Only applies when result == "error".
            	               Error details when a request failed.
		"""

		if len(fields) > 0:
			# Check availiability
			for name, typename, value in fields:
				if not self.has_control_field(name, typename):
					self._send_control_reject(session, name, "NotFound", callback)
					return False;

		for name, typename, value in fields:
			self._set_field_value(name, value)

		callback(session, result="ok", nodeId=self.nodeId);
		return True

	def _send_control_reject(self, session, field, message, callback):
		"""
		Sends a reject to the caller

        Arguments:
            session  -- Session id, see definition in 
                        set_control_fields function
            callback -- Callback function, see definition in 
                        set_control_fields function
		"""
		callback(session, result="error", nodeId=self.nodeId, error_field=field, error_msg=message);

	def _add_control_field(self, name, typename, value):
		"""
		Adds a control field to the device

        Arguments:
            name     -- Name of the field
            typename -- Type of the field, one of: 
                        (boolean, color, string, date, dateTime, 
                         double, duration, int, long, time)
            value    -- Field value
		"""
		self.control_fields[name] = {"type": typename, "value": value};

	def _set_field_value(self, name, value):
		"""
		Set the value of a control field

        Arguments:
            name     -- Name of the field
            value    -- New value for the field
		"""
		if name in self.control_fields:
			self.control_fields[name]["value"] = value;

	def _get_field_value(self, name):
		"""
		Get the value of a control field. Only used for unit testing.

        Arguments:
            name     -- Name of the field
		"""
		if name in self.control_fields:
			return self.control_fields[name]["value"];
		return None;