UNIT IV - Chapter 3 - Bluetooth API

With the profileration of a large number of micro devices there was a genuine need for a replacement for the infra red (IR) data transfer technology. As most of you who have used the IR data transfer technology know what a tedious task it is to transfer even a small amount of data through IR. Also with the increase in devices there was also an increase in the number of wires on the desk. In fact I am personally quite fedup with the large number of wires interconnecting the various devices. Thus there was a strong need for a replacement for the above discussed problems. The bluetooth technology does precisely that.

 

The bluetooth technolgy was launched to eradicate the wires and make it convenient to connect various devices. It uses the free spectrum to create a personal area network for the user so that he or she can easily connect different devices wirelessly. In doing so this technology takes care of many issues that if not taken care off might cause problems. Companies like Microsoft, Motorola, Nokia, IBM, Intel, Ericsson and 3Com support it. Thus it has become a very pervasive technology. These days you will find that most phone above the US$ 250 range support bluetooth.

 

The use of bluetooth spreads beyond any individual platform. You can use this technology with Desktop PC, Laptops, PDAs and mobile phones. Thus the knowledge of this technology is fundamental to mobile phone software programming. In fact this technology can also play a great role in future for multi-player games, remote controllers and a host of other novel application. I would recommend you to visit http://www.bluetooth.com for more details on this technology.

 

Since bluetooth technology is fundamental to the future of mobile phones it was obvious for the founders of the J2ME technology to support bluetooth technology. The bluetooth API which has been defined as a part of the JSR 82 is very robust and flexible. It is designed to work on top of the ‘Connected, Limited Device Configuration’ CLDC 1.0. This has certain obvious advantages. First this API will be made available on a large number of devices. Plus in the future even devices that do not support MIDP but support CLDC 1.0 may also support it. Thus the day is not far when we will be using this API for a variety of purposes and to integrate different devices with the MIDP enabled devices. Here we should also keep in mind that this API is an optional API for devices supporting CLDC and MIDP. We can not assume this API to be available on each and every device.

 

I would like to bring to your notice that this API has been specified with the support of IBM, Motorola, Nokia, Sony Erricsson Mobile Communications, Sun Microsystems and Symbian among others. Thus we can assume that a large number of devices will in future support this API.

 

JSR 82 defines the ‘Java APIs for Bluetooth Wireless Technology’. This specification defines 2 packages namely:

 

·   javax.bluetooth

·   javax.obex

 

Both the packages are separate optional packages. The device manufacturers have the liberty to incluse any particular package of the two packages. In fact Nokia has exercised this option and most Nokia phones which support javax.bluetooth package currently do not support javax.obex.

 

Bluetooth Diagram

 

javax.bluetooth

The javax.bluetooth package defines the interface and classes that let us work with the blueooth technology. This package lets us use the RFCOMM and L2CAP protocols for communication. Now we will see the contents of this package in detail.

 

 

// To check diagram

 

public interface DiscoveryListener

What is it?

This interface allows an application to receive device discovery and service discovery events. This interface provides us with methods for discovering devices and services.

 

o    Fields

  • public static final int INQUIRY_COMPLETED

This field indicates the normal completion of device discovery. It is used with the inquiryCompleted() method.

·         public static final int INQUIRY_TERMINATED

This field indicates that device discovery has been canceled by the application and did not complete. It is used with the inquiryCompleted() method.

·         public static final int INQUIRY_ERROR

This field indicates that the inquiry request failed to complete normally and was not cancelled.

·         public static final int SERVICE_SEARCH_COMPLETED

This field indicates the normal completion of service discovery. It is used with the serviceSearchCompleted() method.

·         public static final int SERVICE_SEARCH_TERMINATED

This field indicates that the service search has been canceled by the application and did not complete. This field is used with the serviceSearchCompleted() method.

·         public static final int SERVICE_SEARCH_ERROR

This field indicates the service search terminated with an error. This field is used with the serviceSearchCompleted() method.

·         public static final int SERVICE_SEARCH_NO_RECORDS

This field indicates the service search has completed with no service records found on the device. This field is used with the serviceSearchCompleted() method.

·         public static final int SERVICE_SEARCH_DEVICE_NOT_REACHABLE

This field indicates the service search could not be completed because the remote device provided to DiscoveryAgent.searchServices() could not be reached. This field is used with the serviceSearchCompleted() method.

 

o    Method

  • public void deviceDiscovered(RemoteDevice btDevice,DeviceClass cod)

This method is called when a device is found during an inquiry.

·         public void servicesDiscovered(int transID,ServiceRecord[] servRecord)

This method is called when services are found during a service search.

·         public void serviceSearchCompleted(int transID,int respCode)

This method is called when a service search is completed or was terminated because of an error. The respCode parameter may contain the following the values:

 

·   SERVICE_SEARCH_COMPLETED

·   SERVICE_SEARCH_TERMINATED

·   SERVICE_SEARCH_ERROR

·   SERVICE_SEARCH_NO_RECORDS

·   SERVICE_SEARCH_DEVICE_NOT_REACHABLE

·         public void inquiryCompleted(int discType)

This method is called when an inquiry is completed.

 

public interface L2CAPConnection

What is it?

A connection-oriented L2CAP channel is represented by this interface. The protocol btl2cap is used for creating a client connection.

 

o    Field

  • public static final int DEFAULT_MTU

This field stands for the Default MTU value for connection-oriented channels which is 672 bytes.

 

What is MTU?

 

MTU stands for ‘Maximum Transmission Unit’. ReceiveMTU and TransmitMTU are two important terms you will encounter while working with the L2CAP protocol. There descriptions are as follows:

 

ReceiveMTU: It stands for the maximum payload size this connection can accept.

TransmitMTU: It stands for the maximum paylioad size this connection can send.

·         public static final int MINIMUM_MTU

This field stands for the minimum MTU value for connection-oriented channels which is 48 bytes.

 

o    Methods

  • public int getTransmitMTU()throws java.io.IOException

This method returns the maximum number of bytes that can be sent in a single call to send() without losing any data.

·         public int getReceiveMTU()throws java.io.IOException

This method returns the maximum number of bytes that can be read in a single call to receive ().

·         public void send(byte[] data)throws java.io.IOException

This method requests that data be sent to the remote device. TransmitMTU determines the amount of data that can be sent successfully in a single send operation.

·         public int receive(byte[] inBuf)throws java.io.IOException

This method reads a packet of data. The amount of data received in this operation is related to the value of ReceiveMTU and if the size of inBuf is greater than or equal to ReceiveMTU then no data will be lost.

·         public boolean ready()throws java.io.IOException

This method determines if there is a packet that can be read via a call to receive(). This method returns true if there is data to read. It returns false if there is no data to be read.

 

public interface L2CAPConnectionNotifier

What is it?

This interface provides an L2CAP connection notifier. The btl2cap protocol must be used to create a server connection.

 

o    Methods

  • public L2CAPConnection acceptAndOpen()throws java.io.IOException

This method returns a connection to communicate with the client.

 

public interface ServiceRecord

What is it?

This interface describes characteristics of a Bluetooth service. It contains a set of service attributes. Each service attribute it contains is an (ID, value) pair. Each Bluetooth attribute ID is a 16-bit unsigned integer. On the other hand the attribute value is a DataElement.

 

The objects implementing this interface are made available to a client application through an argument of the servicesDiscovered method of the DiscoveryListener interface. They are made available to server applications through the method getRecord() on LocalDevice.

 

Here is a subset of the most common service attribute name and there IDs.

·   ServiceRecordHandle

Attribute ID: 0x0000

 

·   ServiceClassIDList

Attribute ID: 0x0001

 

·   ServiceRecordState

Attribute ID: 0x0002

 

·   ServiceID

Attribute ID: 0x0003

 

·   ProtocolDescriptorList

Attribute ID: 0x0004

 

·   BrowseGroupList

Attribute ID: 0x0005

 

·   LanguageBasedAttributeIDList

Attribute ID: 0x0006

 

·   ServiceInfoTimeToLive

Attribute ID: 0x0007

 

·   ServiceAvailability

Attribute ID: 0x0008

 

·   BluetoothProfileDescriptorList

Attribute ID: 0x0009

 

·   DocumentationURL

Attribute ID: 0x000A

 

·   ClientExecutableURL

Attribute ID: 0x000B

 

·   IconURL

Attribute ID: 0x000C

 

·   VersionNumberList

Attribute ID: 0x0200

 

·   ServiceDatabaseState

Attribute ID: 0x0201

 

o    Field

·         public static final int NOAUTHENTICATE_NOENCRYPT
This field is used with getConnectionURL() method. It tells that authentication and encryption are not needed on a connection to this service.

·         public static final int AUTHENTICATE_NOENCRYPT

This field is used with getConnectionURL() method. It tells that authentication is required for connections to this service but not encryption. It tells that it is OK for encryption to be either on or off for the connection.

·         public static final int AUTHENTICATE_ENCRYPT

This field is used with getConnectionURL() method. It tells that authentication and encryption are required for connections to this service.

 

o    Methods

·         public DataElement getAttributeValue(int attrID)

This method returns the value of the attribute ID if present in the service record. In case it is not present it returns null.

·         public RemoteDevice getHostDevice()

This method returns the remote Bluetooth device that populated the service record. It returns null if the local device populated this ServiceRecord.

·         public int[] getAttributeIDs()

This method returns an array of service attribute IDs that are in this object and have values for them. In case there are no attribute IDs that have values then this method will return an array of zero length.

·         public boolean populateRecord(int[] attrIDs) throws java.io.IOException

This method returns true if the request was successful in retrieving values for some or the entire attribute IDs. It returns false if it was unsuccessful in retrieving any values.

·         public java.lang.String getConnectionURL(int requiredSecurity,                                         boolean mustBeMaster)

This method returns a string that can be used to connect to the service. It returns null in case the ProtocolDescriptorList in this ServiceRecord is not formatted according to the Bluetooth specification.

·         public void setDeviceServiceClasses(int classes)

This method is used by a server application to indicate the major service class bits that should be activated in the server's DeviceClass when this ServiceRecord is added to the SDDB.

·         public boolean setAttributeValue(int attrID,DataElement attrValue)

This method returns true if the service attribute was successfully added, removed, or modified. It returns false if attrValue is null and attrID is not in this object.

 

public class DataElement

What is it?

The various data types that a Bluetooth service attribute value may have are defined in this class.

 

o    Constructors

  • public DataElement(int valueType)

This constructor creates a DataElement of type NULL, DATALT or DATSEQ.

·         public DataElement(boolean bool)

This constructor creates a DataElement whose data type is BOOL and whose value is equal to bool.

·         public DataElement(int valueType,long value)

This constructor creates a DataElement that encapsulates an integer value of the following sizes:

·         U_INT_1

·         U_INT_2

·         U_INT_4

·         INT_1

·         INT_2

·         INT_4

·         INT_8.

·         public DataElement(int valueType,java.lang.Object value)

This constructor creates a DataElement whose data type is given by valueType. Its value is refered by the parameter value.

 

o    Fields

  • public static final int NULL

This field defines data of type NULL.

·         public static final int U_INT_1

This field defines an unsigned integer of size one byte.

·         public static final int U_INT_2

This field defines an unsigned integer of size two bytes.

·         public static final int U_INT_4

This field defines an unsigned integer of size four bytes.

·         public static final int U_INT_8

This field defines an unsigned integer of size eight bytes.

·         public static final int U_INT_16

This field defines an unsigned integer of size sixteen bytes.

·         public static final int INT_1

This field defines a signed integer of size one byte.

·         public static final int INT_2

This field defines a signed integer of size two bytes.

·         public static final int INT_4

This field defines a signed integer of size four bytes.

·         public static final int INT_8

This field defines a signed integer of size eight bytes.

·         public static final int INT_16

This field defines a signed integer of size sixteen bytes.

·         public static final int URL

This field defines data of type URL.

·         public static final int UUID

This field defines data of type UUID.

·         public static final int BOOL

This field defines data of type BOOL.

·         public static final int STRING

This field defines data of type STRING.

·         public static final int DATSEQ

This field defines data of type DATSEQ.

·         public static final int DATALT

This field defines data of type DATALT.

 

o    Method

  • public void addElement(DataElement elem)

This method adds a DataElement to this DATALT or DATSEQ DataElement object. The addition will be at the end of the list.

·         public void insertElementAt(DataElement elem,int index)

This method inserts a DataElement at the specified location.

·         public int getSize()

This method returns the number of DataElements that are present in this DATALT or DATSEQ object.

·         public boolean removeElement(DataElement elem)

This method removes the first occurrence of the DataElement from this object.

·         public int getDataType()

This method returns the data type of the object this DataElement represents.

·         public long getLong()

This method returns the value of the DataElement if it can be represented as a long.

·         public boolean getBoolean()

This method returns the boolean value of this DataElement object.

·         public java.lang.Object getValue()

This method returns the value of this DataElement as an Object.

 

public class DeviceClass

What is it?

This class represents the class of device record as defined in the Bluetooth specification. Bluetooth Assigned Numbers document defines this record and contains information on the type of the device and the type of services available on the device.

 

o    Constructor

  • public DeviceClass(int record)

This constructor creates a DeviceClass from the class of device record provided. Parameter record must follow the format of the class of device record in the Bluetooth specification.

 

o    Method

  • public int getServiceClasses()
This method returns the major service classes. A single device might have multiple major service classes.

·         public int getMajorDeviceClass()

This method returns the major device class. A single device might have only a single major device class.

·         public int getMinorDeviceClass()

This method returns the minor device class.

 

public class DiscoveryAgent

What is it?

 The methods to perform device and service discovery are provided to us by the DiscoveryAgent class. The one and only DiscoveryAgent object on the LocalDevice object can be retrieved by a call to getDiscoveryAgent() on the LocalDevice object.

 

The following are the details of device discovery and service discovery:

·   Device Discovery

There are two ways to discover devices through DiscoveryAgent class. The application may use startInquiry() to start an inquiry to find devices in proximity to the local device. The other way to discover devices is via the retrieveDevices() method that has been provided to us.

 

·   Service Discovery

We have been provided two ways to search for services also. For searching a service on a single device the searchServices() method should be used. In case you do not care which device a service is on then the selectService() method can be used.

 

o    Fields

  • public static final int NOT_DISCOVERABLE

This field takes the device out of discoverable mode.

·         public static final int GIAC

This field represents the inquiry access code for General/Unlimited Inquiry Access Code (GIAC). This field is used to specify the type of inquiry to complete or respond to.

·         public static final int LIAC

This field represents inquiry access code for Limited Dedicated Inquiry Access Code (LIAC). This field is used to specify the type of inquiry to complete or respond to.

·         public static final int CACHED

This field is used with the retrieveDevices() method to return those devices that were found via a previous inquiry.

·         public static final int PREKNOWN

This field is used with the retrieveDevices() method to return those devices that are defined to be pre-known devices.

 

o    Methods

  • public RemoteDevice[] retrieveDevices(int option)

This method returns an array containing the Bluetooth devices that were previously found if option is CACHED. It returns an array of devices that are preknown devices if option is PREKNOWN. It may also return null in case no devices meet the given criteria.

·         public boolean startInquiry(int accessCode,DiscoveryListener listener)throws                             BluetoothStateException

This method returns true if the inquiry was started. It may return false in case the inquiry was not started because the accessCode is not supported.

·         public boolean cancelInquiry(DiscoveryListener listener)

This method removes the device from inquiry mode. This method returns true if the inquiry was canceled. Otherwise it returns false in case the inquiry was not canceled or in case the inquiry was not started using listener.

·         public int searchServices(int[] attrSet,UUID[] uuidSet,RemoteDevice btDev,

      DiscoveryListener discListener) throws BluetoothStateException

This method searches for services on a remote Bluetooth device that have all the UUIDs specified in uuidSet. This method returns the transaction ID of the service search. The number returned must be positive.

·         public boolean cancelServiceSearch(int transID)

This method cancels the service search transaction that has the specified transaction ID. This method returns true if the service search transaction is terminated otherwise it returns false if the transID does not represent an active service search transaction.

·         public java.lang.String selectService(UUID uuid,int security,boolean master) throws BluetoothStateException

This method attempts to locate a service that contains uuid in the ServiceClassIDList of its service record. This method returns the connection string used to connect to the service with a UUID of uuid. It may return null if no service could be found with a UUID of uuid in the ServiceClassIDList.

 

public class LocalDevice

What is it?

The LocalDevice class defines the basic functions of the Bluetooth manager. This class provides access and control of the local bluetooth device.

 

o    Methods

This method returns an object that represents the local Bluetooth device.

·         public DiscoveryAgent getDiscoveryAgent()

This method returns the discovery agent for the local device.

·         public java.lang.String getFriendlyName()

This method returns the name of the local device. It may return null if the name could not be retrieved.

·         public DeviceClass getDeviceClass()

This method returns the service classes, major device class and minor device class of the local device. It may return null if the service classes, major device class or minor device class could not be determined.

·         public boolean setDiscoverable(int mode) throws BluetoothStateException

This method returns true if the request succeeded otherwise it returns false if the request failed because the BCC denied the request. It may also return false if the Bluetooth system does not support the access mode specified in mode.

·         public static java.lang.String getProperty(java.lang.String property)

This method retrieves the bluetooth system properties. The following properties among others are supported by this method:

·         bluetooth.api.version

·         bluetooth.master.switch

·         bluetooth.sd.attr.retrievable.max

·         bluetooth.connected.devices.max

·         bluetooth.l2cap.receiveMTU.max

·         bluetooth.sd.trans.max

·         bluetooth.connected.inquiry.scan

·         bluetooth.connected.page.scan

·         bluetooth.connected.inquiry

·         bluetooth.connected.page

 

This method returns the value of the property specified. It may return null if the property is not defined.

·         public int getDiscoverable()

This method returns the discoverable mode the device is presently in.

·         public java.lang.String getBluetoothAddress()

This method returns the Bluetooth address of the local device.

·         public ServiceRecord  getRecord(javax.microedition.io.Connection notifier)

This method returns the ServiceRecord associated with notifier.

·         public void updateRecord(ServiceRecord srvRecord) throws ServiceRegistrationException

This method updates the service record in the local SDDB that corresponds to the ServiceRecord parameter.

 

public class RemoteDevice

What is it?

This class represents a remote Bluetooth device. RemoteDevice class provides basic information about a remote device including the device's Bluetooth address and its friendly name.

 

o    Constructor

  • protected RemoteDevice(java.lang.String address)

This constructor creates a Bluetooth device based upon its address.

 

o    Methods

  • public boolean isTrustedDevice()

This method returns true if the device is a trusted device. It returns false otherwise.

·         public java.lang.String getFriendlyName(boolean alwaysAsk)                                 throws java.io.IOException

This method returns the name of the device. It may return null if the Bluetooth system does not support this feature. In cases where the local device is able to contact the remote device, the result will never be null. In case the remote device does not have a name then an empty string will be returned by this method.

·         public final java.lang.String getBluetoothAddress()

This method returns the Bluetooth address of the remote device.

·         public boolean equals(java.lang.Object obj)

This method returns true if both devices have the same Bluetooth address. It returns false if both devices do not have the same address. It also return’s false if obj is null or if obj is not a RemoteDevice.

·         public int hashCode()

This method returns the hash code for this object.

·         public static RemoteDevice getRemoteDevice(javax.microedition.io.Connection conn)                                 throws java.io.IOException

This method returns the remote device involved in the connection.

·         public boolean authenticate() throws java.io.IOException

This method returns true if authentication is successful. In other cases it returns false.

·         public boolean authorize(javax.microedition.io.Connection conn)                  throws java.io.IOException

This method returns true if this RemoteDevice is successfully authenticated and authorized. In case the authentication or authorization fails it returns false.

·         public boolean encrypt(javax.microedition.io.Connection conn,                       boolean on)throws java.io.IOException

This method attempts to turn encryption on or off for an existing connection. This method returns true if the change succeeded. In other cases it returns false.

·         public boolean isAuthenticated()

This method returns true if this RemoteDevice has previously been authenticated. It returns false if it has not been authenticated or there are no open connections between the local device and this RemoteDevice.

·         public boolean isAuthorized(javax.microedition.io.Connection conn)                     throws java.io.IOException

This method returns true if conn is a server-side connection and this RemoteDevice has been authorized. In cases where the ‘conn’ parameter is a client-side connection or a server-side connection that has not been authorized it returns false.

·         public boolean isEncrypted()

This method returns true if data exchanges with this RemoteDevice are being encrypted. It returns false if the data exchanges are not being encrypted or there are no open connections between the local device and this RemoteDevice.

 

public class UUID

What is it?

This class defines universally unique identifiers. The 128-bit unsigned integers defined by this class are guaranteed to be unique across all time and space. Therefore an instance of this class is immutable.

 

The table below provides a short list of the most common UUIDs defined in the Bluetooth Assigned Numbers document.

 

·   Base UUID Value

Value: 0x0000000000001000800000805F9B34FB

 

·   SDP

Value: 0x0001

 

·   RFCOMM

Value: 0x0003

 

·   OBEX

Value: 0x0008

 

·   HTTP

Value: 0x000C

 

·   L2CAP

Value: 0x0100

 

·   BNEP

Value: 0x000F

 

·   Serial Port

Value: 0x1101

 

·   ServiceDiscoveryServerServiceClassID

Value: 0x1000

 

·   BrowseGroupDescriptorServiceClassID

Value: 0x1001

 

·   PublicBrowseGroup

Value: 0x1002

 

·   OBEX Object Push Profile

Value: 0x1105

 

·   OBEX File Transfer Profile

Value: 0x1106

 

·   Personal Area Networking User

Value: 0x1115

 

·   Network Access Point

Value: 0x1116

 

·   Group Network

Value: 0x1117

 

o    Constructors

·         public UUID(long uuidValue)

This constructor creates a UUID object from long value uuidValue.

·         public UUID(java.lang.String uuidValue,boolean shortUUID)

This constructor creates a UUID object from the string provided. Characters in this string must be from the hexadecimal set [0-9, a-f, A-F].

 

o    Methods

·         public java.lang.String toString()

This method returns the string representation of the UUID.

·         public boolean equals(java.lang.Object value)

This method returns true if the 128 bit values of the two objects are equal. It returns false otherwise.

·         public int hashCode()

This method returns the hash code for this object.

 

 

public class BluetoothConnectionException

What is it?

This exception is thrown when a Bluetooth connection cannot be established successfully. The cause of the exception is indicated by the fields in this exception class.

 

o    Constructor

  • public BluetoothConnectionException(int error) throws IllegalArgumentException

This constructor creates a new BluetoothConnectionException with the error indicator specified.

·         public BluetoothConnectionException(int error, java.lang.String msg) throws IllegalArgumentException

This constructor creates a new BluetoothConnectionException with the error indicator and message specified.

 

o    Fields

  • public static final int UNKNOWN_PSM

This field indicates the connection to the server failed because no service for the given PSM was registered.

·         public static final int SECURITY_BLOCK

This field indicates the connection failed because the security settings on the local device or the remote device were incompatible with the request.

·         public static final int NO_RESOURCES

This field indicates the connection failed due to a lack of resources either on the local device or on the remote device.

·         public static final int FAILED_NOINFO

This field indicates the connection to the server failed due to unknown reasons.

·         public static final int TIMEOUT

This field indicates the connection to the server failed due to a timeout.

·         public static final int UNACCEPTABLE_PARAMS

This field indicates the connection failed because the configuration parameters provided were not acceptable to either the remote device or the local device.

 

o    Method

  • public int getStatus()

This method returns cause for the exception. The value returned will be one of the constants defined in this class.

 

public class BluetoothStateException

What is it?

This exception is thrown when a request is made to the Bluetooth system and the system cannot support that request in its present state.

 

o    Constructors

  • public BluetoothStateException()

This constructor creates a new BluetoothStateException without a detail message.

·         public BluetoothStateException(java.lang.String msg)

This constructor creates a BluetoothStateException with the specified detail message.

 

public class ServiceRegistrationException

What is it?

This Exception is thrown when there is a failure to add a service record to the local Service Discovery Database (SDDB). It may also be thrown if there is a failure to modify an existing service record in the SDDB.

 

o    Constructors

·         public ServiceRegistrationException()

This constructor creates a ServiceRegistrationException without a detailed message.

·         public ServiceRegistrationException(java.lang.String msg)

This constructor creates a ServiceRegistrationException with a detailed message.

 

 

 

javax.obex

 

The JSR 82 supports the OBEX protocol also. OBEX stands for ‘Object Exchange Protocol’. OBEX protocol can be used over different transmission media like infra red, wired media and bluetooth radio etc. This package is defined independently of the javax.bluetooth package. OBEX has been developed by the Infrared Data Association (IrDA). You can visit http://www.irda.org for more information on OBEX. The main purpose of OBEX is to exchange objects between different devices. Plus it can also be scaled up for sending large objects in form of multiple OBEX packets.

 

// To check diagram

 

public interface Authenticator

What is it?

Authenticator provides a way to respond to authentication challenge and authentication response headers. In cases where a client or server receives an authentication challenge or authentication response header the methods onAuthenticationChallenge() or onAuthenticationResponse() will be called, respectively, by the implementation.

 

What are authentication challenges ?

In cases where a client or server receives an authentication challenge header the onAuthenticationChallenge() method will be invoked by the implementation. The application will then return the user name (if required) and password through a PasswordAuthentication object.

What are authentication responses ?

In cases where a client or server receives an authentication response header the onAuthenticationResponse() method is invoked by the API implementation with the user name received in the authentication response header. The application must determine the correct password. This onAuthenticationResponse() method should return this value.

 

o    Method

  • public passwordAuthentication onAuthenticationChallenge( java.lang.String decription, boolean isUserIdRequired, boolean isFullAccess)

This method returns a PasswordAuthentication object containing the user name and password used for authentication.

·         public byte[] onAuthenticationResponse(byte[] userName)

This method returns the correct password for the user name provided. In cases where null is returned then it means that authentication request has failed.

 

public interface ClientSession

What is it?

This interface provides methods for OBEX requests. The ways to define headers for any OBEX operation are also provided by this interface. The following are the OBEX operations:

·   CONNECT

·   SETPATH

·   PUT

·   GET

·   DISCONNECT

 

o    Method

·         public void setAuthenticator(Authenticator auth)

This method sets the Authenticator to use with this connection.

·         public HeaderSet createHeaderSet()

This method creates a javax.obex.HeaderSet object. This javax.obex.HeaderSet object can be used to define header values in a request.

·         public void setConnectionID(long id)

This method sets the connection ID header to include in the request packets.

 

·         public long getConnectionID()

This method returns the connection ID being used. It returns -1 if no connection ID is being used.

·         public HeaderSet connect(HeaderSet headers) throws java.io.IOException

This method returns the headers that were returned from the server.

·         public HeaderSet disconnect(HeaderSet headers) throws java.io.IOException

This method returns the headers returned by the server

·         public HeaderSet setPath(HeaderSet headers, boolean backup,                       boolean create) throws java.io.IOException

This method completes an OBEX SETPATH operation. This method returns the headers that were returned from the server.

·         public HeaderSet delete(HeaderSet headers) throws java.io.IOException

This method returns the headers returned by the server.

·         public Operation get(HeaderSet headers) throws java.io.IOException

This method performs the OBEX GET operation. This method returns the OBEX operation that will complete the GET request.

·         public Operation put(HeaderSet headers) throws java.io.IOException

This method does the OBEX PUT operation. This method returns the operation object used to complete the PUT request.

 

public interface HeaderSet

What is it?

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


Fields

  • public static final int COUNT

This field stands for the OBEX Count header.

·         public static final int NAME

This field stands for the OBEX Name header.

·         public static final int TYPE

This field stands for the OBEX Type header. This field allows a request to specify the type of the object. The object can be of type text, html, binary etc.

·         public static final int LENGTH

This field stands for the OBEX Length header. It means the length of the object in bytes.

·         public static final int TIME_ISO_8601

This field stands for the OBEX Time header using the ISO 8601 standards.

·         public static final int TIME_4_BYTE

This field stands for the OBEX Time header using the 4 byte representation.

·         public static final int DESCRIPTION

This field stands for the OBEX Description header.

·         public static final int TARGET

This field stands for the OBEX Target header.

·         public static final int HTTP

This field stands for the OBEX HTTP header.

·         public static final int WHO

This field stands for the OBEX Who header.

·         public static final int OBJECT_CLASS

This field stands for the OBEX Object Class header.

·         public static final int APPLICATION_PARAMETER

This field stands for the OBEX Application Parameter header.

 

o    Methods

  • public void setHeader(int headerID, java.lang.Object headerValue)

This method sets the value of the header identifier to the value provided.

·         public java.lang.Object getHeader(int headerID) throws java.io.IOException

This method returns the value of the header provided. It may return null if the header identifier specified is not part of this HeaderSet object.

·         public int[] getHeaderList() throws java.io.IOException

This method returns the array of headers that are set in this object. It may return null if no headers are available.

·         public void createAuthenticationChallenge(java.lang.String realm,                                         boolean userID, boolean access)

This method sets the authentication challenge header.

·         public int getResponseCode() throws java.io.IOException

This method returns the response code retrieved from the server.

 

public interface Operation

What is it?

This interface provides us with the ways to manipulate a single OBEX PUT or GET operation.

 

o    Methods

  • public void abort() throws java.io.IOException

This method sends an ABORT message to the server. When you will call this method the corresponding input and output streams will be closed along with this object.

·         public HeaderSet getReceivedHeaders() throws java.io.IOException

This method returns the headers received during this Operation.

·         public void sendHeaders(HeaderSet headers) throws java.io.IOException

This method specifies the headers that should be sent in the next OBEX message that is sent.

·         public int getResponseCode() throws java.io.IOException

This method returns the response code retrieved from the server.

 

public interface SessionNotifier

What is it?

This interface defines a connection notifier for server-side OBEX connections. When it is created and calls the acceptAndOpen() method it will begin listening for clients to create a connection at the transport layer.

 

o    Methods

·         public javax.microedition.io.Connection
acceptAndOpen(ServerRequestHandler handler) throws java.io.IOException

This method returns the connection to the client.

·         public javax.microedition.io.Connection acceptAndOpen(ServerRequestHandler handler,Authenticator auth)                                        throws java.io.IOException

This method returns the connection to the client.

 

public class PasswordAuthentication

What is it?

PasswordAuthentication class holds user name and password combinations.

 

o    Constructor

  • public PasswordAuthentication(byte[] userName,byte[] password)

This constructor creates a new PasswordAuthentication with the user name and password provided.

 

o    Methods

  • public byte[] getUserName()

This method returns the user name.

·         public byte[] getPassword()

This method returns the password.

 

public class ResponseCodes

What is it?

This class contains the list of valid response codes a server may send to a client.

 

o    Fields

·         public static final int OBEX_HTTP_OK

This field defines the OBEX SUCCESS response code.

·         public static final int OBEX_HTTP_CREATED

This field defines the OBEX CREATED response code.

·         public static final int OBEX_HTTP_ACCEPTED

This field defines the OBEX ACCEPTED response code.

·         public static final int OBEX_HTTP_NOT_AUTHORITATIVE

This field defines the OBEX NON-AUTHORITATIVE INFORMATION response code.

·         public static final int OBEX_HTTP_NO_CONTENT

This field defines the OBEX NO CONTENT response code.

·         public static final int OBEX_HTTP_RESET

This field defines the OBEX RESET CONTENT response code.

·         public static final int OBEX_HTTP_PARTIAL

This field defines the OBEX PARTIAL CONTENT response code.

·         public static final int OBEX_HTTP_MULT_CHOICE

This field defines the OBEX MULTIPLE_CHOICES response code.

·         public static final int OBEX_HTTP_MOVED_PERM

This field defines the OBEX MOVED PERMANENTLY response code.

·         public static final int OBEX_HTTP_MOVED_TEMP

This field defines the OBEX MOVED TEMPORARILY response code.

·         public static final int OBEX_HTTP_SEE_OTHER

This field defines the OBEX SEE OTHER response code.

·         public static final int OBEX_HTTP_NOT_MODIFIED

This field defines the OBEX NOT MODIFIED response code.

·         public static final int OBEX_HTTP_USE_PROXY

This field defines the OBEX USE PROXY response code.

·         public static final int OBEX_HTTP_BAD_REQUEST

This field defines the OBEX BAD REQUEST response code.

·         public static final int OBEX_HTTP_UNAUTHORIZED

This field defines the OBEX UNAUTHORIZED response code.

·         public static final int OBEX_HTTP_PAYMENT_REQUIRED

This field defines the OBEX PAYMENT REQUIRED response code.

·         public static final int OBEX_HTTP_FORBIDDEN

This field defines the OBEX FORBIDDEN response code.

·         public static final int OBEX_HTTP_NOT_FOUND

This field defines the OBEX NOT FOUND response code.

·         public static final int OBEX_HTTP_BAD_METHOD

This field defines the OBEX METHOD NOT ALLOWED response code.

·         public static final int OBEX_HTTP_NOT_ACCEPTABLE

This field defines the OBEX NOT ACCEPTABLE response code.

·         public static final int OBEX_HTTP_PROXY_AUTH

This field defines the OBEX PROXY AUTHENTICATION REQUIRED response code.

·         public static final int OBEX_HTTP_TIMEOUT

This field defines the OBEX REQUEST TIME OUT response code.

·         public static final int OBEX_HTTP_CONFLICT

This field defines the OBEX METHOD CONFLICT response code.

·         public static final int OBEX_HTTP_GONE

This field defines the OBEX METHOD GONE response code.

·         public static final int OBEX_HTTP_LENGTH_REQUIRED

This field defines the OBEX METHOD LENGTH REQUIRED response code.

·         public static final int OBEX_HTTP_PRECON_FAILED

This field defines the OBEX PRECONDITION FAILED response code.

·         public static final int OBEX_HTTP_ENTITY_TOO_LARGE

This field defines the OBEX REQUESTED ENTITY TOO LARGE response code.

·         public static final int OBEX_HTTP_REQ_TOO_LARGE

This field defines the OBEX REQUESTED URL TOO LARGE response code.

·         public static final int OBEX_HTTP_UNSUPPORTED_TYPE

This field defines the OBEX UNSUPPORTED MEDIA TYPE response code.

·         public static final int OBEX_HTTP_INTERNAL_ERROR

This field defines the OBEX INTERNAL SERVER ERROR response code.

·         public static final int OBEX_HTTP_NOT_IMPLEMENTED

This field defines the OBEX NOT IMPLEMENTED response code.

·         public static final int OBEX_HTTP_BAD_GATEWAY

This field defines the OBEX BAD GATEWAY response code.

·         public static final int OBEX_HTTP_UNAVAILABLE

This field defines the OBEX SERVICE UNAVAILABLE response code.

·         public static final int OBEX_HTTP_GATEWAY_TIMEOUT

This field defines the OBEX GATEWAY TIMEOUT response code.

·         public static final int OBEX_HTTP_VERSION

This field defines the OBEX HTTP VERSION NOT SUPPORTED response code.

·         public static final int OBEX_DATABASE_FULL

This field defines the OBEX DATABASE FULL response code.

·         public static final int OBEX_DATABASE_LOCKED

This field defines the OBEX DATABASE LOCKED response code.


public class ServerRequestHandler

What is it?

This class defines an event listener that will respond to OBEX requests made to the server.

 

o    Constructor

·         protected ServerRequestHandler()

This constructor creates a ServerRequestHandler.

 

o    Method

·         public final HeaderSet createHeaderSet()

This method returns the HeaderSet object to use in put and get operations.

·         public void setConnectionID(long id)

This method sets the connection ID header to include in the reply packets.

·         public long getConnectionID()

This method returns the connection id being used. It return -1 in case no connection ID is being used.

·         public int onConnect(HeaderSet request,HeaderSet reply)

This method returns a response code from those defined in ResponseCodes to the client. In case an invalid response code is provided the OBEX_HTTP_INTERNAL_ERROR response code will be used.

·         public void onDisconnect(HeaderSet request, HeaderSet reply)

This method is called when a DISCONNECT request is received.

·         public int onSetPath(HeaderSet request,HeaderSet reply,boolean backup,                     boolean create)

This method is called when a SETPATH request is received. This method returns a response code defined in ResponseCodes that will be returned to the client. In case an invalid response code is provided the OBEX_HTTP_INTERNAL_ERROR response code will be used.

·         public int onDelete(HeaderSet request,HeaderSet reply)

This method is called when a DELETE request is received. This method returns a response code from those defined in ResponseCodes to the client. In case an invalid response code is provided the OBEX_HTTP_INTERNAL_ERROR response code will be used.

·         public int onPut(Operation op)

This method is called when a PUT request is received. This method returns a response code from those defined in ResponseCodes to the client. In case an invalid response code is provided the OBEX_HTTP_INTERNAL_ERROR response code will be used.

·         public int onGet(Operation op)

This method is called when a GET request is received. This method returns a response code from those defined in ResponseCodes to the client. In case an invalid response code is provided the OBEX_HTTP_INTERNAL_ERROR response code will be used.

·         public void onAuthenticationFailure(byte[] userName)

This method is called when this object attempts to authenticate a client and the authentication request fails because the response digest in the authentication response header was wrong.
Comments