Changes between Version 1 and Version 2 of develop

Timestamp:

2013-04-13 11:53:48 (12 years ago)

Author:

futzle

Comment:

--

develop

@@ -15 +15 @@
 The MiOS LuaUPnP process cannot receive '''NOTIFY''' messages, so the plugin instead nominates the UPnP Event Proxy daemon as the callback URL.  The plugin must also inform the UPnP Event Proxy daemon of the SID, and which Luup action on the plugin to invoke when the event occurs.
 
+== Setup code ==
+
+The example code below assumes these variables:
+
+{{{
+http = require("socket.http")
+ltn12 = require("ltn12")
+function socketWithTimeout(timeout)
+  local s = socket.tcp()
+  s:settimeout(timeout)
+  return s
+end
+}}}
+
 == Registering a subscription with the proxy ==
 
-TODO
+In this example, the plugin at MiOS deviceId ''deviceId'' is interested in knowing about changes to the UPnP variable ''UPnPVariable''.
+
+Sending the UPnP SUBSCRIBE request is outside the scope of this document.  For example code, see the Belkin WeMo plugin function [http://code.mios.com/trac/mios_belkin-wemo/browser/L_WeMo1.lua#L327 subscribeToDevice()].  The callback URL must be <http://''vera-address'':2529/upnp/event>.
+
+After the '''SUBSCRIBE''' request succeeds, the plugin will have a subscription identifier (SID) ''sid'', and a duration in seconds ''timeout''.  For the next ''timeout'' seconds, the UPnP device will send '''NOTIFY''' messages to the callback URL.
+
+The plugin has an action ''VariableChanged'' in service ''pluginServiceId'' which accepts two parameters: ''valueParam'' (the new value of the varable), and ''sidParam'' (the subscription identifier).  The plugin wants this action to be invoked by the proxy every time that ''UPnPVariable'' changes.
+
+To register the subscription with the proxy, perform an HTTP '''PUT''' to /upnp/event/''sid'':
+
+{{{
+local proxyRequestBody = "<subscription expiry='" .. os.time() + timeout .. "'>"
+proxyRequestBody = proxyRequestBody ..
+  "<variable name='UPnPVariable' host='localhost' deviceId='" ..
+  deviceId .. "' serviceId='pluginServiceId' " ..
+  "action='VariableChanged' parameter='valueParam' sidParameter='sidParam'/>"
+proxyRequestBody = proxyRequestBody .. "</subscription>"
+local request, code = http.request({
+  url = "http://localhost:2529/upnp/event/" .. url.escape(sid),
+  create = socketWithTimeout(2),
+  method = "PUT",
+  headers = {
+    ["Content-Type"] = "text/html",
+    ["Content-Length"] = proxyRequestBody:len(),
+  },
+  source = ltn12.source.string(proxyRequestBody),
+  sink = ltn12.sink.null(),
+})
+if (request == nil and code ~= "closed") then
+  -- Failed (timeout?)
+elseif (code ~= 200) then
+  -- Failed (refused)
+else
+  -- Succeeded
+end
+}}}
+
+The proxy will soon receive (or may have already received) the initial UPnP '''NOTIFY''' (with sequence 0), and will invoke the ''VariableChanged'' action on the plugin.
 
 == Receiving an event notification from the proxy ==
 
-TODO
+The plugin should have an action ''VariableChanged'', matching the ''serviceId'' and ''action'' parameters supplied in the previous section's sample code.  In the
+
+{{{
+<action>
+  <serviceId>pluginServiceId</serviceId>
+  <name>VariableChanged</name>
+  <run>
+    doSomethingWith(lul_device, lul_settings.valueParam, lul_settings.sidParam)
+  </run>
+</action>
+}}}
+
+The ''doSomethingWith'' function will be called with the value of ''UPnPVariable'' from each notification from the UPnP device, and the SID mentioned in the event.  Normally this function will set a Luup variable to reflect the reported change in the variable.
 
 == Renewing the subscription ==
 
-TODO
+Before ''timeout'' seconds have passed, the plugin must renew the subscription with the UPnP device.  The code to do this is outside the scope of this document.
+
+If the renewal succeeds, a new timeout will be supplied by the UPnP device.  The plugin must inform the proxy of the new expiry, using code exactly the same as the initial registration.  This '''PUT''' request completely replaces the previous registration, so it must mention all variables again.
 
 == Cancelling the subscription ==
 
-TODO
+In most cases, the plugin will want to keep renewing the subscription indefinitely.  If the plugin knows that a subscription should be cancelled, it can ask the proxy to stop forwarding the event to the plugin with an HTTP '''DELETE''':
+
+{{{
+local request, code = http.request({
+  url = "http://localhost:2529/upnp/event/" .. url.escape(sid),
+  create = socketWithTimeout(2),
+  method = "DELETE",
+  headers = {
+    ["Content-Length"] = 0,
+  },
+  source = ltn12.source.empty(),
+  sink = ltn12.sink.null(),
+})
+if (request == nil and code ~= "closed") then
+  -- Failed (timeout?)
+elseif (code ~= 200) then
+  -- Failed (refused)
+else
+  -- Succeeded
+end
+}}}
+
+If the Luup engine is restarted, the plugin will not have an opportunity to cancel a subscription, and the proxy will send events that were registered before the Luup engine was restarted.  The plugin can use the ''sidParam'' value to see if this has happened.  Eventually the subscription will expire and the plugin will stop receive notifications.
 
 == Avoiding deadlocks ==