UPnPAction
Date: 2016-06-25

org.osgi.service.upnp

## Interface UPnPAction

-     public interface UPnPAction

  A UPnP action. Each UPnP service contains zero or more actions. Each action may have zero or more UPnP state variables as arguments.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.String[]` | `getInputArgumentNames()` Lists all input arguments for this action.
    `java.lang.String` | `getName()` Returns the action name.
    `java.lang.String[]` | `getOutputArgumentNames()` List all output arguments for this action.
    `java.lang.String` | `getReturnArgumentName()` Returns the name of the designated return argument.
    `UPnPStateVariable` | `getStateVariable(java.lang.String argumentName)` Finds the state variable associated with an argument name.
    `java.util.Dictionary` | `invoke(java.util.Dictionary args)` Invokes the action.

- - ### Method Detail

    - #### getName

          java.lang.String getName()

      Returns the action name. The action name corresponds to the `name` field in the `actionList` of the service description.
      - For standard actions defined by a UPnP Forum working committee, action names must not begin with `X_` nor `A_`.
      - For non-standard actions specified by a UPnP vendor and added to a standard service, action names must begin with `X_`.

      This method must continue to return the action name after the UPnP action has been removed from the network.

      Returns:
        Name of action, must not contain a hyphen character or a hash character

    - #### getReturnArgumentName

          java.lang.String getReturnArgumentName()

      Returns the name of the designated return argument.

      One of the output arguments can be flagged as a designated return argument.

      This method must continue to return the action return argument name after the UPnP action has been removed from the network.

      Returns:
        The name of the designated return argument or `null` if none is marked.

    - #### getInputArgumentNames

          java.lang.String[] getInputArgumentNames()

      Lists all input arguments for this action.

      Each action may have zero or more input arguments.

      This method must continue to return the action input argument names after the UPnP action has been removed from the network.

      Returns:
        Array of input argument names or `null` if no input arguments.
      See Also:
        `UPnPStateVariable`

    - #### getOutputArgumentNames

          java.lang.String[] getOutputArgumentNames()

      List all output arguments for this action.

      This method must continue to return the action output argument names after the UPnP action has been removed from the network.

      Returns:
        Array of output argument names or `null` if there are no output arguments.
      See Also:
        `UPnPStateVariable`

    - #### getStateVariable

          UPnPStateVariable getStateVariable(java.lang.String argumentName)

      Finds the state variable associated with an argument name. Helps to resolve the association of state variables with argument names in UPnP actions.
      Parameters:
        `argumentName` - The name of the UPnP action argument.
      Returns:
        State variable associated with the named argument or `null` if there is no such argument.
      Throws:
        `java.lang.IllegalStateException` - if the UPnP action has been removed from the network.
      See Also:
        `UPnPStateVariable`

    - #### invoke

          java.util.Dictionary invoke(java.util.Dictionary args)
                                      throws java.lang.Exception

      Invokes the action. The input and output arguments are both passed as `Dictionary` objects. Each entry in the `Dictionary` object has a `String` object as key representing the argument name and the value is the argument itself. The class of an argument value must be assignable from the class of the associated UPnP state variable. The input argument `Dictionary` object must contain exactly those arguments listed by `getInputArguments` method. The output argument `Dictionary` object will contain exactly those arguments listed by `getOutputArguments` method.
      Parameters:
        `args` - A `Dictionary` of arguments. Must contain the correct set and type of arguments for this action. May be `null` if no input arguments exist.
      Returns:
        A `Dictionary` with the output arguments. `null` if the action has no output arguments.
      Throws:
        `UPnPException` - A UPnP error has occurred.
        `java.lang.IllegalStateException` - if the UPnP action has been removed from the network.
        `java.lang.Exception` - The execution fails for some reason.
      See Also:
        `UPnPStateVariable`