org.ocap.hn.upnp.client
Interface UPnPClientService

All Superinterfaces:

UPnPAdvertisedService, UPnPService

public interface UPnPClientService
extends UPnPAdvertisedService

This interface is the client representation of a UPnP service.

Method Summary

void	addStateVariableListener(UPnPStateVariableListener listener) Adds a state variable listener to this UPnPClientService.
UPnPClientDevice	getDevice() Gets the UPnP device that this service is a part of.
UPnPClientStateVariable	getStateVariable(String stateVariableName) Gets a UPnP state variable from the UPnP description of this service.
UPnPClientStateVariable[]	getStateVariables() Gets all of the UPnP state variables supported by this service.
boolean	getSubscribedStatus() Gets the subscription status of the service.
void	postActionInvocation(UPnPActionInvocation actionInvocation, UPnPActionResponseHandler handler) Posts an action to the network.
void	removeStateVariableListener(UPnPStateVariableListener listener) Removes a change listener.
void	setSubscribedStatus(boolean subscribed) Attempts to subscribe or unsubscribe the control point to/from this service.

Methods inherited from interface org.ocap.hn.upnp.common.UPnPAdvertisedService

getAdvertisedStateVariable, getAdvertisedStateVariables, getControlURL, getEventSubURL, getSCPDURL, getXML

Methods inherited from interface org.ocap.hn.upnp.common.UPnPService

getAction, getActions, getServiceId, getServiceType, getSpecVersion

Method Detail

getDevice

UPnPClientDevice getDevice()

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

Returns:

The device that this service is a part of.

postActionInvocation

void postActionInvocation(UPnPActionInvocation actionInvocation,
                          UPnPActionResponseHandler handler)

Posts an action to the network. Sends the action from the control point to the device the service is in. The device MAY be on the local host. If no handler is set when this method is called, the response is consumed by the implementation in an implementation-specific fashion.

Parameters:

actionInvocation - The action invocation to post.

handler - The handler that will be notified when the action response is received. May be null, in which case the action response will be discarded.

Throws:

NullPointerException - if action is null.

See Also:

UPnPActionInvocation

addStateVariableListener

void addStateVariableListener(UPnPStateVariableListener listener)

Adds a state variable listener to this UPnPClientService. If this service has evented state variables, this method will cause the control point to attempt to subscribe to the service if it is not already subscribed. See UPnP Device Architecture specification for UPnP service and state variable subscription.

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.

See Also:

setSubscribedStatus(boolean)

removeStateVariableListener

void removeStateVariableListener(UPnPStateVariableListener listener)

Removes a change listener.

Parameters:

listener - The listener to remove.

setSubscribedStatus

void setSubscribedStatus(boolean subscribed)

Attempts to subscribe or unsubscribe the control point to/from this service. Changes to subscription status are signaled asynchronously via the UPnPStateVariableListener interface.

Parameters:

subscribed - True to subscribe to evented state variable updates, false to unsubscribe.

Throws:

UnsupportedOperationException - if subscribed is true but the service has no evented state variables.

getSubscribedStatus

boolean getSubscribedStatus()

Gets the subscription status of the service. Defaults to subscribed if the service has evented state variables; false otherwise.

Returns:

True if the control point is presently registered to receive UPnP events from the service, false if not.

getStateVariable

UPnPClientStateVariable getStateVariable(String stateVariableName)

Gets a UPnP state variable from the UPnP description of this service. Supported state variable names are provided by a UPnP device in the name element of each stateVariable element in a device service description.

Parameters:

stateVariableName - The name of the state variable to get.

Returns:

The state variable corresponding to the stateVariableName parameter.

Throws:

IllegalArgumentException - if the stateVariableName does not match a state variable name in this service.

getStateVariables

UPnPClientStateVariable[] getStateVariables()

Gets all of the UPnP state variables supported by this service. UPnP state variable information is taken from the stateVariable elements in the UPnP service description.

Returns:

The UPnP state variables supported by this service. If the service has no state variables, returns a zero-length array.