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, ornil + 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), ornil, 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 thegenericgetter()/genericsetter()
might automatically have been set as theexecute()
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 theexecute()
method for the action.Parameters:
-
params
: list of parameters (not used by getters, but is standard inexecute()
method signature)
Return value:
table with named return arguments (seeaction:execute()
for format)Example:
-- usage for generic getter, assign to execute method
myAction.execute = upnp.classes.action.genericgetterSee also:
- action name starts with
- 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 theexecute()
method for the action.Parameters:
-
params
: list of parameters
Return values:
1
on success, ornil
on errorerrorstring
on errorerrornr
on error
Example:
-- usage for generic getter, assign to execute method
myAction.execute = upnp.classes.action.genericgetterSee also:
- action name starts with
- 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, seecreator()
. -
parent
: the parent service object for the action to be created
Return value:
action object ornil + error message
-