= Developer Documentation =

The UPnP Event Proxy is a daemon which works around a [http://bugs.micasaverde.com/view.php?id=2529 known bug] in the MiOS web server implementation (namely, that it does not accept '''NOTIFY''' HTTP messages).  

The proxy runs a simple Lua web server at Vera startup, which listens for a small set of HTTP commands, which are either '''NOTIFY''' messages, or requests from Vera plugins to be informed when a '''NOTIFY''' message is received.  When the proxy receives a '''NOTIFY''' message, it sends a Luup [http://wiki.micasaverde.com/index.php/Luup_Requests#action action] message to the plugin so that it can act upon the notification.

== Typical use case ==

'''NOTIFY''' is one of the message types defined in the UPnP standard, and is used when a UPnP device needs to tell a UPnP control point about a state variable that has changed.  For example, a UPnP device such as a WeMo motion sensor may have detected motion, or a UPnP media device such as a Sonos may have had its volume level changed by the user.

MiOS plugins that interact with UPnP devices may wish to be informed of these events, so that they can modify the dashboard UI to match, or so that they can fire a scene trigger.

The UPnP mechanism that the plugin uses is to send a UPnP '''SUBSCRIBE''' message to the UPnP device.  Inside this '''SUBSCRIBE''' message is the URL that the device should try to contact whenever the event occurs.  The UPnP device will immediately return a unique string, a ''subscription identifier'' (SID).  Any time that the event occurs, the UPnP device will send a '''NOTIFY''' message to the callback URL, quoting this SID, so that the receiver knows which device has had the event.

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.

== Registering a subscription with the proxy ==

TODO

== Receiving an event notification from the proxy ==

TODO

== Renewing the subscription ==

TODO

== Cancelling the subscription ==

TODO

== Avoiding deadlocks ==

TODO