LuaDoc

• Index

Modules

• upnp
• upnp.bootstrap
• upnp.classes.action
• upnp.classes.argument
• upnp.classes.device
• upnp.classes.service
• upnp.classes.statevariable
• upnp.classes.upnpbase
• upnp.devicefactory
• upnp.drivers.driver-template
• upnp.drivers.xplrfx
• upnp.lp
• upnp.xmlfactory
• urn_schemas-upnp-org_device_BinaryLight_1
• urn_schemas-upnp-org_device_DimmableLight_1
• urn_schemas-upnp-org_service_Dimming_1
• urn_schemas-upnp-org_service_SwitchPower_1

Module "upnp.classes.device"

The base object for UPnP devices.

Copyright © 2012 Thijs Schreijer, LuaUPnP is licensed under GPLv3

Release: Version 0.1, LuaUPnP

Tables

Functions

Tables

device fields/properties

Members of the device object

Fields

• _udn: device udn (unique device name; UUID). Do not access directly, use device:getudn(), device:setudn()
• parent: owning device, or nil if it is a root device
• devicelist: list of sub-devices, ordered by their UDN
• servicelist: list of services, ordered by their serviceid
• devicexmlurl: the url to the device XML (relative to the upnp.webroot directory), this only applies to root-devices

Functions

creator (plist, classname, parent)

Description of the "creator" callback function as it has to be provided to parsefromxml(). This function allows to create the device object hierarchy with custom objects, implementing the required device behaviour. The most common case being to override the action:execute(params) method.

Parameters:

• plist: list of named properties as parsed from the xml, eg. a device could expect a key-value pair friendlyname = "name as specified in xml". NOTE: all keys have been converted to lowercase!!
• classname: the type of object (or descendant of that type) to be created, this will be any of the following; "device", "service", "statevariable", "action", "argument", or "servicexml".
• parent: The parent object to which the requested object will be added. The parent property on the created object will be set afterwards, no need to set it here (nil for a root-device).

Return value:

object type as requested, to be created by calling objectbaseclass:new(plist), which will instantiate a new class and set the properties from plist accordingly. EXCEPTION: if class servicexml is requested, a string with the service xml should be returned, the string should be parseable by the upnp.getxml() function. If nil is returned, then a standard baseclass of the requested type will be instatiated. If "servicexml" was requested, and nil is returned, an attempt will be made to combine the upnp.webroot value with the SCPDURL element from the device description to locate the xml.

device:adddevice (device)

Adds a sub-device to the device.

Parameters:

• device: device object to add

device:addservice (service)

Adds a service to the device.

Parameters:

• service: service object to add

device:afterset (service, statevariable, oldval)

Handler called after the new value has been set to an owned statevariable (through a service).
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.
Call order; statevariable:afterset() -> service:afterset() -> device:afterset()

Parameters:

• service: the service (table/object) the statevariable is located in
• statevariable: the statevariable (table/object) whose value is being changed
• oldval: the previous value of the statevariable

See also:

• statevariable:beforeset
• device:beforeset

device:beforeset (service, statevariable, newval)

Handler called before the new value is set to an owned statevariable (through a service). The new value will have been checked and converted before this handler is called. Override in descendant classes to implement device behaviour. 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:

• service: the service (table/object) the statevariable is located in
• 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

See also:

• statevariable:beforeset
• device:afterset

device:executeaction (serviceid, actionname, params)

Executes an action on a service owned by the device.
Call order: device:executeaction() -> action:checkparams() -> service:executeaction() -> action:execute() -> action:checkresults()

Parameters:

• serviceid: ServiceId string, or service table/object
• actionname: Name of the action to execute, or action table/object
• params: table with argument values, indexed by argument name.

Return value:

2 lists (names and values) of the 'out' arguments (in proper UPnP order), or nil, errormsg, errornumber upon failure

See also:

• service:executeaction
• action:execute
• action:checkparams
• action:checkresults

device:getudn ()

Gets the udn (unique device name; UUID) of the device.

Return value:

udn of the device

device:initialize ()

Initializes the device object. Will be called upon instantiation of an object, override this method to set default values for all properties.

device:parsefromxml (xmldoc, creator, parent)

Device constructor method, creates a new device, parsed from a device xml. The device object will be created, including all services and sub devices.

Parameters:

• xmldoc: XML document from which a device 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 'device' element
• creator: callback function to create individual sub objects
• parent: the parent object for the device to be created (or nil if a root device)

Return value:

device object or nil + error message

See also:

• creator

device:setudn (newudn)

Sets the udn (unique device name; UUID) of the device. Adds the device to the global device list. Set it to nil to remove it from the global list and parent object (its own parent property will remain unchanged)

Parameters:

• newudn: New udn for the device

device:start ()

Startup handler. Called by upnpbase ancestor object for the event upnp.events.UPnPstarted (event through the Copas Timer eventer mechanism) When called it will call the start() method on all sub-devices. Override in child classes to add specific startup functionality (starting hardware comms for example) See also upnpbase:start()

device:stop ()

Shutdown handler. Called by upnpbase ancestor object for the event upnp.events.UPnPstopping (event through the Copas Timer eventer mechanism) When called it will call the stop() method on all sub-devices. Override in child classes to add specific shutdown functionality (stopping hardware comms for example) See also upnpbase:stop()