Module "upnp"

LuaUPnP is a binding for the pupnp library for Lua.
The library has dependencies on LuaSocket, Copas, CopasTimer, LuaLogging, date, Loop, DarkSideSync and pupnp. When 'required' it will load all required modules, the core UPnP library, all devices classes, etc. Only devices need to be set up before calling copas.loop() to start the scheduler.
A global upnp will be created and it will be returned.

Note: the global print() function will be remapped to the logger, so everything printed will be logged at the info level.

Copyright © 2012 Thijs Schreijer, LuaUPnP is licensed under GPLv3

Release: Version 0.x, LuaUPnP.

Tables

upnp members and namespaces List of members and namespaces within LuaUPnP.
upnp.events Events generated by upnp library for starting and stopping.

Functions

getconfigfilename (configname) Takes a config filename and returns the path to the file to open.
os.exit (...) wraps original os.exit() function to make sure UPnP lib is always properly stopped
upnp.existsconfigfile (configname) Does a configfile exist.
upnp.getxml (xmldoc) Gets an xml document.
upnp.lib.util.CreateUUID () wraps original function to work even when library is not started
upnp.readconfigfile (configname, defaults) Read a configfile.
upnp.startdevice (rootdev) Starts a UPnP device.
upnp.stopdevice (hdl) Stops a UPnP device.
upnp.subscribe () Subscribe to events of upnp library.
upnp.unsubscribe () Unsubscribe from events of upnp library.
upnp.writeconfigfile (configname, content, comment) Write a configfile.


Tables

upnp members and namespaces
List of members and namespaces within LuaUPnP.

Fields

  • classes: holds a list of classes for upnp devices; upnpbase, device, service, etc.
  • devices: list of registered devices indexed by their UDN
  • logger: the logger in use by the upnp module (all print() commands will be rerouted here)
  • webroot: path of the web-root directory
  • baseurl: base url pointing to the web-root directory
  • configroot: base directory for configuration information
  • lib: contains the mapped functions of pupnp library
  • lib.web: contains the mapped functions of upnp web methods
  • lib.http: contains the mapped functions of upnp http methods
  • lib.util: contains the mapped functions of upnp util methods + CreateUUID
  • lib.ixml: contains the mapped functions of upnp ixml methods
upnp.events
Events generated by upnp library for starting and stopping. Besides these events there are additional events from copas as that scheduler is used (see 'CopasTimer' and specifically the copas.eventer module).

Fields

  • UPnPstarting: This event is started on the copas.events.loopstarted event and executes before any UPnP code is being run. Only when this event is complete (all handlers spawned have finished) the UPnP code will start. Use this event to setup any UPnP devices.
  • UPnPstarted: Runs after the UPnP library has been initiated and is running. The device object typically start themselves on this event and will announce themselves.
  • UPnPstopping: This event is started from the copas.events.loopstopping event and executes before any UPnP code is being torn down. Only when this event is complete (all handlers spawned have finished) the UPnP code will initiate the teardown. The device object typically will stop itself on this event.
  • UPnPstopped: Runs after the UPnP code has been stopped

Functions

getconfigfilename (configname)
Takes a config filename and returns the path to the file to open. An automatic extension '.config' will be appended.

Parameters:

  • configname: filename of configfile (only the filename part of a path will be used, path and '.config' extension will stripped from the provided name)

Return value:

path to config file, being upnp.configroot combined with the config filename
os.exit (...)
wraps original os.exit() function to make sure UPnP lib is always properly stopped

Parameters:

  • ...:
upnp.existsconfigfile (configname)
Does a configfile exist.

Parameters:

  • configname: configuration filename to check.

Return value:

boolean
upnp.getxml (xmldoc)
Gets an xml document. It will try to get the xml from several things; 1) filename, 2) literal xml, 3) IXML object. If a filename is given, it will first try to open, if it fails it will try again relative to the upnp.webroot directory.

Parameters:

  • xmldoc: either 1) filename, 2) literal xml, 3) IXML object

Return value:

IXML object or nil + errormessage
upnp.lib.util.CreateUUID ()
wraps original function to work even when library is not started
upnp.readconfigfile (configname, defaults)
Read a configfile. The configfile must be a lua table format, starting with ' return {' and ending with '}'.

Parameters:

  • configname: configuration filename to load. This should only be a filename (no path), and it will be sought for in the upnp.configroot directory.
  • defaults: table with defaults to return when the configfile does not exist. If not provided, it will be set to an empty table.

Return values:

  1. table with configuration loaded, or defaults if it failed. The returned table will have the defaults table set as its metatable, so any value not in the configfile will be returned from the defaults.
  2. 2nd return value is an error message in case an error was encountered while loading the config file. NOTE: the configfile not existing is not considered an error.
upnp.startdevice (rootdev)
Starts a UPnP device. Registers the device with the lib to enable network comms and callbacks.

Parameters:

  • rootdev: device object, must be a root device with the rootdev.devicexmlurl set to the relative path within the webroot path, where the device description xml can be downloaded.

Return value:

handle to the newly registered device or nil + error message
upnp.stopdevice (hdl)
Stops a UPnP device. Unregisters the device with the lib to disable network comms and callbacks.

Parameters:

  • hdl: handle to the currently enabled device

Return value:

1 on success, or nil + error message
upnp.subscribe ()
Subscribe to events of upnp library. These are not individual device/service event, but library events.
upnp.unsubscribe ()
Unsubscribe from events of upnp library.
upnp.writeconfigfile (configname, content, comment)
Write a configfile. The configfile must be a string in Lua table format, starting with ' return {' and ending with '}'.

Parameters:

  • configname: configuration filename to write to. This should only be a filename only (no path), and it will be stored in the upnp.configroot directory.
  • content: table; the content to write
  • comment: string (optional); text block to write at start of config file

Return value:

1 on success, nil + errormsg upon failure

Valid XHTML 1.0!