Module "upnp.classes.service"

The base object for UPnP services.

Copyright © 2012 Thijs Schreijer, LuaUPnP is licensed under GPLv3

Release: Version 0.1, LuaUPnP

Tables

service fields/properties Members of the service object

Functions

service:addaction (action) Adds an action to the service actionlist.
service:addstatevariable (statevar) Adds a statevariable to the service statetable.
service:afterset (statevariable, oldval) Handler called after the new value has been set to an owned statevariable.
service:beforeset (statevariable, newval) Handler called before the new value is set to an owned statevariable.
service:executeaction (actionname, params) Execute an action owned by the service.
service:getupnpvalues () Creates a list of all variables and values, to be provided when a subscription is accepted
service:initialize () Initializes the service object.
service:parsefromxml (xmldoc, creator, parent, plist) Service constructor method, creates a new service, parsed from a service xml.


Tables

service fields/properties
Members of the service object

Fields

  • servicetype: type of the service
  • serviceid: id of the service
  • parent: the device owning this service
  • actionlist: list of actions, indexed by their name
  • statetable: list of statevariables, indexed by their name

Functions

service:addaction (action)
Adds an action to the service actionlist.

Parameters:

  • action: action object to add
service:addstatevariable (statevar)
Adds a statevariable to the service statetable.

Parameters:

  • statevar: statevariable object to add
service:afterset (statevariable, oldval)
Handler called after the new value has been set to an owned statevariable.
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:

  • statevariable: the statevariable (table/object) whose value is being changed
  • oldval: the previous value of the statevariable
service:beforeset (statevariable, newval)
Handler called before the new value is set to an owned statevariable. 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:

  • statevariable: the statevariable (table/object) whose value is being changed
  • newval: the new value to be set

Return value:

newval to be set (Lua type) or nil, error message, error number upon failure
service:executeaction (actionname, params)
Execute an action owned by the service. Preferably call the device:executeaction() method, as that ensures that all objects in the hierarchy are informed about the results, additionally it will check and convert parameters in and results going out.

Parameters:

  • actionname: (string or table) name of action to execute, or action table/object
  • params: (table) table of parameter values, keyed by parameter names

Return value:

2 lists (names and values) of the 'out' arguments (in proper order), or nil, errormsg, errornumber upon failure
service:getupnpvalues ()
Creates a list of all variables and values, to be provided when a subscription is accepted

Return values:

  1. list with variablenames
  2. list with variablevalues (order matching the name list)
service:initialize ()
Initializes the service object. Will be called upon instantiation of an object, override this method to set default values for all properties.
service:parsefromxml (xmldoc, creator, parent, plist)
Service constructor method, creates a new service, parsed from a service xml. The service object will be created, including all its children.

Parameters:

  • xmldoc: XML document from which a service is to be parsed, this can be either 1) a string value containing the xml, 2) a string value containing the filename of the xml 3) an IXML object containing the 'service' element
  • creator: callback function to create individual sub objects, see creator().
  • parent: the parent device object for the service to be created
  • plist: key-value list with service properties already parsed from the Device XMLs 'serviceList' element.

Return value:

service object or nil + error message

Valid XHTML 1.0!