javax.obex
Interface HeaderSet


public interface HeaderSet

The HeaderSet interface defines the methods that set and get the values of OBEX headers.

The following table describes how the headers specified in this interface are represented in OBEX and in Java. The Java types are used with the setHeader() and getHeader() methods and specify the type of object that must be provided and will be returned from these methods, respectively.
Header ValuesOBEX RepresentationJava Type
COUNT4 byte unsigned integer java.lang.Long in the range 0 to 232-1
NAMEUnicode string java.lang.String
TYPEASCII string java.lang.String
LENGTH4 byte unsigned integer java.lang.Long in the range 0 to 232-1
TIME_ISO_8601 ASCII string of the form YYYYMMDDTHHMMSS[Z] where [Z] specifies Zulu time java.util.Calendar
TIME_4_BYTE4 byte unsigned integer java.util.Calendar
DESCRIPTIONUnicode string java.lang.String
TARGETbyte sequence byte[]
HTTPbyte sequence byte[]
WHObyte sequence byte[]
OBJECT_CLASSbyte sequence byte[]
APPLICATION_PARAMETERbyte sequence byte[]

The APPLICATION_PARAMETER header requires some additional explanation. The byte array provided with the APPLICATION_PARAMETER should be of the form Tag-Length-Value according to the OBEX specification where Tag is a byte long, Length is a byte long, and Value is up to 255 bytes long. Multiple Tag-Length-Value triples are allowed within a single APPLICATION_PARAMETER header. The implementation will NOT check this condition. It is mentioned only to allow for interoperability between OBEX implementations.

User Defined Headers

OBEX allows 64 user-defined header values. Depending on the header identifier provided, headers have different types. The table below defines the ranges and their types.
Header IdentifierDecimal RangeOBEX Type Java Type
0x30 to 0x3F48 to 63Unicode String java.lang.String
0x70 to 0x7F112 to 127byte sequence byte[]
0xB0 to 0xBF176 to 1911 byte java.lang.Byte
0xF0 to 0xFF240 to 2554 byte unsigned integer java.lang.Long in the range 0 to 232-1

Since:
JDE 4.2.1

Field Summary
static int APPLICATION_PARAMETER
          Represents the OBEX Application Parameter header.
static int COUNT
          Represents the OBEX Count header.
static int DESCRIPTION
          Represents the OBEX Description header.
static int HTTP
          Represents the OBEX HTTP header.
static int LENGTH
          Represents the OBEX Length header.
static int NAME
          Represents the OBEX Name header.
static int OBJECT_CLASS
          Represents the OBEX Object Class header.
static int TARGET
          Represents the OBEX Target header.
static int TIME_4_BYTE
          Represents the OBEX Time header using the 4 byte representation.
static int TIME_ISO_8601
          Represents the OBEX Time header using the ISO 8601 standards.
static int TYPE
          Represents the OBEX Type header.
static int WHO
          Represents the OBEX Who header.
 
Method Summary
 void createAuthenticationChallenge(String realm, boolean userID, boolean access)
          Sets the authentication challenge header.
 Object getHeader(int headerID)
          Retrieves the value of the header identifier provided.
 int[] getHeaderList()
          Retrieves the list of headers that may be retrieved via the getHeader method that will not return null.
 int getResponseCode()
          Returns the response code received from the server.
 void setHeader(int headerID, Object headerValue)
          Sets the value of the header identifier to the value provided.
 

Field Detail

APPLICATION_PARAMETER

public static final int APPLICATION_PARAMETER
Represents the OBEX Application Parameter header. This header specifies additional application request and response information.

The value of APPLICATION_PARAMETER is 0x4C (76).

Since:
JDE 4.2.1

COUNT

public static final int COUNT
Represents the OBEX Count header. This allows the connection statement to tell the server how many objects it plans to send or retrieve.

The value of COUNT is 0xC0 (192).

Since:
JDE 4.2.1

DESCRIPTION

public static final int DESCRIPTION
Represents the OBEX Description header. This is a text description of the object.

The value of DESCRIPTION is 0x05 (5).

Since:
JDE 4.2.1

HTTP

public static final int HTTP
Represents the OBEX HTTP header. This allows an HTTP 1.X header to be included in a request or reply.

The value of HTTP is 0x47 (71).

Since:
JDE 4.2.1

LENGTH

public static final int LENGTH
Represents the OBEX Length header. This is the length of the object in bytes.

The value of LENGTH is 0xC3 (195).

Since:
JDE 4.2.1

NAME

public static final int NAME
Represents the OBEX Name header. This specifies the name of the object.

The value of NAME is 0x01 (1).

Since:
JDE 4.2.1

OBJECT_CLASS

public static final int OBJECT_CLASS
Represents the OBEX Object Class header. This header specifies the OBEX object class of the object.

The value of OBJECT_CLASS is 0x4F (79).

Since:
JDE 4.2.1

TARGET

public static final int TARGET
Represents the OBEX Target header. This is the name of the service an operation is targeted to.

The value of TARGET is 0x46 (70).

Since:
JDE 4.2.1

TIME_4_BYTE

public static final int TIME_4_BYTE
Represents the OBEX Time header using the 4 byte representation. This is only included for backwards compatibility. It represents the number of seconds since January 1, 1970.

The value of TIME_4_BYTE is 0xC4 (196).

Since:
JDE 4.2.1

TIME_ISO_8601

public static final int TIME_ISO_8601
Represents the OBEX Time header using the ISO 8601 standards. This is the preferred time header.

The value of TIME_ISO_8601 is 0x44 (68).

Since:
JDE 4.2.1

TYPE

public static final int TYPE
Represents the OBEX Type header. This allows a request to specify the type of the object (e.g. text, html, binary, etc.).

The value of TYPE is 0x42 (66).

Since:
JDE 4.2.1

WHO

public static final int WHO
Represents the OBEX Who header. Identifies the OBEX application to determine if the two peers are talking to each other.

The value of WHO is 0x4A (74).

Since:
JDE 4.2.1
Method Detail

createAuthenticationChallenge

public void createAuthenticationChallenge(String realm,
                                          boolean userID,
                                          boolean access)
Sets the authentication challenge header. The realm will be encoded based upon the default encoding scheme used by the implementation to encode strings. Therefore, the encoding scheme used to encode the realm is application dependent.
Parameters:
realm - a short description that describes what password to use; if null no realm will be sent in the authentication challenge header
userID - if true, a user ID is required in the reply; if false, no user ID is required
access - if true then full access will be granted if successful; if false then read-only access will be granted if successful
Since:
JDE 4.2.1

getHeader

public Object getHeader(int headerID)
                 throws IOException
Retrieves the value of the header identifier provided. The type of the Object returned is defined in the description of this interface.
Parameters:
headerID - the header identifier whose value is to be returned
Returns:
the value of the header provided or null if the header identifier specified is not part of this HeaderSet object
Throws:
IllegalArgumentException - if the headerID is not one defined in this interface or any of the user-defined headers
IOException - if an error occurred in the transport layer during the operation or if the connection has been closed
Since:
JDE 4.2.1

getHeaderList

public int[] getHeaderList()
                    throws IOException
Retrieves the list of headers that may be retrieved via the getHeader method that will not return null. In other words, this method returns all the headers that are available in this object.
Returns:
the array of headers that are set in this object or null if no headers are available
Throws:
IOException - if an error occurred in the transport layer during the operation or the connection has been closed
Since:
JDE 4.2.1
See Also:
getHeader(int)

getResponseCode

public int getResponseCode()
                    throws IOException
Returns the response code received from the server. Response codes are defined in the ResponseCodes class.
Returns:
the response code retrieved from the server
Throws:
IOException - if an error occurred in the transport layer during the transaction; if this method is called on a HeaderSet object created by calling createHeaderSet() in a ClientSession object; if an OBEX server created this object
Since:
JDE 4.2.1
See Also:
ResponseCodes

setHeader

public void setHeader(int headerID,
                      Object headerValue)
Sets the value of the header identifier to the value provided. The type of object must correspond to the Java type defined in the description of this interface. If null is passed as the headerValue then the header will be removed from the set of headers to include in the next request.
Parameters:
headerID - the identifier to include in the message
headerValue - the value of the header identifier
Throws:
IllegalArgumentException - if the header identifier provided is not one defined in this interface or a user-defined header; if the type of headerValue is not the correct Java type as defined in the description of this interface
Since:
JDE 4.2.1



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.