org.ocap.hn.upnp.client
Class UPnPControlPoint

java.lang.Object
  org.ocap.hn.upnp.client.UPnPControlPoint

public class UPnPControlPoint
extends Object

This class represents a device control point that can discover devices and services. It also offers a facility to directly monitor and modify communication between the control point and any devices.

Constructor Summary

protected

UPnPControlPoint() Construct the instance.

Method Summary

void	addDeviceListener(UPnPClientDeviceListener listener) Adds a listener for device changes.
UPnPClientDevice[]	getDevices() Gets a client representation of all UPnP root devices visible to this host.
UPnPClientDevice[]	getDevicesByServiceType(String type) Gets a client representation of all UPnP devices containing a service of the specified type, visible to this host.
UPnPClientDevice[]	getDevicesByType(String type) Gets a client representation of all UPnP devices of the specified type visible to this host.
UPnPClientDevice[]	getDevicesByUDN(String UDN) Gets a client representation of the UPnP devices of the specified UDN visible to this host.
InetAddress[]	getInetAddresses() Gets the InetAddresses that this UPnPControlPoint is associated with.
static UPnPControlPoint	getInstance() Obtain the local UPnP device control point.
void	removeDeviceListener(UPnPClientDeviceListener listener) Removes a device listener.
void	search(int mx) Initiate a UPnP M-SEARCH for UPnP root devices.
void	setIncomingMessageHandler(UPnPIncomingMessageHandler inHandler) Sets a message handler for incoming messages (advertisements, evented state variables, action responses, device and service descriptions).
InetAddress[]	setInetAddresses(InetAddress[] addresses) Sets the InetAddresses that the UPnPControlPoint is associated with.
void	setOutgoingMessageHandler(UPnPOutgoingMessageHandler outHandler) Sets a message handler for outgoing messages (action invocations, subscription requests, device and service retrievals).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UPnPControlPoint

protected UPnPControlPoint()

Construct the instance.

Method Detail

getInstance

public static UPnPControlPoint getInstance()

Obtain the local UPnP device control point.

Returns:

The singleton UPnPControlPoint.

setInetAddresses

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

Sets the InetAddresses that the UPnPControlPoint is associated with. The control point will only send searches and listen for device advertisements on the most appropriate interface for each of the addresses specified.

The passed array replaces any prior addresses that the control point was associated with. The control point may need to perform searches and update its list of devices in response to this method being invoked.

Note that the control point defaults to all home network interfaces with all their associated IP addresses. A client application would not normally need to invoke this method.

Parameters:

addresses - Array of InetAddress objects representing the IP addresses that the control point is associated with. May be zero length.

Returns:

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

Throws:

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

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

getInetAddresses

public InetAddress[] getInetAddresses()

Gets the InetAddresses that this UPnPControlPoint is associated with.

Returns:

Array of InetAddress objects representing the network interfaces that this control point is associated with. If the control point has no associated network interfaces, returns a zero length array.

getDevices

public UPnPClientDevice[] getDevices()

Gets a client representation of all UPnP root devices visible to this host. This does not cause a search to take place, but simply returns the currently known devices.

Returns:

The UPnP devices visible to this host. Each element in the array of UPnPClientDevices returned represents one root device found by the local host via UPnP discovery. If no root devices are found, returns a zero-length array.

getDevicesByType

public UPnPClientDevice[] getDevicesByType(String type)

Gets a client representation of all UPnP devices of the specified type visible to this host. This does not cause a search to take place, but simply returns the currently known devices.

Parameters:

type - The type of devices to return. Of the form urn:schemas-upnp-org:device:deviceType:v where deviceType is replaced with a type specific to the device being requested, and v is a version specifier as defined in UPnP Device Architecture.

Returns:

The UPnP devices visible to this host matching the type specified, of the specified version or lower version number. Each element in the array of UPnPClientDevices returned represents one device found by the local host via UPnP discovery. If no devices matching the type are found, returns a zero-length array.

getDevicesByUDN

public UPnPClientDevice[] getDevicesByUDN(String UDN)

Gets a client representation of the UPnP devices of the specified UDN visible to this host. This does not cause a search to take place, but simply returns the currently known devices.

Note that normally a UDN is unique and would return a single device. In multi-homed server and control point environments, a single server may be visible over multiple interfaces, resulting in multiple UPnPClientDevice representations.

Parameters:

UDN - The UDN of the devices to return.

Returns:

The UPnP devices visible to this host matching the UDN specified. Each element in the array of UPnPClientDevices returned represents one device found by the local host via UPnP discovery. If no devices matching the UDN are found, returns a zero-length array.

getDevicesByServiceType

public UPnPClientDevice[] getDevicesByServiceType(String type)

Gets a client representation of all UPnP devices containing a service of the specified type, visible to this host. This does not cause a search to take place, but simply returns the currently known devices.

Parameters:

type - The type of service to use in determining which devices to return. Of the form urn:schemas-upnp-org:service:serviceType:v where serviceType is replaced with a type specific to the service being requested, and v is a version specifier as defined in UPnP Device Architecture.

Returns:

The UPnP devices visible to this host containing a service matching the type specified, of the specified version or lower version number. Each element in the array of UPnPClientDevices returned represents one device found by the local host via UPnP discovery. Returns only devices directly containing a service of the matching type, not devices where only their embedded devices contain a service of the matching type. If no devices matching the criteria are found, returns a zero-length array.

search

public void search(int mx)

Initiate a UPnP M-SEARCH for UPnP root devices. The UPnP stack constantly monitors for device arrival and departure. This method is used to assist with detection of devices which may not renew advertisements correctly and only respond to search requests.

Parameters:

mx - The maximum time in seconds for client devices to respond to this search.

addDeviceListener

public void addDeviceListener(UPnPClientDeviceListener listener)

Adds a listener for device changes. Each UPnPClientDeviceListeneris notified when a UPnP device is added to or removed from a home network.

Adding a listener which is the same instance as a previously added (and not removed) listener has no effect.

Parameters:

listener - The listener to add.

removeDeviceListener

public void removeDeviceListener(UPnPClientDeviceListener listener)

Removes a device listener.

Parameters:

listener - The listener to remove.

setIncomingMessageHandler

public void setIncomingMessageHandler(UPnPIncomingMessageHandler inHandler)
                               throws SecurityException

Sets a message handler for incoming messages (advertisements, evented state variables, action responses, device and service descriptions). Calls to set the message handler replace any prior incoming message handler.

A message handler may be removed by passing null as the inHandler. In the absence of a registered message handler the stack will parse the incoming messages.

If the application-provided handler throws any exceptions during execution, the stack will attempt to process the message with the default (stack-provided) handler.

Parameters:

inHandler - The incoming message handler to set.

Throws:

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

setOutgoingMessageHandler

public void setOutgoingMessageHandler(UPnPOutgoingMessageHandler outHandler)
                               throws SecurityException

Sets a message handler for outgoing messages (action invocations, subscription requests, device and service retrievals). Calls to set the message handler replace any prior outgoing message handler.

A message handler may be removed by passing null as the outHandler. In the absence of a registered message handler the stack will process the outgoing messages.

If the application-provided handler throws any exceptions during execution, the stack will attempt to process the message with the default (stack-provided) handler.

Parameters:

outHandler - The outgoing message handler to set.

Throws:

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