javax.obex.HeaderSet Maven / Gradle / Ivy
/**
* BlueCove - Java library for Bluetooth
*
* Java docs licensed under the Apache License, Version 2.0
* http://www.apache.org/licenses/LICENSE-2.0
* (c) Copyright 2001, 2002 Motorola, Inc. ALL RIGHTS RESERVED.
*
* @version $Id: HeaderSet.java 549 2007-06-22 22:19:46Z skarzhevskyy $
*/
package javax.obex;
import java.io.IOException;
/**
* 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
*
*
* @version 1.0 February 11, 2002
*/
public interface HeaderSet {
/**
* 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).
*/
public static final int COUNT = 0xC0;
/**
* Represents the OBEX Name header. This specifies the name of the object.
*
* The value of NAME is 0x01 (1).
*/
public static final int NAME = 0x01;
/**
* 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).
*/
public static final int TYPE = 0x42;
/**
* Represents the OBEX Length header. This is the length of the object in
* bytes.
*
* The value of LENGTH is 0xC3 (195).
*/
public static final int LENGTH = 0xC3;
/**
* 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).
*/
public static final int TIME_ISO_8601 = 0x44;
/**
* 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).
*/
public static final int TIME_4_BYTE = 0xC4;
/**
* Represents the OBEX Description header. This is a text description of the
* object.
*
* The value of DESCRIPTION is 0x05 (5).
*/
public static final int DESCRIPTION = 0x05;
/**
* Represents the OBEX Target header. This is the name of the service an
* operation is targeted to.
*
* The value of TARGET is 0x46 (70).
*/
public static final int TARGET = 0x46;
/**
* 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).
*/
public static final int HTTP = 0x47;
/**
* 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).
*/
public static final int WHO = 0x4A;
/**
* Represents the OBEX Object Class header. This header specifies the OBEX
* object class of the object.
*
* The value of OBJECT_CLASS is 0x4F (79).
*/
public static final int OBJECT_CLASS = 0x4F;
/**
* Represents the OBEX Application Parameter header. This header specifies
* additional application request and response information.
*
* The value of APPLICATION_PARAMETER is 0x4C (76).
*/
public static final int APPLICATION_PARAMETER = 0x4C;
/**
* 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.
*
* @param headerID
* the identifier to include in the message
*
* @param headerValue
* the value of the header identifier
*
* @exception 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
*/
public void setHeader(int headerID, Object headerValue);
/**
* Retrieves the value of the header identifier provided. The type of the
* Object returned is defined in the description of this interface.
*
* @param headerID
* the header identifier whose value is to be returned
*
* @return the value of the header provided or null if the
* header identifier specified is not part of this
* HeaderSet object
*
* @exception IllegalArgumentException
* if the headerID is not one defined in this
* interface or any of the user-defined headers
*
* @exception IOException
* if an error occurred in the transport layer during the
* operation or if the connection has been closed
*/
public Object getHeader(int headerID) 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.
*
* @see #getHeader
*
* @return the array of headers that are set in this object or
* null if no headers are available
*
* @exception IOException
* if an error occurred in the transport layer during the
* operation or the connection has been closed
*/
public int[] getHeaderList() throws IOException;
/**
* 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.
*
* @param realm
* a short description that describes what password to use; if
* null no realm will be sent in the
* authentication challenge header
*
* @param userID
* if true, a user ID is required in the reply;
* if false, no user ID is required
*
* @param access
* if true then full access will be granted if
* successful; if false then read-only access will
* be granted if successful
*/
public void createAuthenticationChallenge(String realm, boolean userID, boolean access);
/**
* Returns the response code received from the server. Response codes are
* defined in the ResponseCodes class.
*
* @see ResponseCodes
*
* @return the response code retrieved from the server
*
* @exception 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
*/
public int getResponseCode() throws IOException;
}