Inheritance diagram for org.cybergarage.upnp.Action:

Public Member Functions
Service	getService ()

Node	getActionNode ()

	Action (Node serviceNode)

	Action (Node serviceNode, Node actionNode)

	Action (Action action)

void	lock ()

void	unlock ()

void	setName (String value)

String	getName ()

ArgumentList	getArgumentList ()

void	setArgumentList (ArgumentList al)

ArgumentList	getInputArgumentList ()

ArgumentList	getOutputArgumentList ()

Argument	getArgument (String name)

void	setArgumentValues (ArgumentList argList)

void	setInArgumentValues (ArgumentList argList)

void	setOutArgumentValues (ArgumentList argList)

void	setArgumentValue (String name, String value)

void	setArgumentValue (String name, int value)

String	getArgumentValue (String name)

int	getArgumentIntegerValue (String name)

ActionListener	getActionListener ()

void	setActionListener (ActionListener listener)

boolean	performActionListener (ActionRequest actionReq)

UPnPStatus	getControlStatus ()

boolean	postControlAction ()

void	print ()

void	setStatus (int code, String descr)

void	setStatus (int code)

UPnPStatus	getStatus ()

void	setUserData (Object data)

Object	getUserData ()

Static Public Member Functions
static boolean	isActionNode (Node node)

Static Public Attributes
static final String	ELEM_NAME = "action"

Private Member Functions
Node	getServiceNode ()

void	clearOutputAgumentValues ()

ActionData	getActionData ()

ControlResponse	getControlResponse ()

void	setControlResponse (ControlResponse res)

Private Attributes
Node	serviceNode

Node	actionNode

Mutex	mutex = new Mutex()

UPnPStatus	upnpStatus = new UPnPStatus()

Object	userData = null

Static Private Attributes
static final String	NAME = "name"

Detailed Description

Represents a UPnP action that can be invoked on a service.

Actions are methods exposed by UPnP services that can be called remotely by control points. Each action has a name, a list of input arguments, and a list of output arguments. Actions are defined in the service's SCPD (Service Control Protocol Definition) document.

This class provides methods to:

Set and retrieve action arguments
Invoke the action on a remote device via postControlAction()
Handle incoming action requests from control points via ActionListener
Access action execution status and response data

Thread-safety: This class uses internal synchronization via lock() and unlock() methods. Multiple threads can safely interact with the same action instance when using these synchronization methods.

Example usage for invoking an action on a device:



Service service = device.getService("urn:schemas-upnp-org:service:AVTransport:1");

Action playAction = service.getAction("Play");

playAction.setArgumentValue("InstanceID", "0");

playAction.setArgumentValue("Speed", "1");

boolean success = playAction.postControlAction();

if (success) {

    System.out.println("Play action executed successfully");

}

See also: Service; Argument; ActionListener

Constructor & Destructor Documentation

◆ Action() [1/3]

org.cybergarage.upnp.Action.Action ( Node serviceNode )

inline

Constructs a new action with the specified service node.

Creates an empty action node that can be populated with action details.

Parameters

serviceNode the XML node representing the service that contains this action

◆ Action() [2/3]

org.cybergarage.upnp.Action.Action	(	Node	serviceNode,
		Node	actionNode )

inline

Constructs an action from existing service and action XML nodes.

This constructor is typically used when parsing service descriptions to create action objects from the SCPD document.

Parameters

serviceNode	the XML node representing the parent service
actionNode	the XML node containing action definition and arguments

◆ Action() [3/3]

org.cybergarage.upnp.Action.Action ( Action action )

inline

Creates a copy of an existing action.

Note: This creates a shallow copy that references the same underlying XML nodes as the original action.

Parameters

action the action to copy

Member Function Documentation

◆ clearOutputAgumentValues()

void org.cybergarage.upnp.Action.clearOutputAgumentValues ( )

inlineprivate

◆ getActionData()

ActionData org.cybergarage.upnp.Action.getActionData ( )

inlineprivate

◆ getActionListener()

ActionListener org.cybergarage.upnp.Action.getActionListener ( )

inline

Returns the action listener registered for this action.

Returns: the action listener, or null if none is registered

◆ getActionNode()

Node org.cybergarage.upnp.Action.getActionNode ( )

inline

Returns the underlying XML node representing this action.

Returns: the action XML node

◆ getArgument()

Argument org.cybergarage.upnp.Action.getArgument ( String name )

inline

Returns the argument with the specified name.

Parameters

name	the name of the argument to retrieve

Returns: the argument with the specified name, or null if not found

◆ getArgumentIntegerValue()

int org.cybergarage.upnp.Action.getArgumentIntegerValue ( String name )

inline

Returns the integer value of the specified argument.

Parameters

name	the name of the argument

Returns: the argument value as an integer, or 0 if the argument is not found

◆ getArgumentList()

ArgumentList org.cybergarage.upnp.Action.getArgumentList ( )

inline

Returns the complete list of arguments for this action.

This includes both input and output arguments as defined in the service's SCPD document.

Returns: the list of all arguments for this action

See also: getInputArgumentList(); getOutputArgumentList()

◆ getArgumentValue()

String org.cybergarage.upnp.Action.getArgumentValue ( String name )

inline

Returns the string value of the specified argument.

Parameters

name	the name of the argument

Returns: the argument value as a string, or an empty string if the argument is not found

◆ getControlResponse()

ControlResponse org.cybergarage.upnp.Action.getControlResponse ( )

inlineprivate

◆ getControlStatus()

UPnPStatus org.cybergarage.upnp.Action.getControlStatus ( )

inline

Returns the UPnP error status from the most recent control response.

Returns: the UPnP status from the control response

◆ getInputArgumentList()

ArgumentList org.cybergarage.upnp.Action.getInputArgumentList ( )

inline

Returns only the input arguments for this action.

Input arguments are those with direction "in" and must be provided when invoking the action on a device.

Returns: the list of input arguments

See also: getOutputArgumentList()

◆ getName()

String org.cybergarage.upnp.Action.getName ( )

inline

Returns the name of this action.

Returns: the action name as defined in the SCPD document

◆ getOutputArgumentList()

ArgumentList org.cybergarage.upnp.Action.getOutputArgumentList ( )

inline

Returns only the output arguments for this action.

Output arguments are those with direction "out" and are populated with values returned by the device after action execution.

Returns: the list of output arguments

See also: getInputArgumentList()

◆ getService()

Service org.cybergarage.upnp.Action.getService ( )

inline

Returns the service that contains this action.

Returns: the parent service of this action

◆ getServiceNode()

Node org.cybergarage.upnp.Action.getServiceNode ( )

inlineprivate

◆ getStatus()

UPnPStatus org.cybergarage.upnp.Action.getStatus ( )

inline

Returns the current execution status of this action.

The status includes error codes and descriptions from the most recent action execution.

Returns: the UPnP status object containing execution results

See also: UPnPStatus

◆ getUserData()

Object org.cybergarage.upnp.Action.getUserData ( )

inline

Returns the custom user data associated with this action.

Returns: the user data object, or null if none has been set

◆ isActionNode()

static boolean org.cybergarage.upnp.Action.isActionNode ( Node node )

inlinestatic

Checks if the given XML node represents an action element.

Parameters

node	the XML node to check

Returns: true if the node's name matches the action element name, false otherwise

◆ lock()

void org.cybergarage.upnp.Action.lock ( )

inline

Acquires the lock for this action.

Use this method to synchronize access to the action from multiple threads. Always pair with unlock() to release the lock, preferably in a try-finally block.

See also: unlock()

◆ performActionListener()

boolean org.cybergarage.upnp.Action.performActionListener ( ActionRequest actionReq )

inline

Executes the action listener for an incoming action request.

This method is called by the UPnP device when a control point invokes this action. It calls the registered ActionListener, collects the response, and posts it back to the control point.

Parameters

actionReq the incoming action request from the control point

Returns: true if a listener was registered and executed, false if no listener is available

◆ postControlAction()

boolean org.cybergarage.upnp.Action.postControlAction ( )

inline

Posts this action to the device and waits for the response.

This method sends a SOAP action request to the device's control URL with the currently set input argument values. It blocks until a response is received or a timeout occurs. Upon successful execution, the output argument values are updated with the response data.

The execution status can be retrieved via getStatus() after this method returns.

Returns: true if the action was executed successfully and the response was valid, false if an error occurred

See also: setArgumentValue(String, String); getArgumentValue(String); getStatus()

◆ print()

void org.cybergarage.upnp.Action.print ( )

inline

Prints action information to standard output for debugging.

Outputs the action name and all argument details including direction, name, and current value.

◆ setActionListener()

void org.cybergarage.upnp.Action.setActionListener ( ActionListener listener )

inline

Sets the listener that will be notified when this action is invoked.

The listener's ActionListener#actionControlReceived(Action) method will be called when a control point invokes this action.

Parameters

listener the action listener to set, or null to remove the listener

See also: ActionListener

◆ setArgumentList()

void org.cybergarage.upnp.Action.setArgumentList ( ArgumentList al )

inline

Sets the argument list for this action.

Replaces the existing argument list with the provided list. This method ensures that all arguments are properly associated with the action's service.

Parameters

al	the argument list to set

◆ setArgumentValue() [1/2]

void org.cybergarage.upnp.Action.setArgumentValue	(	String	name,
		int	value )

inline

Sets the value of a named argument from an integer.

The integer value is converted to a string before being assigned. If the argument with the specified name does not exist, this method does nothing.

Parameters

name	the name of the argument to set
value	the integer value to assign to the argument

◆ setArgumentValue() [2/2]

void org.cybergarage.upnp.Action.setArgumentValue	(	String	name,
		String	value )

inline

Sets the value of a named argument.

If the argument with the specified name does not exist, this method does nothing.

Parameters

name	the name of the argument to set
value	the string value to assign to the argument

◆ setArgumentValues()

void org.cybergarage.upnp.Action.setArgumentValues ( ArgumentList argList )

inline

Sets argument values from the provided list.

Parameters

argList the argument list containing values to set

Deprecated

You should use one of the following methods instead:

setInArgumentValues(ArgumentList)
setOutArgumentValues(ArgumentList)

◆ setControlResponse()

void org.cybergarage.upnp.Action.setControlResponse ( ControlResponse res )

inlineprivate

◆ setInArgumentValues()

void org.cybergarage.upnp.Action.setInArgumentValues ( ArgumentList argList )

inline

Sets the values of input arguments from the provided argument list.

Only the values of arguments with direction "in" are updated.

Parameters

argList the argument list containing values to set

Since: 1.8.0

◆ setName()

void org.cybergarage.upnp.Action.setName ( String value )

inline

Sets the name of this action.

Parameters

value the action name (e.g., "Play", "SetVolume")

◆ setOutArgumentValues()

void org.cybergarage.upnp.Action.setOutArgumentValues ( ArgumentList argList )

inline

Sets the values of output arguments from the provided argument list.

Only the values of arguments with direction "out" are updated.

Parameters

argList the argument list containing values to set

Since: 1.8.0

◆ setStatus() [1/2]

void org.cybergarage.upnp.Action.setStatus ( int code )

inline

Sets the execution status of this action with a specific error code.

The description is automatically derived from the error code.

Parameters

code	the UPnP error code

See also: UPnPStatus

◆ setStatus() [2/2]

void org.cybergarage.upnp.Action.setStatus	(	int	code,
		String	descr )

inline

Sets the execution status of this action with a specific error code and description.

Parameters

code	the UPnP error code
descr	the human-readable description of the error

See also: UPnPStatus

◆ setUserData()

void org.cybergarage.upnp.Action.setUserData ( Object data )

inline

Sets custom user data associated with this action.

This allows applications to attach arbitrary data to an action instance for application-specific purposes.

Parameters

data	the user data object to associate with this action

◆ unlock()

void org.cybergarage.upnp.Action.unlock ( )

inline

Releases the lock for this action.

Should be called after lock() once the synchronized operation is complete.

See also: lock()

Field Documentation

◆ actionNode

Node org.cybergarage.upnp.Action.actionNode

private

◆ ELEM_NAME

final String org.cybergarage.upnp.Action.ELEM_NAME = "action"

static

The XML element name for action nodes in SCPD documents.

◆ mutex

Mutex org.cybergarage.upnp.Action.mutex = new Mutex()

private

◆ NAME

final String org.cybergarage.upnp.Action.NAME = "name"

staticprivate

◆ serviceNode

Node org.cybergarage.upnp.Action.serviceNode

private

◆ upnpStatus

UPnPStatus org.cybergarage.upnp.Action.upnpStatus = new UPnPStatus()

private

◆ userData

Object org.cybergarage.upnp.Action.userData = null

private

The documentation for this class was generated from the following file:

core/src/main/java/org/cybergarage/upnp/Action.java

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Action() [1/3]

◆ Action() [2/3]

◆ Action() [3/3]

Member Function Documentation

◆ clearOutputAgumentValues()

◆ getActionData()

◆ getActionListener()

◆ getActionNode()

◆ getArgument()

◆ getArgumentIntegerValue()

◆ getArgumentList()

◆ getArgumentValue()

◆ getControlResponse()

◆ getControlStatus()

◆ getInputArgumentList()

◆ getName()

◆ getOutputArgumentList()

◆ getService()

◆ getServiceNode()

◆ getStatus()

◆ getUserData()

◆ isActionNode()

◆ lock()

◆ performActionListener()

◆ postControlAction()

◆ print()

◆ setActionListener()

◆ setArgumentList()

◆ setArgumentValue() [1/2]

◆ setArgumentValue() [2/2]

◆ setArgumentValues()

◆ setControlResponse()

◆ setInArgumentValues()

◆ setName()

◆ setOutArgumentValues()

◆ setStatus() [1/2]

◆ setStatus() [2/2]

◆ setUserData()

◆ unlock()

Field Documentation

◆ actionNode

◆ ELEM_NAME

◆ mutex

◆ NAME

◆ serviceNode

◆ upnpStatus

◆ userData