Module "upnp.classes.action"

The base object for UPnP actions.

Copyright © 2012 Thijs Schreijer, LuaUPnP is licensed under GPLv3

Release: Version 0.1, LuaUPnP

Tables

Action fields/properties Members of the action object

Functions

action:addargument (argument) Adds an argument to the actions argument list.
action:checkparams (params) Checks parameters, completeness and conversion to Lua values/types.
action:checkresults (result) Checks return values, completeness and conversion to UPnP values/types.
action:execute (params) Executes the action.
action:genericgetter (params) Generic function for standard actions 'getVariableName'.
action:genericsetter (params) Generic function for standard actions 'setVariableName'.
action:initialize () Initializes the action object.
action:parsefromxml (xmldoc, creator, parent) Action constructor method, creates a new action, parsed from an XML 'action' element.


Tables

Action fields/properties
Members of the action object

Fields

  • name: name of the action
  • parent: the owning upnpservice object
  • argumentlist: list with arguments, indexed both by name and number (order in the list)
  • argumentcount: number of arguments for the action

Functions

action:addargument (argument)
Adds an argument to the actions argument list. This will append an argument, so adding must be done in proper UPnP order!

Parameters:

  • argument: the argument object to be added to the argumentlist
action:checkparams (params)
Checks parameters, completeness and conversion to Lua values/types.
NOTE: a copy of the table is returned, so the original table will not be modified.

Parameters:

  • params: table with parameters provided (key value list, where key is the parameter name, value is the Lua typed value)

Return value:

params table, or nil + errormsg + errornumber in case of an error
action:checkresults (result)
Checks return values, completeness and conversion to UPnP values/types. Transforms the results in 2 lists, names and values, in proper UPnP order, and UPnP typed.

Parameters:

  • result: table with parameters provided (key value list, where key is the parameter name)

Return value:

2 lists (names and values) of the 'out' arguments (in proper order), or nil, errormsg, errornumber upon failure
action:execute (params)
Executes the action. Override in descendant classes to implement the actual device behaviour. 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.
NOTE: If parsed from an xml file the genericgetter()/genericsetter() might automatically have been set as the execute() method.

Parameters:

  • params: table with named 'out' arguments (each argument indexed by its name).

Return value:

table with named return values (each indexed by its lowercase name). Upon an error the function should return; nil, errorstring, errornumber (see the 6xx error codes in the UPnP 1.0 architecture document, section 3.2.2)
action:genericgetter (params)
Generic function for standard actions 'getVariableName'. This method is capable of returning multiple parameters, it will simply report all 'out' arguments of the action based on the related statevariables current value.
NOTE: when an action is parsed from an xml, and the following conditions are met;

  • action name starts with 'get' (case independent)
  • the action has 1 or more arguments
  • all arguments are direction 'out'
  • none of the arguments has a related statevariable which name starts with 'A_ARG_TYPE_' (case independent)

then the genericgetter will automatically be set as the execute() method for the action.

Parameters:

  • params: list of parameters (not used by getters, but is standard in execute() method signature)

Return value:

table with named return arguments (see action:execute() for format)

Example:

-- usage for generic getter, assign to execute method
myAction.execute = upnp.classes.action.genericgetter
action:genericsetter (params)
Generic function for standard actions 'setVariableName'. This method is capable of aetting multiple statevariable values, it will simply store all values of the parameters in the related statevariables.
NOTE: when an action is parsed from an xml, and the following conditions are met;

  • action name starts with 'set' (case independent)
  • the action has 1 or more arguments
  • all arguments are direction 'in'
  • none of the arguments has a related statevariable which name starts with 'A_ARG_TYPE_' (case independent)

then the genericsetter will automatically be set as the execute() method for the action.

Parameters:

  • params: list of parameters

Return values:

  1. 1 on success, or nil on error
  2. errorstring on error
  3. errornr on error

Example:

-- usage for generic getter, assign to execute method
myAction.execute = upnp.classes.action.genericgetter
action:initialize ()
Initializes the action object. Will be called upon instantiation of an object, override this method to set default values for all properties.
action:parsefromxml (xmldoc, creator, parent)
Action constructor method, creates a new action, parsed from an XML 'action' element.

Parameters:

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

Return value:

action object or nil + error message

Valid XHTML 1.0!