| /* |
| * 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; |
| |
| /** |
| * The meta-information of a UPnP state variable as declared in the device's |
| * service state table (SST). |
| * <p> |
| * Method calls to interact with a device (e.g. {@code UPnPAction.invoke(...);}) |
| * use this class to encapsulate meta information about the input and output |
| * arguments. |
| * <p> |
| * The actual values of the arguments are passed as Java objects. The mapping of |
| * types from UPnP data types to Java data types is described with the field |
| * definitions. |
| * |
| * @author $Id$ |
| */ |
| public interface UPnPStateVariable { |
| /** |
| * Unsigned 1 {@code Byte} int. |
| * <p> |
| * Mapped to an {@code Integer} object. |
| */ |
| static final String TYPE_UI1 = "ui1"; |
| /** |
| * Unsigned 2 Byte int. |
| * <p> |
| * Mapped to {@code Integer} object. |
| */ |
| static final String TYPE_UI2 = "ui2"; |
| /** |
| * Unsigned 4 Byte int. |
| * <p> |
| * Mapped to {@code Long} object. |
| */ |
| static final String TYPE_UI4 = "ui4"; |
| /** |
| * 1 Byte int. |
| * <p> |
| * Mapped to {@code Integer} object. |
| */ |
| static final String TYPE_I1 = "i1"; |
| /** |
| * 2 Byte int. |
| * <p> |
| * Mapped to {@code Integer} object. |
| */ |
| static final String TYPE_I2 = "i2"; |
| /** |
| * 4 Byte int. |
| * <p> |
| * Must be between -2147483648 and 2147483647 |
| * <p> |
| * Mapped to {@code Integer} object. |
| */ |
| static final String TYPE_I4 = "i4"; |
| /** |
| * Integer number. |
| * <p> |
| * Mapped to {@code Integer} object. |
| */ |
| static final String TYPE_INT = "int"; |
| /** |
| * 4 Byte float. |
| * <p> |
| * Same format as float. Must be between 3.40282347E+38 to 1.17549435E-38. |
| * <p> |
| * Mapped to {@code Float} object. |
| */ |
| static final String TYPE_R4 = "r4"; |
| /** |
| * 8 Byte float. |
| * <p> |
| * Same format as float. Must be between -1.79769313486232E308 and |
| * -4.94065645841247E-324 for negative values, and between |
| * 4.94065645841247E-324 and 1.79769313486232E308 for positive values, i.e., |
| * IEEE 64-bit (8-Byte) double. |
| * <p> |
| * Mapped to {@code Double} object. |
| */ |
| static final String TYPE_R8 = "r8"; |
| /** |
| * Same as r8. |
| * <p> |
| * Mapped to {@code Double} object. |
| */ |
| static final String TYPE_NUMBER = "number"; |
| /** |
| * Same as r8 but no more than 14 digits to the left of the decimal point |
| * and no more than 4 to the right. |
| * <p> |
| * Mapped to {@code Double} object. |
| */ |
| static final String TYPE_FIXED_14_4 = "fixed.14.4"; |
| /** |
| * Floating-point number. |
| * <p> |
| * Mantissa (left of the decimal) and/or exponent may have a leading sign. |
| * Mantissa and/or exponent may have leading zeros. Decimal character in |
| * mantissa is a period, i.e., whole digits in mantissa separated from |
| * fractional digits by period. Mantissa separated from exponent by E. (No |
| * currency symbol.) (No grouping of digits in the mantissa, e.g., no |
| * commas.) |
| * <p> |
| * Mapped to {@code Float} object. |
| */ |
| static final String TYPE_FLOAT = "float"; |
| /** |
| * Unicode string. |
| * <p> |
| * One character long. |
| * <p> |
| * Mapped to {@code Character} object. |
| */ |
| static final String TYPE_CHAR = "char"; |
| /** |
| * Unicode string. |
| * <p> |
| * No limit on length. |
| * <p> |
| * Mapped to {@code String} object. |
| */ |
| static final String TYPE_STRING = "string"; |
| /** |
| * A calendar date. |
| * <p> |
| * Date in a subset of ISO 8601 format without time data. |
| * <p> |
| * See <a |
| * href="http://www.w3.org/TR/xmlschema-2/#date">http://www.w3.org/TR/ |
| * xmlschema-2/#date </a>. |
| * <p> |
| * Mapped to {@code java.util.Date} object. Always 00:00 hours. |
| */ |
| static final String TYPE_DATE = "date"; |
| /** |
| * A specific instant of time. |
| * <p> |
| * Date in ISO 8601 format with optional time but no time zone. |
| * <p> |
| * See <a |
| * href="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org |
| * /TR/xmlschema-2/#dateTime </a>. |
| * <p> |
| * Mapped to {@code java.util.Date} object using default time zone. |
| */ |
| static final String TYPE_DATETIME = "dateTime"; |
| /** |
| * A specific instant of time. |
| * <p> |
| * Date in ISO 8601 format with optional time and optional time zone. |
| * <p> |
| * See <a |
| * href="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org |
| * /TR/xmlschema-2/#dateTime </a>. |
| * <p> |
| * Mapped to {@code java.util.Date} object adjusted to default time zone. |
| */ |
| static final String TYPE_DATETIME_TZ = "dateTime.tz"; |
| /** |
| * An instant of time that recurs every day. |
| * <p> |
| * Time in a subset of ISO 8601 format with no date and no time zone. |
| * <p> |
| * See <a |
| * href="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org |
| * /TR/xmlschema-2/#time </a>. |
| * <p> |
| * Mapped to {@code Long}. Converted to milliseconds since midnight. |
| */ |
| static final String TYPE_TIME = "time"; |
| /** |
| * An instant of time that recurs every day. |
| * <p> |
| * Time in a subset of ISO 8601 format with optional time zone but no date. |
| * <p> |
| * See <a |
| * href="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org |
| * /TR/xmlschema-2/#time </a>. |
| * <p> |
| * Mapped to {@code Long} object. Converted to milliseconds since midnight |
| * and adjusted to default time zone, wrapping at 0 and 24*60*60*1000. |
| */ |
| static final String TYPE_TIME_TZ = "time.tz"; |
| /** |
| * True or false. |
| * <p> |
| * Mapped to {@code Boolean} object. |
| */ |
| static final String TYPE_BOOLEAN = "boolean"; |
| /** |
| * MIME-style Base64 encoded binary BLOB. |
| * <p> |
| * Takes 3 Bytes, splits them into 4 parts, and maps each 6 bit piece to an |
| * octet. (3 octets are encoded as 4.) No limit on size. |
| * <p> |
| * Mapped to {@code byte[]} object. The Java byte array will hold the |
| * decoded content of the BLOB. |
| */ |
| static final String TYPE_BIN_BASE64 = "bin.base64"; |
| /** |
| * Hexadecimal digits representing octets. |
| * <p> |
| * Treats each nibble as a hex digit and encodes as a separate Byte. (1 |
| * octet is encoded as 2.) No limit on size. |
| * <p> |
| * Mapped to {@code byte[]} object. The Java byte array will hold the |
| * decoded content of the BLOB. |
| */ |
| static final String TYPE_BIN_HEX = "bin.hex"; |
| /** |
| * Universal Resource Identifier. |
| * <p> |
| * Mapped to {@code String} object. |
| */ |
| static final String TYPE_URI = "uri"; |
| /** |
| * Universally Unique ID. |
| * <p> |
| * Hexadecimal digits representing octets. Optional embedded hyphens are |
| * ignored. |
| * <p> |
| * Mapped to {@code String} object. |
| */ |
| static final String TYPE_UUID = "uuid"; |
| |
| /** |
| * Returns the variable name. |
| * |
| * <ul> |
| * <li>All standard variables defined by a UPnP Forum working committee must |
| * not begin with {@code X_} nor {@code A_}.</li> |
| * <li>All non-standard variables specified by a UPnP vendor and added to a |
| * standard service must begin with {@code X_}.</li> |
| * </ul> |
| * |
| * <p> |
| * This method must continue to return the state variable name after the |
| * UPnP state variable has been removed from the network. |
| * |
| * @return Name of state variable. Must not contain a hyphen character nor a |
| * hash character. Should be < 32 characters. |
| */ |
| String getName(); |
| |
| /** |
| * Returns the Java class associated with the UPnP data type of this state |
| * variable. |
| * <P> |
| * Mapping between the UPnP data types and Java classes is performed |
| * according to the schema mentioned above. |
| * |
| * <pre> |
| * |
| * Integer ui1, ui2, i1, i2, i4, int |
| * Long ui4, time, time.tz |
| * Float r4, float |
| * Double r8, number, fixed.14.4 |
| * Character char |
| * String string, uri, uuid |
| * Date date, dateTime, dateTime.tz |
| * Boolean boolean |
| * byte[] bin.base64, bin.hex |
| * |
| * </pre> |
| * |
| * <p> |
| * This method must continue to return the state variable java type after |
| * the UPnP state variable has been removed from the network. |
| * |
| * @return A class object corresponding to the Java type of this argument. |
| */ |
| Class<?> getJavaDataType(); |
| |
| /** |
| * Returns the UPnP type of this state variable. Valid types are defined as |
| * constants. |
| * |
| * <p> |
| * This method must continue to return the state variable UPnP data type |
| * after the UPnP state variable has been removed from the network. |
| * |
| * @return The UPnP data type of this state variable, as defined in above |
| * constants. |
| */ |
| String getUPnPDataType(); |
| |
| /** |
| * Returns the default value, if defined. |
| * |
| * <p> |
| * This method must continue to return the state variable default value |
| * after the UPnP state variable has been removed from the network. |
| * |
| * @return The default value or {@code null} if not defined. The type of the |
| * returned object can be determined by {@code getJavaDataType}. |
| */ |
| Object getDefaultValue(); |
| |
| /** |
| * Returns the allowed values, if defined. Allowed values can be defined |
| * only for String types. |
| * |
| * <p> |
| * This method must continue to return the state variable allowed values |
| * after the UPnP state variable has been removed from the network. |
| * |
| * @return The allowed values or {@code null} if not defined. Should be less |
| * than 32 characters. |
| */ |
| String[] getAllowedValues(); |
| |
| /** |
| * Returns the minimum value, if defined. Minimum values can only be defined |
| * for numeric types. |
| * |
| * <p> |
| * This method must continue to return the state variable minimum value |
| * after the UPnP state variable has been removed from the network. |
| * |
| * @return The minimum value or {@code null} if not defined. |
| */ |
| Number getMinimum(); |
| |
| /** |
| * Returns the maximum value, if defined. Maximum values can only be defined |
| * for numeric types. |
| * |
| * <p> |
| * This method must continue to return the state variable maximum value |
| * after the UPnP state variable has been removed from the network. |
| * |
| * @return The maximum value or {@code null} if not defined. |
| */ |
| Number getMaximum(); |
| |
| /** |
| * Returns the size of an increment operation, if defined. Step sizes can be |
| * defined only for numeric types. |
| * |
| * <p> |
| * This method must continue to return the step size after the UPnP state |
| * variable has been removed from the network. |
| * |
| * @return The increment size or null if not defined. |
| */ |
| Number getStep(); |
| |
| /** |
| * Tells if this StateVariable can be used as an event source. |
| * |
| * If the StateVariable is eventable, an event listener service can be |
| * registered to be notified when changes to the variable appear. |
| * |
| * <p> |
| * This method must continue to return the correct value after the UPnP |
| * state variable has been removed from the network. |
| * |
| * @return {@code true} if the {@code StateVariable} generates events, |
| * {@code false} otherwise. |
| */ |
| boolean sendsEvents(); |
| } |
