org.ocap.hn.upnp.server
Interface UPnPManagedService

All Superinterfaces:

UPnPService

public interface UPnPManagedService
extends UPnPService

This interface provides the server representation of a UPnP service created when a privileged application uses the UPnPDeviceManager in the local host.

Method Summary

UPnPAction	getAction(String actionName) Gets the named action from this service.
UPnPActionHandler	getActionHandler() Gets the current action handler for this service.
UPnPAction[]	getActions() Gets the actions that can be used with this service.
UPnPAdvertisedService[]	getAdvertisedServices() Gets the representations of this service on the network interfaces on which is it advertised.
UPnPManagedDevice	getDevice() Gets the UPnP device that this service is a part of.
String	getServiceId() Gets the UPnP serviceId of this service.
String	getServiceType() Gets the UPnP serviceType of this service.
String	getSpecVersion() Gets the UPnP specVersion major and minor values of this service.
UPnPManagedStateVariable[]	getStateVariables() Gets the state variables that are part of this service definition.
boolean	getSubscribedStatus() Reports the subscription status of the service.
void	respondToQueries(boolean respond) Control whether the service responds to UPnP QueryStateVariable actions.
UPnPActionHandler	setActionHandler(UPnPActionHandler handler) Sets an action handler for this service, replacing any prior action handler.
UPnPStateVariableHandler	setHandler(UPnPStateVariableHandler handler) Sets a UPnPStateVariableHandler to this UPnPManagedService.

Method Detail

setActionHandler

UPnPActionHandler setActionHandler(UPnPActionHandler handler)
                                   throws SecurityException

Sets an action handler for this service, replacing any prior action handler.

Parameters:

handler - UPnPActionHandler to be set for this managed service.

Returns:

Previous action handler, if any; null, if none.

Throws:

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

See Also:

UPnPActionHandler

getActionHandler

UPnPActionHandler getActionHandler()

Gets the current action handler for this service. If no action server is registered, returns null.

Returns:

Current action handler, if any; null if none.

See Also:

UPnPActionHandler

respondToQueries

void respondToQueries(boolean respond)
                      throws SecurityException

Control whether the service responds to UPnP QueryStateVariable actions.

If respond is true, the UPnP stack will respond to the QueryStateVariable action invocation with a value from any registered UPnPManagedStateVariableHandler, or with the most recently set value for the state value if no handler is registered, or with the default value of the state variable if no handler is registered and no calls to UPnPManagedStateVariable.setValue() have been made. If respond is false, responds with an error as defined by UPnP Device Architecture 1.0, with UPnPError errorCode of 401 (Invalid Action).

If respond is true and a request is received with a state variable name that is not part of this service, responds with an error as defined by UPnP Device Architecture 1.0, with UPnPError errorCode of 404 (Invalid Var).

Parameters:

respond - True to cause the stack to respond to QueryStateVariable actions, returning the current state variable value to the UPnP control point. False to refuse QueryStateVariable actions with UPnP errorCode of 401 (Invalid Action).

Throws:

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

getAdvertisedServices

UPnPAdvertisedService[] getAdvertisedServices()

Gets the representations of this service on the network interfaces on which is it advertised. Since the UPnP device and service descriptions contain network-dependent information, there can be multiple UPnPAdvertisedService objects associated with a single UPnPManagedService.

Returns:

The network representations of this UPnPManagedService. Returns a zero-length array if the service has not been advertised on a network interface.

getStateVariables

UPnPManagedStateVariable[] getStateVariables()

Gets the state variables that are part of this service definition.

Returns:

The state variables that are part of this service definition. If this service defines no state variables, returns a zero-length array.

getDevice

UPnPManagedDevice getDevice()

Gets the UPnP device that this service is a part of.

Returns:

The device that this service is a part of.

setHandler

UPnPStateVariableHandler setHandler(UPnPStateVariableHandler handler)

Sets a UPnPStateVariableHandler to this UPnPManagedService. The handler provides the ability to respond dynamically to the QueryStateVariable action, and to be notified of subscription requests.

Only a single handler may be registered at any point in time. Subsequent requests to add a handler replace any existing handler.

Parameters:

handler - The handler to add. May be null, removing any previously set handler.

Returns:

The previously set UPnPStateVariableHandler, if any. Returns null if no prior handler set.

getSubscribedStatus

boolean getSubscribedStatus()

Reports the subscription status of the service.

Returns:

True if any control points are presently subscribed to this service.

getAction

UPnPAction getAction(String actionName)

Gets the named action from this service.

Specified by:

getAction in interface UPnPService

Parameters:

actionName - The name of the UPnPAction to retrieve.

Returns:

The UPnPAction object from this service with the matched name. If the service has been advertised, this method returns the same value as getAdvertisedServices()[0].getAction().

Throws:

IllegalArgumentException - if the actionName does not match an action name in this service.

getActions

UPnPAction[] getActions()

Gets the actions that can be used with this service.

Specified by:

getActions in interface UPnPService

Returns:

An array of UPnPActions. If the service has no actions, returns an zero-length array. If the service has been advertised, this method returns the same value as getAdvertisedServices()[0].getActions().

getServiceId

String getServiceId()

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

Specified by:

getServiceId in interface UPnPService

Returns:

The serviceId of this service. If the service has been advertised, this method returns the same value as getAdvertisedServices()[0].getServiceId().

getServiceType

String getServiceType()

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

Specified by:

getServiceType in interface UPnPService

Returns:

The type of this service. If the service has been advertised, this method returns the same value as getAdvertisedServices()[0].getServiceType().

getSpecVersion

String getSpecVersion()

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

Specified by:

getSpecVersion in interface UPnPService

Returns:

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