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 Values	OBEX Representation	Java Type
COUNT	4 byte unsigned integer	java.lang.Long in the range 0 to 232-1
NAME	Unicode string	java.lang.String
TYPE	ASCII string	java.lang.String
LENGTH	4 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_BYTE	4 byte unsigned integer	java.util.Calendar
DESCRIPTION	Unicode string	java.lang.String
TARGET	byte sequence	byte[]
HTTP	byte sequence	byte[]
WHO	byte sequence	byte[]
OBJECT_CLASS	byte sequence	byte[]
APPLICATION_PARAMETER	byte 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 Identifier	Decimal Range	OBEX Type	Java Type
0x30 to 0x3F	48 to 63	Unicode String	java.lang.String
0x70 to 0x7F	112 to 127	byte sequence	byte[]
0xB0 to 0xBF	176 to 191	1 byte	java.lang.Byte
0xF0 to 0xFF	240 to 255	4 byte unsigned integer	java.lang.Long in the range 0 to 232-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(java.lang.String realm, boolean userID, boolean access) Sets the authentication challenge header.
java.lang.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, java.lang.Object headerValue) Sets the value of the header identifier to the value provided.

Field Detail

COUNT

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

See Also:

Constant Field Values

NAME

static final int NAME

Represents the OBEX Name header. This specifies the name of the object.

The value of NAME is 0x01 (1).

See Also:

Constant Field Values

TYPE

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

See Also:

Constant Field Values

LENGTH

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

See Also:

Constant Field Values

TIME_ISO_8601

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

See Also:

Constant Field Values

TIME_4_BYTE

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

See Also:

Constant Field Values

DESCRIPTION

static final int DESCRIPTION

Represents the OBEX Description header. This is a text description of the object.

The value of DESCRIPTION is 0x05 (5).

See Also:

Constant Field Values

TARGET

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

See Also:

Constant Field Values

HTTP

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

See Also:

Constant Field Values

WHO

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

See Also:

Constant Field Values

OBJECT_CLASS

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

See Also:

Constant Field Values

APPLICATION_PARAMETER

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

See Also:

Constant Field Values

Method Detail

setHeader

void setHeader(int headerID,
               java.lang.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:

java.lang.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

getHeader

java.lang.Object getHeader(int headerID)
                           throws java.io.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:

java.lang.IllegalArgumentException - if the headerID is not one defined in this interface or any of the user-defined headers

java.io.IOException - if an error occurred in the transport layer during the operation or if the connection has been closed

getHeaderList

int[] getHeaderList()
                    throws java.io.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:

java.io.IOException - if an error occurred in the transport layer during the operation or the connection has been closed

See Also:

getHeader(int)

createAuthenticationChallenge

void createAuthenticationChallenge(java.lang.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

getResponseCode

int getResponseCode()
                    throws java.io.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:

java.io.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

See Also:

ResponseCodes