/* * $Header: /cvshome/build/org.osgi.service.upnp/src/org/osgi/service/upnp/UPnPStateVariable.java,v 1.8 2006/06/16 16:31:46 hargrave Exp $ * * Copyright (c) OSGi Alliance (2002, 2006). 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). *

* Method calls to interact with a device (e.g. UPnPAction.invoke(...);) * use this class to encapsulate meta information about the input and output * arguments. *

* 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. */ public interface UPnPStateVariable { /** * Unsigned 1 Byte int. *

* Mapped to an Integer object. */ static final String TYPE_UI1 = "ui1"; /** * Unsigned 2 Byte int. *

* Mapped to Integer object. */ static final String TYPE_UI2 = "ui2"; /** * Unsigned 4 Byte int. *

* Mapped to Long object. */ static final String TYPE_UI4 = "ui4"; /** * 1 Byte int. *

* Mapped to Integer object. */ static final String TYPE_I1 = "i1"; /** * 2 Byte int. *

* Mapped to Integer object. */ static final String TYPE_I2 = "i2"; /** * 4 Byte int. *

* Must be between -2147483648 and 2147483647 *

* Mapped to Integer object. */ static final String TYPE_I4 = "i4"; /** * Integer number. *

* Mapped to Integer object. */ static final String TYPE_INT = "int"; /** * 4 Byte float. *

* Same format as float. Must be between 3.40282347E+38 to 1.17549435E-38. *

* Mapped to Float object. */ static final String TYPE_R4 = "r4"; /** * 8 Byte float. *

* 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. *

* Mapped to Double object. */ static final String TYPE_R8 = "r8"; /** * Same as r8. *

* Mapped to 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. *

* Mapped to Double object. */ static final String TYPE_FIXED_14_4 = "fixed.14.4"; /** * Floating-point number. *

* 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.) *

* Mapped to Float object. */ static final String TYPE_FLOAT = "float"; /** * Unicode string. *

* One character long. *

* Mapped to Character object. */ static final String TYPE_CHAR = "char"; /** * Unicode string. *

* No limit on length. *

* Mapped to String object. */ static final String TYPE_STRING = "string"; /** * A calendar date. *

* Date in a subset of ISO 8601 format without time data. *

* See http://www.w3.org/TR/xmlschema-2/#date * . *

* Mapped to java.util.Date object. Always 00:00 hours. */ static final String TYPE_DATE = "date"; /** * A specific instant of time. *

* Date in ISO 8601 format with optional time but no time zone. *

* See http://www.w3.org/TR/xmlschema-2/#dateTime * . *

* Mapped to java.util.Date object using default time zone. */ static final String TYPE_DATETIME = "dateTime"; /** * A specific instant of time. *

* Date in ISO 8601 format with optional time and optional time zone. *

* See http://www.w3.org/TR/xmlschema-2/#dateTime * . *

* Mapped to 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. *

* Time in a subset of ISO 8601 format with no date and no time zone. *

* See http://www.w3.org/TR/xmlschema-2/#time * . *

* Mapped to Long. Converted to milliseconds since midnight. */ static final String TYPE_TIME = "time"; /** * An instant of time that recurs every day. *

* Time in a subset of ISO 8601 format with optional time zone but no date. *

* See http://www.w3.org/TR/xmlschema-2/#time * . *

* Mapped to 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. *

* Mapped to Boolean object. */ static final String TYPE_BOOLEAN = "boolean"; /** * MIME-style Base64 encoded binary BLOB. *

* 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. *

* Mapped to 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. *

* Treats each nibble as a hex digit and encodes as a separate Byte. (1 * octet is encoded as 2.) No limit on size. *

* Mapped to 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. *

* Mapped to String object. */ static final String TYPE_URI = "uri"; /** * Universally Unique ID. *

* Hexadecimal digits representing octets. Optional embedded hyphens are * ignored. *

* Mapped to String object. */ static final String TYPE_UUID = "uuid"; /** * Returns the variable name. * *

* * @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. *

* Mapping between the UPnP data types and Java classes is performed * according to the schema mentioned above. * * 

	 * 
	 *  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
	 *  
	 *
* * @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. * * @return The UPnP data type of this state variable, as defined in above * constants. */ String getUPnPDataType(); /** * Returns the default value, if defined. * * @return The default value or null if not defined. The type of * the returned object can be determined by getJavaDataType. */ Object getDefaultValue(); /** * Returns the allowed values, if defined. Allowed values can be defined * only for String types. * * @return The allowed values or 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. * * @return The minimum value or null if not defined. */ Number getMinimum(); /** * Returns the maximum value, if defined. Maximum values can only be defined * for numeric types. * * @return The maximum value or null if not defined. */ Number getMaximum(); /** * Returns the size of an increment operation, if defined. Step sizes can be * defined only for numeric types. * * @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. * * @return true if the StateVariable generates events, * false otherwise. */ boolean sendsEvents(); }