roUPnPController

this object establishes and maintains a upnp control point it must exist for the entirety of upnp discovery operations refer to the upnp device architecture http //www upnp org/specs/arch/upnp arch devicearchitecture v1 0 pdf document for more information about upnp discovery protocols object creation the roupnpcontroller object is created without any parameters createobject("roupnpcontroller") ifupnpcontroller setdebug(debug as boolean) as void enables detailed debugging in the upnp engine search(searchtarget as string, mx as integer) as boolean issues a search request for a upnp device the parameters correspond to the st (search target) and mx (maximum wait time) header values that are sent with a upnp m search command responses to the search request will generate messages in the form of roupnpsearchevent objects the most common value for the searchtarget parameter is "upnp\ rootdevice" this allows you to search all root devices, identify which devices you wish to interact with, and then get the roupnpdevice and upnpservice instances for these embedded devices and services removedevice(udn as string) as boolean forces removal of the specified device from the control point device list the passed string must include " uuid " prepended to the udn value ifmessageport specifies the port that will receive events generated by the roupnpcontroller instance ifuserdata setuserdata(user data as object) sets the user data that will be returned when events are raised getuserdata() as object returns the user data that has previously been set via setuserdata() it will return invalid if no data has been set upnp controller operation the roupnpcontroller object maintains a list of all currently detected upnp devices accessible via the local network to maintain this list, the roupnpcontroller object follows these generally accepted control point practices if an ssdp\ alive multicast notification is received from a device that is not part of the list, it is queried for its device information and added to the list however, the ssdp\ alive message is not intended as the primary means for device discovery; rather, this behavior is intended to keep the list up to date and remove devices that disappear without an ssdp\ byebye notification if an ssdp\ byebye multicast notification is received form a device that is part of the list, it will be removed from the list the upnp controller allows a client to issue a search request for upnp devices all devices on the network are expected to respond directly to the requesting device if a response is received from a device that is not part of the list, it is queried for its device information and added to the list upnp devices report a "time to live" for notifications for upnp notify and search response messages, this is contained in the "cache control max age" header typically, this "time to live" is 20 or 30 minutes, though some devices have much shorter time values every device is configured to expire after its "time to live" is reached, at which point it is removed from the device list the counter is reset (i e the device is renewed) after each receipt of an ssdp\ alive message brightscript does not allow direct access to its internal devicelist rather, it raises events in the form of roupnpsearchevent objects when devices are added or removed from the list these objects can, in turn, be used to retrieve roupnpdevice objects containing all device information the controller also raises events whenever it receives a notify multicast message or a response to an m search message (i e a response to a controller search request) these events return associative arrays containing headers from the notify multicast message or from the http response to the m search message the associative arrays may also contain additional non header items for an ssdp multicast message notification (type 0), the associative array will contain an "ssdptype" key, the value of which designates whether it is a notify or m search message in most cases, it is best to ignore m search messages, unless you are implementing a upnp device (the upnp controller object does allow this) during an m search request, a "new device" notification (type 2) will only be sent when a device is added to the controller's internal list once a device is part of the device list, subsequent m search requests will only return type 1 (search response) values for that device this type 1 response returns an associative array with message headers, but not an roupnpdevice object (which is used to contain a complete set of device information) see the roupnpsearchevent page for more information about the messages sent by the upnp controller