| /* |
| * Copyright (c) OSGi Alliance (2002, 2015). All Rights Reserved. |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package org.osgi.service.upnp; |
| |
| import java.util.Dictionary; |
| |
| /** |
| * A UPnP action. |
| * |
| * Each UPnP service contains zero or more actions. Each action may have zero or |
| * more UPnP state variables as arguments. |
| * |
| * @author $Id$ |
| */ |
| public interface UPnPAction { |
| /** |
| * Returns the action name. |
| * |
| * The action name corresponds to the {@code name} field in the |
| * {@code actionList} of the service description. |
| * <ul> |
| * <li>For standard actions defined by a UPnP Forum working committee, |
| * action names must not begin with {@code X_ } nor {@code A_}.</li> |
| * <li>For non-standard actions specified by a UPnP vendor and added to a |
| * standard service, action names must begin with {@code X_}.</li> |
| * </ul> |
| * |
| * <p> |
| * This method must continue to return the action name after the UPnP action |
| * has been removed from the network. |
| * |
| * @return Name of action, must not contain a hyphen character or a hash |
| * character |
| */ |
| String getName(); |
| |
| /** |
| * Returns the name of the designated return argument. |
| * <p> |
| * One of the output arguments can be flagged as a designated return |
| * argument. |
| * |
| * <p> |
| * This method must continue to return the action return argument name after |
| * the UPnP action has been removed from the network. |
| * |
| * @return The name of the designated return argument or {@code null} if |
| * none is marked. |
| */ |
| String getReturnArgumentName(); |
| |
| /** |
| * Lists all input arguments for this action. |
| * <p> |
| * Each action may have zero or more input arguments. |
| * |
| * <p> |
| * This method must continue to return the action input argument names after |
| * the UPnP action has been removed from the network. |
| * |
| * @return Array of input argument names or {@code null} if no input |
| * arguments. |
| * |
| * @see UPnPStateVariable |
| */ |
| String[] getInputArgumentNames(); |
| |
| /** |
| * List all output arguments for this action. |
| * |
| * <p> |
| * This method must continue to return the action output argument names |
| * after the UPnP action has been removed from the network. |
| * |
| * @return Array of output argument names or {@code null} if there are no |
| * output arguments. |
| * |
| * @see UPnPStateVariable |
| */ |
| String[] getOutputArgumentNames(); |
| |
| /** |
| * Finds the state variable associated with an argument name. |
| * |
| * Helps to resolve the association of state variables with argument names |
| * in UPnP actions. |
| * |
| * @param argumentName The name of the UPnP action argument. |
| * @return State variable associated with the named argument or {@code null} |
| * if there is no such argument. |
| * |
| * @throws IllegalStateException if the UPnP action has been removed from |
| * the network. |
| * |
| * @see UPnPStateVariable |
| */ |
| UPnPStateVariable getStateVariable(String argumentName); |
| |
| /** |
| * Invokes the action. |
| * |
| * The input and output arguments are both passed as {@code Dictionary} |
| * objects. Each entry in the {@code Dictionary} object has a {@code 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 {@code Dictionary} object must contain exactly those |
| * arguments listed by {@code getInputArguments} method. The output argument |
| * {@code Dictionary} object will contain exactly those arguments listed by |
| * {@code getOutputArguments} method. |
| * |
| * @param args A {@code Dictionary} of arguments. Must contain the correct |
| * set and type of arguments for this action. May be {@code null} if |
| * no input arguments exist. |
| * |
| * @return A {@code Dictionary} with the output arguments. {@code null} if |
| * the action has no output arguments. |
| * |
| * @throws UPnPException A UPnP error has occurred. |
| * @throws IllegalStateException if the UPnP action has been removed from |
| * the network. |
| * @throws Exception The execution fails for some reason. |
| * |
| * @see UPnPStateVariable |
| */ |
| Dictionary<String, Object> invoke(Dictionary<String, ?> args) throws Exception; |
| } |