1 /**
2 * Java docs licensed under the Apache License, Version 2.0
3 * http://www.apache.org/licenses/LICENSE-2.0
4 * (c) Copyright 2001, 2002 Motorola, Inc. ALL RIGHTS RESERVED.
5 *
6 *
7 * @version $Id: HeaderSet.java 1379 2007-10-13 02:00:43Z vlads $
8 */
9 package javax.obex;
10
11 import java.io.IOException;
12
13 /**
14 * The <code>HeaderSet</code> interface defines the methods that set and get
15 * the values of OBEX headers.
16 * <P>
17 * The following table describes how the headers specified in this interface are
18 * represented in OBEX and in Java. The Java types are used with the
19 * <code>setHeader()</code> and <code>getHeader()</code> methods and specify
20 * the type of object that must be provided and will be returned from these
21 * methods, respectively. <TABLE BORDER>
22 * <TR>
23 * <TH>Header Values</TH>
24 * <TH>OBEX Representation</TH>
25 * <TH>Java Type</TH>
26 * </TR>
27 * <TR>
28 * <TD>COUNT</TD>
29 * <TD>4 byte unsigned integer</TD>
30 * <TD><code>java.lang.Long</code> in the range 0 to 2<sup>32</sup>-1</TD>
31 * </TR>
32 * <TR>
33 * <TD>NAME</TD>
34 * <TD>Unicode string</TD>
35 * <TD><code>java.lang.String</code></TD>
36 * </TR>
37 * <TR>
38 * <TD>TYPE</TD>
39 * <TD>ASCII string</TD>
40 * <TD><code>java.lang.String</code></TD>
41 * </TR>
42 * <TR>
43 * <TD>LENGTH</TD>
44 * <TD>4 byte unsigned integer</TD>
45 * <TD><code>java.lang.Long</code> in the range 0 to 2<sup>32</sup>-1</TD>
46 * </TR>
47 * <TR>
48 * <TD>TIME_ISO_8601</TD>
49 * <TD>ASCII string of the form YYYYMMDDTHHMMSS[Z] where [Z] specifies Zulu
50 * time</TD>
51 * <TD><code>java.util.Calendar</code></TD>
52 * </TR>
53 * <TR>
54 * <TD>TIME_4_BYTE</TD>
55 * <TD>4 byte unsigned integer</TD>
56 * <TD><code>java.util.Calendar</code></TD>
57 * </TR>
58 * <TR>
59 * <TD>DESCRIPTION</TD>
60 * <TD>Unicode string</TD>
61 * <TD><code>java.lang.String</code></TD>
62 * </TR>
63 * <TR>
64 * <TD>TARGET</TD>
65 * <TD>byte sequence</TD>
66 * <TD><code>byte[]</code></TD>
67 * </TR>
68 * <TR>
69 * <TD>HTTP</TD>
70 * <TD>byte sequence</TD>
71 * <TD><code>byte[]</code></TD>
72 * </TR>
73 * <TR>
74 * <TD>WHO</TD>
75 * <TD>byte sequence</TD>
76 * <TD><code>byte[]</code></TD>
77 * </TR>
78 * <TR>
79 * <TD>OBJECT_CLASS</TD>
80 * <TD>byte sequence</TD>
81 * <TD><code>byte[]</code></TD>
82 * </TR>
83 * <TR>
84 * <TD>APPLICATION_PARAMETER</TD>
85 * <TD>byte sequence</TD>
86 * <TD><code>byte[]</code></TD>
87 * </TR>
88 * </TABLE>
89 * <P>
90 * The <code>APPLICATION_PARAMETER</code> header requires some additional
91 * explanation. The byte array provided with the
92 * <code>APPLICATION_PARAMETER</code> should be of the form Tag-Length-Value
93 * according to the OBEX specification where Tag is a byte long, Length is a
94 * byte long, and Value is up to 255 bytes long. Multiple Tag-Length-Value
95 * triples are allowed within a single <code>APPLICATION_PARAMETER</code>
96 * header. The implementation will NOT check this condition. It is mentioned
97 * only to allow for interoperability between OBEX implementations.
98 * <P>
99 * <STRONG>User Defined Headers</STRONG>
100 * <P>
101 * OBEX allows 64 user-defined header values. Depending on the header identifier
102 * provided, headers have different types. The table below defines the ranges
103 * and their types. <TABLE BORDER>
104 * <TR>
105 * <TH>Header Identifier</TH>
106 * <TH>Decimal Range</TH>
107 * <TH>OBEX Type</TH>
108 * <TH>Java Type</TH>
109 * </TR>
110 * <TR>
111 * <TD>0x30 to 0x3F</TD>
112 * <TD>48 to 63</TD>
113 * <TD>Unicode String</TD>
114 * <TD><code>java.lang.String</code></TD>
115 * </TR>
116 * <TR>
117 * <TD>0x70 to 0x7F</TD>
118 * <TD>112 to 127</TD>
119 * <TD>byte sequence</TD>
120 * <TD><code>byte[]</code></TD>
121 * </TR>
122 * <TR>
123 * <TD>0xB0 to 0xBF</TD>
124 * <TD>176 to 191</TD>
125 * <TD>1 byte</TD>
126 * <TD><code>java.lang.Byte</code></TD>
127 * </TR>
128 * <TR>
129 * <TD>0xF0 to 0xFF</TD>
130 * <TD>240 to 255</TD>
131 * <TD>4 byte unsigned integer</TD>
132 * <TD><code>java.lang.Long</code> in the range 0 to 2<sup>32</sup>-1</TD>
133 * </TR>
134 * </TABLE>
135 *
136 * @version 1.0 February 11, 2002
137 */
138 public interface HeaderSet {
139
140 /**
141 * Represents the OBEX Count header. This allows the connection statement to
142 * tell the server how many objects it plans to send or retrieve.
143 * <P>
144 * The value of <code>COUNT</code> is 0xC0 (192).
145 */
146 public static final int COUNT = 0xC0;
147
148 /**
149 * Represents the OBEX Name header. This specifies the name of the object.
150 * <P>
151 * The value of <code>NAME</code> is 0x01 (1).
152 */
153 public static final int NAME = 0x01;
154
155 /**
156 * Represents the OBEX Type header. This allows a request to specify the
157 * type of the object (e.g. text, html, binary, etc.).
158 * <P>
159 * The value of <code>TYPE</code> is 0x42 (66).
160 */
161 public static final int TYPE = 0x42;
162
163 /**
164 * Represents the OBEX Length header. This is the length of the object in
165 * bytes.
166 * <P>
167 * The value of <code>LENGTH</code> is 0xC3 (195).
168 */
169 public static final int LENGTH = 0xC3;
170
171 /**
172 * Represents the OBEX Time header using the ISO 8601 standards. This is the
173 * preferred time header.
174 * <P>
175 * The value of <code>TIME_ISO_8601</code> is 0x44 (68).
176 */
177 public static final int TIME_ISO_8601 = 0x44;
178
179 /**
180 * Represents the OBEX Time header using the 4 byte representation. This is
181 * only included for backwards compatibility. It represents the number of
182 * seconds since January 1, 1970.
183 * <P>
184 * The value of <code>TIME_4_BYTE</code> is 0xC4 (196).
185 */
186 public static final int TIME_4_BYTE = 0xC4;
187
188 /**
189 * Represents the OBEX Description header. This is a text description of the
190 * object.
191 * <P>
192 * The value of <code>DESCRIPTION</code> is 0x05 (5).
193 */
194 public static final int DESCRIPTION = 0x05;
195
196 /**
197 * Represents the OBEX Target header. This is the name of the service an
198 * operation is targeted to.
199 * <P>
200 * The value of <code>TARGET</code> is 0x46 (70).
201 */
202 public static final int TARGET = 0x46;
203
204 /**
205 * Represents the OBEX HTTP header. This allows an HTTP 1.X header to be
206 * included in a request or reply.
207 * <P>
208 * The value of <code>HTTP</code> is 0x47 (71).
209 */
210 public static final int HTTP = 0x47;
211
212 /**
213 * Represents the OBEX Who header. Identifies the OBEX application to
214 * determine if the two peers are talking to each other.
215 * <P>
216 * The value of <code>WHO</code> is 0x4A (74).
217 */
218 public static final int WHO = 0x4A;
219
220 /**
221 * Represents the OBEX Object Class header. This header specifies the OBEX
222 * object class of the object.
223 * <P>
224 * The value of <code>OBJECT_CLASS</code> is 0x4F (79).
225 */
226 public static final int OBJECT_CLASS = 0x4F;
227
228 /**
229 * Represents the OBEX Application Parameter header. This header specifies
230 * additional application request and response information.
231 * <P>
232 * The value of <code>APPLICATION_PARAMETER</code> is 0x4C (76).
233 */
234 public static final int APPLICATION_PARAMETER = 0x4C;
235
236 /**
237 * Sets the value of the header identifier to the value provided. The type
238 * of object must correspond to the Java type defined in the description of
239 * this interface. If <code>null</code> is passed as the
240 * <code>headerValue</code> then the header will be removed from the set
241 * of headers to include in the next request.
242 *
243 * @param headerID
244 * the identifier to include in the message
245 *
246 * @param headerValue
247 * the value of the header identifier
248 *
249 * @exception IllegalArgumentException
250 * if the header identifier provided is not one defined in
251 * this interface or a user-defined header; if the type of
252 * <code>headerValue</code> is not the correct Java type as
253 * defined in the description of this interface
254 */
255 public void setHeader(int headerID, Object headerValue);
256
257 /**
258 * Retrieves the value of the header identifier provided. The type of the
259 * Object returned is defined in the description of this interface.
260 *
261 * @param headerID
262 * the header identifier whose value is to be returned
263 *
264 * @return the value of the header provided or <code>null</code> if the
265 * header identifier specified is not part of this
266 * <code>HeaderSet</code> object
267 *
268 * @exception IllegalArgumentException
269 * if the <code>headerID</code> is not one defined in this
270 * interface or any of the user-defined headers
271 *
272 * @exception IOException
273 * if an error occurred in the transport layer during the
274 * operation or if the connection has been closed
275 */
276 public Object getHeader(int headerID) throws IOException;
277
278 /**
279 * Retrieves the list of headers that may be retrieved via the
280 * <code>getHeader</code> method that will not return <code>null</code>.
281 * In other words, this method returns all the headers that are available in
282 * this object.
283 *
284 * @see #getHeader
285 *
286 * @return the array of headers that are set in this object or
287 * <code>null</code> if no headers are available
288 *
289 * @exception IOException
290 * if an error occurred in the transport layer during the
291 * operation or the connection has been closed
292 */
293 public int[] getHeaderList() throws IOException;
294
295 /**
296 * Sets the authentication challenge header. The <code>realm</code> will
297 * be encoded based upon the default encoding scheme used by the
298 * implementation to encode strings. Therefore, the encoding scheme used to
299 * encode the <code>realm</code> is application dependent.
300 *
301 * @param realm
302 * a short description that describes what password to use; if
303 * <code>null</code> no realm will be sent in the
304 * authentication challenge header
305 *
306 * @param userID
307 * if <code>true</code>, a user ID is required in the reply;
308 * if <code>false</code>, no user ID is required
309 *
310 * @param access
311 * if <code>true</code> then full access will be granted if
312 * successful; if <code>false</code> then read-only access will
313 * be granted if successful
314 */
315 public void createAuthenticationChallenge(String realm, boolean userID, boolean access);
316
317 /**
318 * Returns the response code received from the server. Response codes are
319 * defined in the <code>ResponseCodes</code> class.
320 *
321 * @see ResponseCodes
322 *
323 * @return the response code retrieved from the server
324 *
325 * @exception IOException
326 * if an error occurred in the transport layer during the
327 * transaction; if this method is called on a
328 * <code>HeaderSet</code> object created by calling
329 * <code>createHeaderSet()</code> in a
330 * <code>ClientSession</code> object; if an OBEX server
331 * created this object
332 */
333 public int getResponseCode() throws IOException;
334 }