javax.bluetooth
Class DiscoveryAgent

java.lang.Object
  javax.bluetooth.DiscoveryAgent

public class DiscoveryAgent
extends Object

The DiscoveryAgent class provides methods to perform device discovery (but not service discovery in leJOS NXJ). A local device must have only one DiscoveryAgent object. This object must be retrieved by a call to getDiscoveryAgent() on the LocalDevice object. The three service methods normally in the DiscoveryAgent class such as searchServices() are not included because the Lego NXT brick only allows one service: SPP (Serial Port Profile). It would waste memory to implement the service methods considering they are not really functional.

Device Discovery

There are two ways to discover devices. First, an application may use startInquiry() to start an inquiry to find devices in proximity to the local device. Discovered devices are returned via the deviceDiscovered() method of the interface DiscoveryListener. The second way to discover devices is via the retrieveDevices() method. This method will return devices that have been discovered via a previous inquiry or devices that are classified as pre-known. (Pre-known devices are those devices that are defined in the Bluetooth Control Center as devices this device frequently contacts.) The retrieveDevices() method does not perform an inquiry, but provides a quick way to get a list of devices that may be in the area. WARNING: If a device is found that has not yet been paired with the NXT brick, the name field of RemoteDevice will be blank. Make sure to pair your devices through the leJOS NXJ Bluetooth menu on your NXT.

Version:

1.0 January 17, 2009

Author:

BB

Field Summary

static int	CACHED Used with the retrieveDevices() method to return those devices that were found via a previous inquiry.
static int	GIAC The inquiry access code for General/Unlimited Inquiry Access Code (GIAC).
static int	LIAC The inquiry access code for Limited Dedicated Inquiry Access Code (LIAC).
static int	NOT_DISCOVERABLE Takes the device out of discoverable mode.
static int	PREKNOWN Used with the retrieveDevices() method to return those devices that are defined to be pre-known devices.

Method Summary

boolean	cancelInquiry(DiscoveryListener listener) Removes the device from inquiry mode.
RemoteDevice[]	retrieveDevices(int option) Returns an array of Bluetooth devices that have either been found by the local device during previous inquiry requests or been specified as a pre-known device depending on the argument.
boolean	startInquiry(int accessCode, DiscoveryListener listener) Places the device into inquiry mode.

Methods inherited from class java.lang.Object

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

Field Detail

NOT_DISCOVERABLE

public static final int NOT_DISCOVERABLE

Takes the device out of discoverable mode.

The value of NOT_DISCOVERABLE is 0x00 (0).

See Also:

Constant Field Values

GIAC

public static final int GIAC

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

The value of GIAC is 0x9E8B33 (10390323). This value is defined in the Bluetooth Assigned Numbers document.

See Also:

startInquiry(int, javax.bluetooth.DiscoveryListener), Constant Field Values

LIAC

public static final int LIAC

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

The value of LIAC is 0x9E8B00 (10390272). This value is defined in the Bluetooth Assigned Numbers document.

See Also:

startInquiry(int, javax.bluetooth.DiscoveryListener), Constant Field Values

CACHED

public static final int CACHED

Used with the retrieveDevices() method to return those devices that were found via a previous inquiry. If no inquiries have been started, this will cause the method to return null.

The value of CACHED is 0x00 (0).

See Also:

retrieveDevices(int), Constant Field Values

PREKNOWN

public static final int PREKNOWN

Used with the retrieveDevices() method to return those devices that are defined to be pre-known devices. Pre-known devices are specified in the BCC. These are devices that are specified by the user as devices with which the local device will frequently communicate.

The value of PREKNOWN is 0x01 (1).

See Also:

retrieveDevices(int), Constant Field Values

Method Detail

retrieveDevices

public RemoteDevice[] retrieveDevices(int option)

Returns an array of Bluetooth devices that have either been found by the local device during previous inquiry requests or been specified as a pre-known device depending on the argument. The list of previously found devices is maintained by the implementation of this API. (In other words, maintenance of the list of previously found devices is an implementation detail.) A device can be set as a pre-known device in the Bluetooth Control Center.

Parameters:

option - CACHED if previously found devices should be returned; PREKNOWN if pre-known devices should be returned

Returns:

an array containing the Bluetooth devices that were previously found if option is CACHED; an array of devices that are pre-known devices if option is PREKNOWN; null if no devices meet the criteria

Throws:

IllegalArgumentException - if option is not CACHED or PREKNOWN

startInquiry

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

Places the device into inquiry mode. The length of the inquiry is implementation dependent. This method will search for devices with the specified inquiry access code. Devices that responded to the inquiry are returned to the application via the method deviceDiscovered() of the interface DiscoveryListener. The cancelInquiry() method is called to stop the inquiry. NOTE: If a device is found that has not yet been paired with the NXT brick, the name field of RemoteDevice will be blank. Make sure to pair your devices through the leJOS NXJ Bluetooth menu on your NXT.

Parameters:

accessCode - the type of inquiry to complete

listener - the event listener that will receive device discovery events

Returns:

true if the inquiry was started; false if the inquiry was not started because the accessCode is not supported

Throws:

IllegalArgumentException - if the access code provided is not LIAC, GIAC, or in the range 0x9E8B00 to 0x9E8B3F

NullPointerException - if listener is null

BluetoothStateException - if the Bluetooth device does not allow an inquiry to be started due to other operations that are being performed by the device

See Also:

cancelInquiry(javax.bluetooth.DiscoveryListener), GIAC, LIAC

cancelInquiry

public boolean cancelInquiry(DiscoveryListener listener)

Removes the device from inquiry mode.

An inquiryCompleted() event will occur with a type of INQUIRY_TERMINATED as a result of calling this method. After receiving this event, no further deviceDiscovered() events will occur as a result of this inquiry.

This method will only cancel the inquiry if the listener provided is the listener that started the inquiry.

Parameters:

listener - the listener that is receiving inquiry events

Returns:

true if the inquiry was canceled; otherwise false if the inquiry was not canceled or if the inquiry was not started using listener

Throws:

NullPointerException - if listener is null