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 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.

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

SetPort(port As roMessagePort)

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).