001 /*
002 * Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.osgi.service.upnp;
017
018 /**
019 * The meta-information of a UPnP state variable as declared in the device's
020 * service state table (SST).
021 * <p>
022 * Method calls to interact with a device (e.g.
023 * <code>UPnPAction.invoke(...);</code>) use this class to encapsulate meta
024 * information about the input and output arguments.
025 * <p>
026 * The actual values of the arguments are passed as Java objects. The mapping of
027 * types from UPnP data types to Java data types is described with the field
028 * definitions.
029 *
030 * @version $Revision: 5673 $
031 */
032 public interface UPnPStateVariable {
033 /**
034 * Unsigned 1 <code>Byte</code> int.
035 * <p>
036 * Mapped to an <code>Integer</code> object.
037 */
038 static final String TYPE_UI1 = "ui1";
039 /**
040 * Unsigned 2 Byte int.
041 * <p>
042 * Mapped to <code>Integer</code> object.
043 */
044 static final String TYPE_UI2 = "ui2";
045 /**
046 * Unsigned 4 Byte int.
047 * <p>
048 * Mapped to <code>Long</code> object.
049 */
050 static final String TYPE_UI4 = "ui4";
051 /**
052 * 1 Byte int.
053 * <p>
054 * Mapped to <code>Integer</code> object.
055 */
056 static final String TYPE_I1 = "i1";
057 /**
058 * 2 Byte int.
059 * <p>
060 * Mapped to <code>Integer</code> object.
061 */
062 static final String TYPE_I2 = "i2";
063 /**
064 * 4 Byte int.
065 * <p>
066 * Must be between -2147483648 and 2147483647
067 * <p>
068 * Mapped to <code>Integer</code> object.
069 */
070 static final String TYPE_I4 = "i4";
071 /**
072 * Integer number.
073 * <p>
074 * Mapped to <code>Integer</code> object.
075 */
076 static final String TYPE_INT = "int";
077 /**
078 * 4 Byte float.
079 * <p>
080 * Same format as float. Must be between 3.40282347E+38 to 1.17549435E-38.
081 * <p>
082 * Mapped to <code>Float</code> object.
083 */
084 static final String TYPE_R4 = "r4";
085 /**
086 * 8 Byte float.
087 * <p>
088 * Same format as float. Must be between -1.79769313486232E308 and
089 * -4.94065645841247E-324 for negative values, and between
090 * 4.94065645841247E-324 and 1.79769313486232E308 for positive values, i.e.,
091 * IEEE 64-bit (8-Byte) double.
092 * <p>
093 * Mapped to <code>Double</code> object.
094 */
095 static final String TYPE_R8 = "r8";
096 /**
097 * Same as r8.
098 * <p>
099 * Mapped to <code>Double</code> object.
100 */
101 static final String TYPE_NUMBER = "number";
102 /**
103 * Same as r8 but no more than 14 digits to the left of the decimal point
104 * and no more than 4 to the right.
105 * <p>
106 * Mapped to <code>Double</code> object.
107 */
108 static final String TYPE_FIXED_14_4 = "fixed.14.4";
109 /**
110 * Floating-point number.
111 * <p>
112 * Mantissa (left of the decimal) and/or exponent may have a leading sign.
113 * Mantissa and/or exponent may have leading zeros. Decimal character in
114 * mantissa is a period, i.e., whole digits in mantissa separated from
115 * fractional digits by period. Mantissa separated from exponent by E. (No
116 * currency symbol.) (No grouping of digits in the mantissa, e.g., no
117 * commas.)
118 * <p>
119 * Mapped to <code>Float</code> object.
120 */
121 static final String TYPE_FLOAT = "float";
122 /**
123 * Unicode string.
124 * <p>
125 * One character long.
126 * <p>
127 * Mapped to <code>Character</code> object.
128 */
129 static final String TYPE_CHAR = "char";
130 /**
131 * Unicode string.
132 * <p>
133 * No limit on length.
134 * <p>
135 * Mapped to <code>String</code> object.
136 */
137 static final String TYPE_STRING = "string";
138 /**
139 * A calendar date.
140 * <p>
141 * Date in a subset of ISO 8601 format without time data.
142 * <p>
143 * See <a
144 * href="http://www.w3.org/TR/xmlschema-2/#date">http://www.w3.org/TR/xmlschema-2/#date
145 * </a>.
146 * <p>
147 * Mapped to <code>java.util.Date</code> object. Always 00:00 hours.
148 */
149 static final String TYPE_DATE = "date";
150 /**
151 * A specific instant of time.
152 * <p>
153 * Date in ISO 8601 format with optional time but no time zone.
154 * <p>
155 * See <a
156 * href="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org/TR/xmlschema-2/#dateTime
157 * </a>.
158 * <p>
159 * Mapped to <code>java.util.Date</code> object using default time zone.
160 */
161 static final String TYPE_DATETIME = "dateTime";
162 /**
163 * A specific instant of time.
164 * <p>
165 * Date in ISO 8601 format with optional time and optional time zone.
166 * <p>
167 * See <a
168 * href="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org/TR/xmlschema-2/#dateTime
169 * </a>.
170 * <p>
171 * Mapped to <code>java.util.Date</code> object adjusted to default time zone.
172 */
173 static final String TYPE_DATETIME_TZ = "dateTime.tz";
174 /**
175 * An instant of time that recurs every day.
176 * <p>
177 * Time in a subset of ISO 8601 format with no date and no time zone.
178 * <p>
179 * See <a
180 * href="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org/TR/xmlschema-2/#time
181 * </a>.
182 * <p>
183 * Mapped to <code>Long</code>. Converted to milliseconds since midnight.
184 */
185 static final String TYPE_TIME = "time";
186 /**
187 * An instant of time that recurs every day.
188 * <p>
189 * Time in a subset of ISO 8601 format with optional time zone but no date.
190 * <p>
191 * See <a
192 * href="http://www.w3.org/TR/xmlschema-2/#dateTime">http://www.w3.org/TR/xmlschema-2/#time
193 * </a>.
194 * <p>
195 * Mapped to <code>Long</code> object. Converted to milliseconds since
196 * midnight and adjusted to default time zone, wrapping at 0 and
197 * 24*60*60*1000.
198 */
199 static final String TYPE_TIME_TZ = "time.tz";
200 /**
201 * True or false.
202 * <p>
203 * Mapped to <code>Boolean</code> object.
204 */
205 static final String TYPE_BOOLEAN = "boolean";
206 /**
207 * MIME-style Base64 encoded binary BLOB.
208 * <p>
209 * Takes 3 Bytes, splits them into 4 parts, and maps each 6 bit piece to an
210 * octet. (3 octets are encoded as 4.) No limit on size.
211 * <p>
212 * Mapped to <code>byte[]</code> object. The Java byte array will hold the
213 * decoded content of the BLOB.
214 */
215 static final String TYPE_BIN_BASE64 = "bin.base64";
216 /**
217 * Hexadecimal digits representing octets.
218 * <p>
219 * Treats each nibble as a hex digit and encodes as a separate Byte. (1
220 * octet is encoded as 2.) No limit on size.
221 * <p>
222 * Mapped to <code>byte[]</code> object. The Java byte array will hold the
223 * decoded content of the BLOB.
224 */
225 static final String TYPE_BIN_HEX = "bin.hex";
226 /**
227 * Universal Resource Identifier.
228 * <p>
229 * Mapped to <code>String</code> object.
230 */
231 static final String TYPE_URI = "uri";
232 /**
233 * Universally Unique ID.
234 * <p>
235 * Hexadecimal digits representing octets. Optional embedded hyphens are
236 * ignored.
237 * <p>
238 * Mapped to <code>String</code> object.
239 */
240 static final String TYPE_UUID = "uuid";
241
242 /**
243 * Returns the variable name.
244 *
245 * <ul>
246 * <li>All standard variables defined by a UPnP Forum working committee
247 * must not begin with <code>X_</code> nor <code>A_</code>.</li>
248 * <li>All non-standard variables specified by a UPnP vendor and added to a
249 * standard service must begin with <code>X_</code>.</li>
250 * </ul>
251 *
252 * @return Name of state variable. Must not contain a hyphen character nor a
253 * hash character. Should be < 32 characters.
254 */
255 String getName();
256
257 /**
258 * Returns the Java class associated with the UPnP data type of this state
259 * variable.
260 * <P>
261 * Mapping between the UPnP data types and Java classes is performed
262 * according to the schema mentioned above.
263 *
264 * <pre>
265 *
266 * Integer ui1, ui2, i1, i2, i4, int
267 * Long ui4, time, time.tz
268 * Float r4, float
269 * Double r8, number, fixed.14.4
270 * Character char
271 * String string, uri, uuid
272 * Date date, dateTime, dateTime.tz
273 * Boolean boolean
274 * byte[] bin.base64, bin.hex
275 *
276 * </pre>
277 *
278 * @return A class object corresponding to the Java type of this argument.
279 */
280 Class getJavaDataType();
281
282 /**
283 * Returns the UPnP type of this state variable. Valid types are defined as
284 * constants.
285 *
286 * @return The UPnP data type of this state variable, as defined in above
287 * constants.
288 */
289 String getUPnPDataType();
290
291 /**
292 * Returns the default value, if defined.
293 *
294 * @return The default value or <code>null</code> if not defined. The type of
295 * the returned object can be determined by <code>getJavaDataType</code>.
296 */
297 Object getDefaultValue();
298
299 /**
300 * Returns the allowed values, if defined. Allowed values can be defined
301 * only for String types.
302 *
303 * @return The allowed values or <code>null</code> if not defined. Should be
304 * less than 32 characters.
305 */
306 String[] getAllowedValues();
307
308 /**
309 * Returns the minimum value, if defined. Minimum values can only be defined
310 * for numeric types.
311 *
312 * @return The minimum value or <code>null</code> if not defined.
313 */
314 Number getMinimum();
315
316 /**
317 * Returns the maximum value, if defined. Maximum values can only be defined
318 * for numeric types.
319 *
320 * @return The maximum value or <code>null</code> if not defined.
321 */
322 Number getMaximum();
323
324 /**
325 * Returns the size of an increment operation, if defined. Step sizes can be
326 * defined only for numeric types.
327 *
328 * @return The increment size or null if not defined.
329 */
330 Number getStep();
331
332 /**
333 * Tells if this StateVariable can be used as an event source.
334 *
335 * If the StateVariable is eventable, an event listener service can be
336 * registered to be notified when changes to the variable appear.
337 *
338 * @return <code>true</code> if the <code>StateVariable</code> generates events,
339 * <code>false</code> otherwise.
340 */
341 boolean sendsEvents();
342 }