com.appliancestudio.jbluez
Class BlueZ

java.lang.Object
  |
  +--com.appliancestudio.jbluez.BlueZ

public class BlueZ

extends java.lang.Object

This class provides the methods to access the underlying BlueZ functions. All of the native methods defined in this class are implemented, via the Java Native Interface (JNI) in C. See the bluez.c file and associated comments for full details. If you wish to incorporate Bluetooth functionality (using the BlueZ stack) into your Java application, create a new instance of this BlueZ class. Calling the methods provided here will call the functions defined by the BlueZ libraries, primarily those defined in the files hci.c and hci_lib.h.

Version:

1.0

Author:

Edward Kay, ed.kay@appliancestudio.com

Constructor Summary

BlueZ()

Method Summary

void	hciCloseDevice(int dd) Close the HCI device.
int	hciCreateConnection(int dd, com.appliancestudio.jbluez.BTAddress bdaddr, int ptype, int clkoffset, short rswitch, int timeOut) Create an HCI connection.
int	hciCreateConnection(int dd, java.lang.String bdaddr, int ptype, int clkoffset, short rswitch, int timeOut) Create an HCI connection.
com.appliancestudio.jbluez.BTAddress	hciDevBTAddress(int hciDevID) Gets the Bluetooth device address for a specified local HCI device.
int	hciDeviceID(com.appliancestudio.jbluez.BTAddress bdaddr) Gets the device ID for a specified local HCI device.
int	hciDeviceID(java.lang.String bdaddr) Gets the device ID for a specified local HCI device.
com.appliancestudio.jbluez.HCIDeviceInfo	hciDevInfo(int hciDevID) Gets the device information for a specified local HCI device.
void	hciDisconnect(int dd, int handle, short reason, int timeOut) Disconnect an established HCI connection.
com.appliancestudio.jbluez.InquiryInfo	hciInquiry(int hciDevID) Perform an HCI inquiry to discover remote Bluetooth devices.
com.appliancestudio.jbluez.InquiryInfo	hciInquiry(int hciDevID, int len, int max_num_rsp, long flags) Perform an HCI inquiry to discover remote Bluetooth devices.
java.lang.String	hciLocalName(int dd) Get the name of a local device.
java.lang.String	hciLocalName(int dd, int timeOut) Get the name of a local device.
int	hciOpenDevice(int hciDevID) Opens the HCI device.
com.appliancestudio.jbluez.HCIVersion	hciReadLocalVersion(int dd, int timeOut) Get the version information of a local Bluetooth device.
com.appliancestudio.jbluez.HCIFeatures	hciReadRemoteFeatures(int dd, int handle, int timeOut) Get the features of a remote Bluetooth device.
com.appliancestudio.jbluez.HCIVersion	hciReadRemoteVersion(int dd, int handle, int timeOut) Get the version information of a remote Bluetooth device.
java.lang.String	hciRemoteName(int dd, com.appliancestudio.jbluez.BTAddress bdaddr) Get the name of a remote device, as specified by its Bluetooth device address.
java.lang.String	hciRemoteName(int dd, com.appliancestudio.jbluez.BTAddress bdaddr, int timeOut) Get the name of a remote device, as specified by its Bluetooth device address.
java.lang.String	hciRemoteName(int dd, java.lang.String bdaddr) Get the name of a remote device, as specified by its Bluetooth device address.
java.lang.String	hciRemoteName(int dd, java.lang.String bdaddr, int timeOut) Get the name of a remote device, as specified by its Bluetooth device address.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BlueZ

public BlueZ()

Method Detail

hciOpenDevice

public int hciOpenDevice(int hciDevID)
                  throws BlueZException

Opens the HCI device.

Parameters:

hciDevID - The local HCI device ID (see the hciconfig tool provided by BlueZ for further information).

Returns:

A device descriptor (often named dd) for the HCI device.

Throws:

BlueZException - Unable to open the HCI device.

hciCloseDevice

public void hciCloseDevice(int dd)

Close the HCI device.

Parameters:

dd - The HCI device descriptor (as returned from hciOpenDevice)

hciCreateConnection

public int hciCreateConnection(int dd,
                               java.lang.String bdaddr,
                               int ptype,
                               int clkoffset,
                               short rswitch,
                               int timeOut)
                        throws BlueZException

Create an HCI connection. Note that this requires higher than normal privileges, and so will often only work when executed as root. If you call this method with insufficient privileges, an exception will be thrown with the message text "Unable to create connection". See HCI_Create_Connection in the Bluetooth Specification for further details of the various arguments.

Parameters:

dd - HCI device descriptor.

bdaddr - Bluetooth address String in the form "00:12:34:56:78:9A".

ptype - Packet type, for example 0x0008 for DM1.

clkoffset - Clock offset (usually set to 0).

rswitch - Role switch (usually set to 0 or 1).

timeOut - Timeout, in milliseconds.

Returns:

A handle for the connection.

Throws:

BlueZException - Unable to create the connection.

hciCreateConnection

public int hciCreateConnection(int dd,
                               com.appliancestudio.jbluez.BTAddress bdaddr,
                               int ptype,
                               int clkoffset,
                               short rswitch,
                               int timeOut)
                        throws BlueZException

Create an HCI connection. Note that this requires higher than normal privileges, and so will often only work when executed as root. If you call this method with insufficient privileges, an exception will be thrown with the message text "Unable to create connection". See HCI_Create_Connection in the Bluetooth Specification for further details of the various arguments.

Parameters:

dd - HCI device descriptor.

bdaddr - Bluetooth address as a BTAddress object.

ptype - Packet type, for example 0x0008 for DM1.

clkoffset - Clock offset (usually set to 0).

rswitch - Role switch (usually set to 0 or 1).

timeOut - Timeout, in milliseconds.

Returns:

A handle for the connection.

Throws:

BlueZException - Unable to create the connection.

hciDisconnect

public void hciDisconnect(int dd,
                          int handle,
                          short reason,
                          int timeOut)
                   throws BlueZException

Disconnect an established HCI connection. See HCI_Disconnect in the Bluetooth Specification for further details of the various arguments.

Parameters:

dd - HCI device descriptor.

handle - HCI connection handle.

reason - Code detailing reason for disconnection (often 0x13).

timeOut - Timeout, in milliseconds.

Throws:

BlueZException - Unable to disconnect.

hciInquiry

public com.appliancestudio.jbluez.InquiryInfo hciInquiry(int hciDevID,
                                                         int len,
                                                         int max_num_rsp,
                                                         long flags)
                                                  throws BlueZException

Perform an HCI inquiry to discover remote Bluetooth devices. See HCI_Inquiry in the Bluetooth Specification for further details of the various arguments.

Parameters:

hciDevID - The local HCI device ID (see the hciconfig tool provided by BlueZ for further information).

len - Maximum amount of time before inquiry is halted. Time = len x 1.28 secs.

max_num_rsp - Maximum number of responses allowed before inquiry is halted. For an unlimited number, set to 0.

flags - Additional flags. See BlueZ documentation and source code for details.

Returns:

An InquiryInfo object containing the results of the inquiry.

Throws:

BlueZException - If the inquiry failed.

See Also:

hciInquiry(int hciDevID)

hciInquiry

public com.appliancestudio.jbluez.InquiryInfo hciInquiry(int hciDevID)
                                                  throws BlueZException

Perform an HCI inquiry to discover remote Bluetooth devices. This is the same as hciInquiry(int hciDevID, int len, int max_num_rsp, long flags), except that the len, max_num_rsp and flags fields are preset to 'default' values. These values are 8, 10 and 0, respectively.

Parameters:

hciDevID - The local HCI device ID (see the hciconfig tool provided by BlueZ for further information)

Returns:

An InquiryInfo object containing the results of the inquiry.

Throws:

BlueZException - If the inquiry failed.

hciDevInfo

public com.appliancestudio.jbluez.HCIDeviceInfo hciDevInfo(int hciDevID)
                                                    throws BlueZException

Gets the device information for a specified local HCI device.

Parameters:

hciDevID - The local HCI device ID (see the hciconfig tool provided by BlueZ for further information)

Returns:

An HCIDeviceInfo object representing the local HCI device information.

Throws:

BlueZException - If unable to get the device information.

hciDevBTAddress

public com.appliancestudio.jbluez.BTAddress hciDevBTAddress(int hciDevID)
                                                     throws BlueZException

Gets the Bluetooth device address for a specified local HCI device.

Parameters:

hciDevID - The local HCI device ID (see the hciconfig tool provided by BlueZ for further information)

Returns:

A BTAddress object representing the Bluetooth device address.

Throws:

BlueZException - If unable to get the Bluetooth device address.

hciDeviceID

public int hciDeviceID(java.lang.String bdaddr)
                throws BlueZException

Gets the device ID for a specified local HCI device.

Parameters:

bdaddr - Bluetooth address String in the form "00:12:34:56:78:9A".

Returns:

The device ID for the local device.

Throws:

BlueZException - If unable to get the device ID.

hciDeviceID

public int hciDeviceID(com.appliancestudio.jbluez.BTAddress bdaddr)
                throws BlueZException

Gets the device ID for a specified local HCI device.

Parameters:

bdaddr - Bluetooth address as a BTAddress object.

Returns:

The device ID for the local device.

Throws:

BlueZException - If unable to get the device ID.

hciLocalName

public java.lang.String hciLocalName(int dd,
                                     int timeOut)
                              throws BlueZException

Get the name of a local device. The device must be opened using hciOpenDevice before calling this method.

Parameters:

dd - HCI device descriptor.

timeOut - Timeout, in milliseconds.

Returns:

A String containing the name of the specified local device.

Throws:

BlueZException - If unable to get the local device name.

hciLocalName

public java.lang.String hciLocalName(int dd)
                              throws BlueZException

Get the name of a local device. The device must be opened using hciOpenDevice before calling this method. This is the same as hciLocalName(int dd, int timeOut) with the timeOut argument set to 10000 (i.e. 10 seconds).

Parameters:

dd - HCI device descriptor.

Returns:

A String containing the name of the specified local device.

Throws:

BlueZException - If unable to get the local device name.

hciRemoteName

public java.lang.String hciRemoteName(int dd,
                                      java.lang.String bdaddr,
                                      int timeOut)
                               throws BlueZException

Get the name of a remote device, as specified by its Bluetooth device address. The local device must be opened using hciOpenDevice before calling this method.

Parameters:

dd - HCI device descriptor.

bdaddr - Bluetooth address String in the form "00:12:34:56:78:9A".

timeOut - Timeout, in milliseconds.

Returns:

A String containing the name of the specified remote device.

Throws:

BlueZException - If unable to get the remote device name.

hciRemoteName

public java.lang.String hciRemoteName(int dd,
                                      java.lang.String bdaddr)
                               throws BlueZException

Get the name of a remote device, as specified by its Bluetooth device address. The local device must be opened using hciOpenDevice before calling this method. This is the same as hciRemoteName(int dd, String bdaddr, int timeOut) with the timeOut argument set to 10000 (i.e. 10 seconds).

Parameters:

dd - HCI device descriptor.

bdaddr - Bluetooth address String in the form "00:12:34:56:78:9A".

Returns:

A String containing the name of the specified remote device.

Throws:

BlueZException - If unable to get the remote device name.

hciRemoteName

public java.lang.String hciRemoteName(int dd,
                                      com.appliancestudio.jbluez.BTAddress bdaddr,
                                      int timeOut)
                               throws BlueZException

Get the name of a remote device, as specified by its Bluetooth device address. The local device must be opened using hciOpenDevice before calling this method.

Parameters:

dd - HCI device descriptor.

bdaddr - Bluetooth address as a BTAddress object.

timeOut - Timeout, in milliseconds.

Returns:

A String containing the name of the specified remote device.

Throws:

BlueZException - If unable to get the remote device name.

hciRemoteName

public java.lang.String hciRemoteName(int dd,
                                      com.appliancestudio.jbluez.BTAddress bdaddr)
                               throws BlueZException

Get the name of a remote device, as specified by its Bluetooth device address. The local device must be opened using hciOpenDevice before calling this method. This is the same as hciRemoteName(int dd, BTAddress bdaddr, int timeOut) with the timeOut argument set to 10000 (i.e. 10 seconds).

Parameters:

dd - HCI device descriptor.

bdaddr - Bluetooth address as a BTAddress object.

Returns:

A String containing the name of the specified remote device.

Throws:

BlueZException - If unable to get the remote device name.

hciReadRemoteFeatures

public com.appliancestudio.jbluez.HCIFeatures hciReadRemoteFeatures(int dd,
                                                                    int handle,
                                                                    int timeOut)
                                                             throws BlueZException

Get the features of a remote Bluetooth device. In order to call this method, a local device must have been opened using hciOpenDevice and an HCI connection created to the remote device using hciCreateConnection.

Parameters:

dd - HCI device descriptor.

handle - HCI connection handle.

timeOut - Timeout, in milliseconds.

Returns:

The remote features as an HCIFeatures object.

Throws:

BlueZException - If unable to read the features of the remote device.

hciReadRemoteVersion

public com.appliancestudio.jbluez.HCIVersion hciReadRemoteVersion(int dd,
                                                                  int handle,
                                                                  int timeOut)
                                                           throws BlueZException

Get the version information of a remote Bluetooth device. In order to call this method, a local device must have been opened using hciOpenDevice and an HCI connection created to the remote device using hciCreateConnection.

Parameters:

dd - HCI device descriptor.

handle - HCI connection handle.

timeOut - Timeout, in milliseconds.

Returns:

An HCIVersion object representing the remote version information.

Throws:

BlueZException - If unable to read the remote version information.

hciReadLocalVersion

public com.appliancestudio.jbluez.HCIVersion hciReadLocalVersion(int dd,
                                                                 int timeOut)
                                                          throws BlueZException

Get the version information of a local Bluetooth device. In order to call this method, the local device must have been opened using hciOpenDevice.

Parameters:

dd - HCI device descriptor.

timeOut - Timeout, in milliseconds.

Returns:

An HCIVersion object representing the local version information.

Throws:

BlueZException - If unable to read the features of the local device.