Module "upnp.classes.statevariable"

The base object for UPnP statevariable.

Copyright © 2012 Thijs Schreijer, LuaUPnP is licensed under GPLv3

Release: Version 0.1, LuaUPnP

Tables

statevariable fields/properties Members of the statevariable object

Functions

statevariable:afterset (oldval) Handler called after the new value has been set.
statevariable:beforeset (newval) Handler called before the new value is set.
statevariable:check (value) Check a value against the statevariable.
statevariable:get () Gets the variable value.
statevariable:getdatatype () Gets the variable UPnP type.
statevariable:getupnp (value) Gets the variable value in upnp format.
statevariable:initialize () Initializes the statevariable object.
statevariable:parsefromxml (xmldoc, creator, parent) StateVariable constructor method, creates a new variable, parsed from an XML 'stateVariable' element.
statevariable:set (value, noevent) Sets the statevariable value.
statevariable:setdatatype (upnptype) Sets the variable UPnP type


Tables

statevariable fields/properties
Members of the statevariable object

Fields

  • name: name of the statevariable
  • sendevents: indicator for the variable to be an evented statevariable
  • _value: internal field holding the value, use get(), set() and getupnp() methods for access
  • _datatype: internal field holding the UPnP type, use getdatatype() and setdatatype() methods for access

Functions

statevariable:afterset (oldval)
Handler called after the new value has been set.
NOTE: this will only be called when the value has actually changed, so setting the current value again will not trigger it! Override in descendant classes to implement device behaviour (when overriding, do not forget to call the ancestor method to make this 'event' bubble up to the device level).
Call order; statevariable:afterset() -> service:afterset() -> device:afterset()

Parameters:

  • oldval: the previous value of the statevariable
statevariable:beforeset (newval)
Handler called before the new value is set. The new value will have been checked and converted before this handler is called. Override in descendant classes to implement device behaviour (when overriding, do not forget to call the ancestor method to make this 'event' bubble up to the device level). While the afterset() will only be called when the value being set is actually different from the current value, the beforeset() will always be run. Hence, beforeset() has the opportunity to change the value being set.
Call order; statevariable:beforeset() -> service:beforeset() -> device:beforeset()

Parameters:

  • newval: the new value to be set

Return value:

newval to be set (Lua type) or nil, error message, error number upon failure

Example:

    -- example 1) using a descendant class (inheritance)
    function mydescendant:beforeset(newval)
      print("New value being set:",newval)
      -- call ancestor method through the superclass() method
      return self:superclass().beforeset(self, newval)  -- NOTE: do not use colon syntax!
    end
    -- example 2) use when replacing a method (use from devicefactory)
    beforeset = function(self, newval)
      print("New value being set:",newval)
      -- assuming the ancestor is the base statevariable class, call it directly on that class
      return upnp.classes.statevariable.beforeset(self, newval)   -- NOTE: do not use colon syntax!
    end
statevariable:check (value)
Check a value against the statevariable. Will coerce booelans and numbers, including min/max/step values. Only values not convertable will return an error.

Parameters:

  • value: the value to check against the statevariable

Return values:

  1. value (in corresponding lua type) on success, nil on failure
  2. error string, if failure
  3. UPnP error number, if failure
statevariable:get ()
Gets the variable value. The value will be in the corresponding Lua type. Note: for a date object, always a copy will be stored/returned to prevent changes from going 'unevented', so the change must be explicitly set.
Note: The boolean type is represented in Lua as 1 or 0, this is done to prevent the mixup with nil which is also falsy.

Return value:

statevariable value as Lua type
statevariable:getdatatype ()
Gets the variable UPnP type.

Return value:

(string) UPnP data type
statevariable:getupnp (value)
Gets the variable value in upnp format.

Parameters:

  • value: (optional) the value to convert to the UPnP format of this variable. If omitted, then the current value of the statevariable will be used (this parameters main use is returning properly formatted results for action arguments during a call)

Return value:

(string) The statevariable value in UPnP format
statevariable:initialize ()
Initializes the statevariable object. Will be called upon instantiation of an object, override this method to set default values for all properties.
statevariable:parsefromxml (xmldoc, creator, parent)
StateVariable constructor method, creates a new variable, parsed from an XML 'stateVariable' element.

Parameters:

  • xmldoc: an IXML object containing the 'stateVariable' element
  • creator: callback function to create individual sub objects, see creator().
  • parent: the parent object for the variable to be created

Return value:

statevariable object
statevariable:set (value, noevent)
Sets the statevariable value. Any value provided will be converted to the corresponding Lua type

Parameters:

  • value: the new value for the statevariable
  • noevent: boolean indicating whether an event should be blocked for evented statevariables

Return values:

  1. value (in corresponding lua type) on success, nil on failure
  2. error string, if failure
  3. UPnP error number, if failure
statevariable:setdatatype (upnptype)
Sets the variable UPnP type

Parameters:

  • upnptype: a valid UPnP datatype

Valid XHTML 1.0!