org.ocap.hn.upnp.server

Interface UPnPManagedDevice

All Superinterfaces:

UPnPDevice

public interface UPnPManagedDevice
extends UPnPDevice

This interface represents a locally hosted UPnP device created when a privileged application uses UPnPDeviceManager.createDevice to create a device.

The UPnPManagedDevice corresponds to a single UPnP server device with a single set of handlers and a single state. This server may be visible on multiple interfaces and/or multiple IP addresses, depending upon the list of InetAddresses that are associated with this server device. The network representations of this device (UPnPAdvertisedDevice), one per InetAddress, are available for query via the getAdvertisedDevices() method.

Updating a device causes corresponding UPnP device byebye/alive pairs to be sent. To institute multiple changes without multiple removals/advertisements, the application should call the sendByeBye() method prior to the first change, calling sendAlive() following the last change.

Method Summary

Methods

Modifier and Type	Method and Description
UPnPManagedService	createService(String serviceType, InputStream description, UPnPActionHandler handler) Creates a UPnP service associated with this device.
UPnPAdvertisedDevice[]	getAdvertisedDevices() Gets the representations of this device on the network interfaces on which is it advertised.
String	getDeviceType() Gets the UPnP deviceType of this device.
UPnPManagedDevice[]	getEmbeddedDevices() Gets any UPnPManagedDevice embedded devices for this UPnPManagedDevice.
String	getFriendlyName() Gets the UPnP "friendly name" of this device.
UPnPManagedDeviceIcon[]	getIcons() Gets the icons for this device.
InetAddress[]	getInetAddresses() Gets the InetAddresses that this UPnPManagedDevice is associated with.
String	getManufacturer() Gets the UPnP manufacturer of this device.
String	getManufacturerURL() Gets the UPnP manufacturer URL of this device.
String	getModelDescription() Gets the UPnP model description of this device.
String	getModelName() Gets the UPnP model name of this device.
String	getModelNumber() Gets the UPnP model number of this device.
String	getModelURL() Gets the UPnP model URL of this device.
UPnPManagedDevice	getParentDevice() Returns the parent device of this UPnPManagedDevice.
String	getSerialNumber() Gets the UPnP serial number of this device.
UPnPManagedService[]	getServices() Gets the services supported by this device.
String	getSpecVersion() Gets the UPnP specVersion major and minor values of this UPnP device, or of the root UPnP device containing this device.
String	getUDN() Gets the UPnP Unique Device Name of this device.
String	getUPC() Gets the UPnP Universal Product Code of this device.
boolean	isAlive() Gets whether the UPnPManagedDevice is active.
boolean	isRootDevice() Reports whether this UPnP device is a UPnP root device.
void	sendAlive() Sends UPnP ssdp:alive messages from the physical device.
void	sendByeBye() Sends UPnP ssdp:byebye messages from this device.
boolean	setDeviceType(String type) Sets the UPnP deviceType of this device.
boolean	setFriendlyName(String friendlyName) Sets the UPnP friendlyName of this device.
UPnPManagedDeviceIcon[]	setIcons(UPnPManagedDeviceIcon[] icons) Sets the Icons for this device.
InetAddress[]	setInetAddresses(InetAddress[] addresses) Sets the InetAddresses that this UPnPManagedDevice is associated with.
boolean	setManufacturer(String manufacturer) Sets the UPnP manufacturer of this device.
boolean	setManufacturerURL(String manufacturerURL) Sets the UPnP manufacturer URL of this device.
boolean	setModelDescription(String modelDescription) Sets the UPnP model description of this device.
boolean	setModelName(String modelName) Sets the UPnP model name of this device.
boolean	setModelNumber(String modelNumber) Sets the UPnP model number of this device.
boolean	setModelURL(String modelURL) Sets the UPnP model URL of this device.
boolean	setSerialNumber(String serialNumber) Sets the UPnP serial number of this device.
boolean	setUDN(String UDN) Sets the UPnP Unique Device Number of this device.
boolean	setUPC(String UPC) Sets the UPnP Universal Product Code of this device.

Method Detail

sendAlive

void sendAlive()
               throws SecurityException

Sends UPnP ssdp:alive messages from the physical device. Sends a 3+2D+k series of alive messages as defined by the UPnP Device Architecture specification on each IP address and network interface associated with the UPnPManagedDevice. Enters the "alive" state once the first advertisements are initiated on the first InetAddress/interface.

If the UPnPManagedDevice has no associated InetAddress, no advertisements are sent and the device does not enter the "alive" state.

If the device is already in the "alive" state, the device still sends advertisements and remains in the "alive" state.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

See Also:

isAlive()

sendByeBye

void sendByeBye()
                throws SecurityException

Sends UPnP ssdp:byebye messages from this device. Sends a byebye message for each device and service corresponding to alive messages that would be sent by the sendAlive method.

Once the last byebye message has been sent on the last InetAddress, the device enters the "not alive" state and is no longer discoverable via UPnPDeviceManager.getDevices(). At this point, the UPnP implementation holds no internal references to this UPnPManagedDevice object.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

See Also:

isAlive()

setInetAddresses

InetAddress[] setInetAddresses(InetAddress[] addresses)
                               throws SecurityException

Sets the InetAddresses that this UPnPManagedDevice is associated with. The device will send advertisements (and de-advertise) on the most appropriate interface for each of the addresses specified, and will respond to actions on each of those interfaces.

The passed array replaces any prior addresses that the device was associated with, including any stack-provided defaults. If the device is already active on one or more addresses, it must de-advertise itself at any addresses that are being removed, and advertise itself at any addresses that are being added.

The device description advertised on each interface will be identical with the exception of the URLs related to the device and its components, which will reflect the IP address on which the device is advertised.

Note that it is the responsibility of the application to monitor for changes in IP addresses that the host responds to, and to update the UPnPManagedDevice with any modifications using this method.

Parameters:

addresses - Array of InetAddress objects representing the IP addresses that this device is to advertise as. May be zero length.

Returns:

Array of prior addresses that were associated with the UPnPManagedDevice. If there were no prior addresses, returns a zero-length array.

Throws:

NullPointerException - if addresses or any of its elements are null.

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

See Also:

getInetAddresses()

getInetAddresses

InetAddress[] getInetAddresses()

Gets the InetAddresses that this UPnPManagedDevice is associated with. If setInetAddresses(java.net.InetAddress[]) has not yet been called on this UPnPManagedDevice, this method will report the default InetAddresses provided by the stack.

Returns:

Array of InetAddress objects representing the network interfaces that this device is to advertise on. If the device has no associated network interfaces, returns a zero length array.

isAlive

boolean isAlive()

Gets whether the UPnPManagedDevice is active. The device is active if it has valid advertisements on one or more network interfaces.

While the device is in the "alive" state, the device:

• responds to SSDP discovery requests on the home network, conforming to the UPnP Device Architecture
• continues to automatically send SSDP "alive" messages conforming to the UPnP Device Architecture, prior to the expiration of prior alive messages
• may be discovered through UPnPDeviceManager.getDevices().

Returns:

True if the UPnPManagedDevice has valid advertisements on one or more network interfaces, else false.

getAdvertisedDevices

UPnPAdvertisedDevice[] getAdvertisedDevices()

Gets the representations of this device on the network interfaces on which is it advertised. Since the UPnP device description contains network-dependent information, there can be multiple UPnPAdvertisedDevice objects associated with a single UPnPManagedDevice. The returned array corresponds to the set of UPnP device descriptions published for this UPnP device.

Returns:

The network representations of this UPnPManagedDevice. Returns a zero-length array if this device has not been advertised on a network interface.

getEmbeddedDevices

UPnPManagedDevice[] getEmbeddedDevices()

Gets any UPnPManagedDevice embedded devices for this UPnPManagedDevice. Returns an array of UPnPManagedDevices, one per device appearing in this device's deviceList element. Does not recurse through embedded devices of this device.

Returns:

The embedded devices for this device. If there are no embedded devices of this device then returns a zero length array.

getParentDevice

UPnPManagedDevice getParentDevice()

Returns the parent device of this UPnPManagedDevice.

Returns:

A UPnPManagedDevice representing this device's parent device. Returns null if this device has no parent.

setDeviceType

boolean setDeviceType(String type)
                      throws SecurityException

Sets the UPnP deviceType of this device. This value is placed in the deviceType element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

type - The deviceType to be set for this device.

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setFriendlyName

boolean setFriendlyName(String friendlyName)
                        throws SecurityException

Sets the UPnP friendlyName of this device. This value is placed in the friendlyName element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

friendlyName - The friendlyName to set for this device

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setManufacturer

boolean setManufacturer(String manufacturer)
                        throws SecurityException

Sets the UPnP manufacturer of this device. This value is placed in the manufacturer element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

manufacturer - The manufacturer to set for this device

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setManufacturerURL

boolean setManufacturerURL(String manufacturerURL)
                           throws SecurityException

Sets the UPnP manufacturer URL of this device. This value is placed in the manufacturerURL element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

manufacturerURL - The manufacturerURL to set for this device

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setModelDescription

boolean setModelDescription(String modelDescription)
                            throws SecurityException

Sets the UPnP model description of this device. This value is placed in the modelDescription element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

modelDescription - The modelDescription to set for this device

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setModelName

boolean setModelName(String modelName)
                     throws SecurityException

Sets the UPnP model name of this device. This value is placed in the modelName element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

modelName - The modelName to set for this device

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setModelNumber

boolean setModelNumber(String modelNumber)
                       throws SecurityException

Sets the UPnP model number of this device. This value is placed in the modelNumber element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

modelNumber - The modelNumber to set for this device.

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setModelURL

boolean setModelURL(String modelURL)
                    throws SecurityException

Sets the UPnP model URL of this device. This value is placed in the modelURL element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

modelURL - The modelURL to set for this device.

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setSerialNumber

boolean setSerialNumber(String serialNumber)
                        throws SecurityException

Sets the UPnP serial number of this device. This value is placed in the serialNumber element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

serialNumber - The serialNumber to set for this device.

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setUDN

boolean setUDN(String UDN)
               throws SecurityException

Sets the UPnP Unique Device Number of this device. This value is placed in the UDN element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

UDN - The UDN to set for this device.

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setUPC

boolean setUPC(String UPC)
               throws SecurityException

Sets the UPnP Universal Product Code of this device. This value is placed in the UPC element within the device description. Adds the element if it is not already present. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

UPC - The UPC to set for this device.

Returns:

True if the setting caused a byebye/alive cycle for this device, false if not.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

setIcons

UPnPManagedDeviceIcon[] setIcons(UPnPManagedDeviceIcon[] icons)
                                 throws SecurityException

Sets the Icons for this device. The passed array of UPnPManagedDeviceIcons is used to generate the iconList sub-document of the device. Replaces any previous iconList for this device. If the array is of zero length, removes any prior iconList from the device description. If the device is currently published on one or more network addresses, this causes a byebye/alive cycle for this device on all published addresses.

Parameters:

icons - An array of UPnPManagedDeviceIcons to be used for the IconList of this device. Each icon in the array is copied into the UPnPManagedDevice; subsequent calls to getIcons() will return different instances than those specified by the icons parameter. May be a zero-length array to indicate no icons.

Returns:

An array of UPnPManagedDeviceIcons representing the previous device icons. If there were no previous device icons, returns a zero-length array.

Throws:

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

getIcons

UPnPManagedDeviceIcon[] getIcons()

Gets the icons for this device.

Returns:

An array of UPnPManagedDeviceIcons representing the current device icons. If no icons are present on the device, returns a zero-length array.

getServices

UPnPManagedService[] getServices()

Gets the services supported by this device. Does not return services contained in embedded devices of this device.

Returns:

An array of UPnPManagedService objects. If there are no services associated with this UPnPManagedDevice, this method returns a zero length array.

createService

UPnPManagedService createService(String serviceType,
                               InputStream description,
                               UPnPActionHandler handler)
                                 throws IOException,
                                        SecurityException

Creates a UPnP service associated with this device. If this device is currently advertised, causes a byebye/alive process to be followed. Note that the USN and serviceId elements are generated by the stack and not provided as parameters.

Parameters:

serviceType - The UPnP service type of the service to be populated in the serviceType element of the device description.

description - The service description as defined by the UPnP Device Architecture specification. The InputStream format is an XML document representing the description.

handler - The action handler that will handle action requests for the service.

Returns:

The UPnP service created from the description. Returns null if the host platform does not support service advertisement.

Throws:

IllegalArgumentException - if the description parameter does not comply with a service description as defined by the UPnP Device Architecture specification.

IOException - if an I/O error occurs on the description.

SecurityException - if the calling application has not been granted MonitorAppPermission("handler.homenetwork").

getDeviceType

String getDeviceType()

Gets the UPnP deviceType of this device. This value is taken from the value of the deviceType element within the device description.

Specified by:

getDeviceType in interface UPnPDevice

Returns:

The type of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getDeviceType().

getFriendlyName

String getFriendlyName()

Gets the UPnP "friendly name" of this device. This value is taken from the value of the friendlyName element within the device description.

Specified by:

getFriendlyName in interface UPnPDevice

Returns:

The friendlyName of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getFriendlyName().

getManufacturer

String getManufacturer()

Gets the UPnP manufacturer of this device. This value is taken from the value of the manufacturer element within the device description.

Specified by:

getManufacturer in interface UPnPDevice

Returns:

the manufacturer of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getManufacturer().

getManufacturerURL

String getManufacturerURL()

Gets the UPnP manufacturer URL of this device. This value is taken from the value of the manufacturerURL element within the device description. If the manufacturerURL is empty or not present, returns the empty String.

Specified by:

getManufacturerURL in interface UPnPDevice

Returns:

The manufacturerURL of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getManufacturerURL().

getModelDescription

String getModelDescription()

Gets the UPnP model description of this device. This value is taken from the value of the modelDescription element within the device description. If the modelDescription is empty or not present, returns the empty String.

Specified by:

getModelDescription in interface UPnPDevice

Returns:

The modelDescription of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getModelDescription().

getModelName

String getModelName()

Gets the UPnP model name of this device. This value is taken from the value of the modelName element within the device description.

Specified by:

getModelName in interface UPnPDevice

Returns:

The modelName of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getModelName().

getModelNumber

String getModelNumber()

Gets the UPnP model number of this device. This value is taken from the value of the modelNumber element within the device description. If the modelNumber is empty or not present, returns the empty String.

Specified by:

getModelNumber in interface UPnPDevice

Returns:

The modelNumber of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getModelNumber().

getModelURL

String getModelURL()

Gets the UPnP model URL of this device. This value is taken from the value of the modelURL element within the device description. If the modelURL is empty or not present, returns the empty String.

Specified by:

getModelURL in interface UPnPDevice

Returns:

The modelURL of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getModelURL().

getSerialNumber

String getSerialNumber()

Gets the UPnP serial number of this device. This value is taken from the value of the serialNumber element within the device description. If the serialNumber is empty or not present, returns the empty String.

Specified by:

getSerialNumber in interface UPnPDevice

Returns:

The serialNumber of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getSerialNumber().

getSpecVersion

String getSpecVersion()

Gets the UPnP specVersion major and minor values of this UPnP device, or of the root UPnP device containing this device. This value is taken from the value of the major and minor sub elements of the specVersion element within the device description. The format of the returned String is the <major> value, followed by '.', followed by the <minor> value.

Specified by:

getSpecVersion in interface UPnPDevice

Returns:

The UPnP specVersion of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getSpecVersion().

getUDN

String getUDN()

Gets the UPnP Unique Device Name of this device. This value is taken from the value of the UDN element within the device description.

Specified by:

getUDN in interface UPnPDevice

Returns:

The UDN of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getUDN().

getUPC

String getUPC()

Gets the UPnP Universal Product Code of this device. This value is taken from the value of the UPC element within the device description. If the UPC is empty or not present, returns the empty String.

Specified by:

getUPC in interface UPnPDevice

Returns:

The UPC of this device. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].getUPC().

isRootDevice

boolean isRootDevice()

Reports whether this UPnP device is a UPnP root device.

Specified by:

isRootDevice in interface UPnPDevice

Returns:

true if this UPnP device represents a root device, false if not. If the device has been advertised, this method returns the same value as getAdvertisedDevices()[0].isRootDevice().