javax.bluetooth
Class DiscoveryAgent

java.lang.Object
  extended by 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