|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavax.bluetooth.DiscoveryAgent
public class DiscoveryAgent
The DiscoveryAgent
class provides methods to perform device
and service discovery. A local device must have only one
DiscoveryAgent
object. This object must be retrieved by a call
to getDiscoveryAgent()
on the LocalDevice
object.
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.
DiscoveryAgent
class also encapsulates the functionality
provided by the service discovery application profile. The class provides an
interface for an application to search and retrieve attributes for a
particular service. There are two ways to search for services. To search for
a service on a single device, the searchServices()
method
should be used. On the other hand, if you don't care which device a service
is on, the selectService()
method does a service search on a
set of remote devices.
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. |
boolean |
cancelServiceSearch(int transID)
Cancels the service search transaction that has the specified transaction ID. |
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. |
int |
searchServices(int[] attrSet,
UUID[] uuidSet,
RemoteDevice btDev,
DiscoveryListener discListener)
Searches for services on a remote Bluetooth device that have all the UUIDs specified in uuidSet . |
String |
selectService(UUID uuid,
int security,
boolean master)
Attempts to locate a service that contains uuid in the
ServiceClassIDList of its service record. |
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 |
---|
public static final int NOT_DISCOVERABLE
The value of NOT_DISCOVERABLE
is 0x00 (0).
public static final int GIAC
The value of GIAC
is 0x9E8B33 (10390323). This value is
defined in the Bluetooth Assigned Numbers document.
public static final int LIAC
The value of LIAC
is 0x9E8B00 (10390272). This value is
defined in the Bluetooth Assigned Numbers document.
public static final int CACHED
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).
retrieveDevices(int)
,
Constant Field Valuespublic static final int PREKNOWN
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).
retrieveDevices(int)
,
Constant Field ValuesMethod Detail |
---|
public RemoteDevice[] retrieveDevices(int option)
DiscoveryAgent.retrieveDevices()
method, if access to the
native list is available. If the native Bluetooth implementation does not
maintain the list of cached devices, or if the list is not readily
available, a Bluetooth API implementation MUST maintain a similar list
itself and return this list from the
DiscoveryAgent.retrieveDevices()
method when asked for
CACHED devices. The returned list in either case MUST contain no more
than one entry for an individual remote device.
option
- CACHED
if previously found devices should be
returned; PREKNOWN
if pre-known devices should be
returned
option
is CACHED
; an array of
devices that are pre-known devices if option
is
PREKNOWN
; null
if no devices meet the
criteria
IllegalArgumentException
- if option
is not CACHED
or
PREKNOWN
public boolean startInquiry(int accessCode, DiscoveryListener listener) throws BluetoothStateException
deviceDiscovered()
of the interface
DiscoveryListener
. The cancelInquiry()
method is called to stop the inquiry.
accessCode
- the type of inquiry to completelistener
- the event listener that will receive device discovery events
true
if the inquiry was started;
false
if the inquiry was not started because the
accessCode
is not supported
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 devicecancelInquiry(javax.bluetooth.DiscoveryListener)
,
GIAC
,
LIAC
public boolean cancelInquiry(DiscoveryListener listener)
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.
listener
- the listener that is receiving inquiry events
true
if the inquiry was canceled; otherwise
false
if the inquiry was not canceled or if the
inquiry was not started using listener
NullPointerException
- if listener
is null
public int searchServices(int[] attrSet, UUID[] uuidSet, RemoteDevice btDev, DiscoveryListener discListener) throws BluetoothStateException
uuidSet
. Once the service is found,
the attributes specified in attrSet
and the default
attributes are retrieved. The default attributes are ServiceRecordHandle
(0x0000), ServiceClassIDList (0x0001), ServiceRecordState (0x0002),
ServiceID (0x0003), and ProtocolDescriptorList (0x0004).If
attrSet
is null
then only the default
attributes will be retrieved. attrSet
does not have to be
sorted in increasing order, but must only contain values in the range [0 -
(216-1)].
attrSet
- indicates the attributes whose values will be retrieved on
services which have the UUIDs specified in
uuidSet
uuidSet
- the set of UUIDs that are being searched for; all services
returned will contain all the UUIDs specified herebtDev
- the remote Bluetooth device to search for services ondiscListener
- the object that will receive events when services are
discovered
BluetoothStateException
- if the number of concurrent service search transactions
exceeds the limit specified by the
bluetooth.sd.trans.max
property obtained
from the class LocalDevice
or the system is
unable to start one due to current conditions
IllegalArgumentException
- if attrSet
has an illegal service attribute
ID or exceeds the property
bluetooth.sd.attr.retrievable.max
defined
in the class LocalDevice
; if
attrSet
or uuidSet
is of
length 0; if attrSet
or
uuidSet
contains duplicates
NullPointerException
- if uuidSet
, btDev
, or
discListener
is null
; if an
element in uuidSet
array is
null
DiscoveryListener
public boolean cancelServiceSearch(int transID)
searchServices()
. A serviceSearchCompleted()
event with a discovery type of SERVICE_SEARCH_TERMINATED
will occur when this method is called. After receiving this event, no
further servicesDiscovered()
events will occur as a result
of this search.
transID
- the ID of the service search transaction to cancel; returned
by searchServices()
true
if the service search transaction is
terminated, else false
if the transID
does not represent an active service search transactionpublic String selectService(UUID uuid, int security, boolean master) throws BluetoothStateException
uuid
in the
ServiceClassIDList of its service record. This method will return a
string that may be used in Connector.open()
to establish a
connection to the service.
This method MUST return immediately after a suitable service (i.e. a
service that matches the specified UUID) is found. The Bluetooth inquiry
or the Bluetooth service discovery MUST NOT continue after a suitable
service is found. Note that if there are several suitable services in the
vicinity, different invocations of this method MAY produce different
results (i.e. return connection strings pointing at different services).
This is because Bluetooth inquiry and service discovery processes are
non-deterministic by their nature.
uuid
- the UUID to search for in the ServiceClassIDListsecurity
- specifies the security requirements for a connection to this
service; must be one of
ServiceRecord.NOAUTHENTICATE_NOENCRYPT
,
ServiceRecord.AUTHENTICATE_NOENCRYPT
, or
ServiceRecord.AUTHENTICATE_ENCRYPT
master
- determines if this client must be the master of the
connection; true
if the client must be the
master; false
if the client can be the master or
the slave
uuid
; or null
if no service could be
found with a UUID of uuid
in the ServiceClassIDList
BluetoothStateException
- if the Bluetooth system cannot start the request due to
the current state of the Bluetooth system
NullPointerException
- if uuid
is null
IllegalArgumentException
- if security
is not
ServiceRecord.NOAUTHENTICATE_NOENCRYPT
,
ServiceRecord.AUTHENTICATE_NOENCRYPT
, or
ServiceRecord.AUTHENTICATE_ENCRYPT
ServiceRecord.NOAUTHENTICATE_NOENCRYPT
,
ServiceRecord.AUTHENTICATE_NOENCRYPT
,
ServiceRecord.AUTHENTICATE_ENCRYPT
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |