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(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

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,
               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

getHeader

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

getHeaderList

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
See Also:
getHeader(int)

createAuthenticationChallenge

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

getResponseCode

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
See Also:
ResponseCodes


JSR-82 Javadocs Apache License, Version 2.0 Copyright © 2001-2008 Motorola, Inc. ALL RIGHTS RESERVED.
BlueCove Javadocs
Apache License, Version 2.0 Copyright © 2004-2008 BlueCove Team.