Client applications use the JABWT discovery APIs to seek out nearby devices and services. The DiscoveryAgent class supports discovery of both devices and services. Client applications wanting to be notified when devices and services are discovered must implement and register the interface DiscoveryListener , which defines callbacks for device- and service-discovery notification.

The relationship between a Bluetooth client application and the DiscoveryAgent is typically one-to-one:

Figure 5: The DiscoveryAgent Class and DiscoveryListener Interface

APIs for Device Discovery

You use the DiscoveryAgent 's device – discovery methods to initiate and cancel device discovery:

The Bluetooth Discovery Agent invokes the DiscoveryListener 's device – discovery callback methods at different points in the inquiry phase:

The state diagram in Figure 6 illustrates the device-discovery states reached as a result of DiscoveryListener callbacks:

Figure 6: Device-Discovery State Diagram

Device discovery begins with a call to startInquiry() . As the inquiry progresses, the Bluetooth Discovery Agent invokes the callback methods deviceDiscovered() and inquiryCompleted() as appropriate.

APIs for Service Discovery

You use the DiscoveryAgent 's service-discovery methods to initiate and cancel service discovery:

The Bluetooth Discovery Agent invokes DiscoveryListener service-discovery callback methods at different points in the service-discovery phase:

Figure 7 illustrates the service discovery states reached as a result of DiscoveryListener callbacks:

Figure 7: Service-Discovery State Diagram

Service discovery begins with a call to searchServices() . As the service search progresses, the Bluetooth Discovery Agent calls back servicesDiscovered() and serviceSearchCompleted() as appropriate.

In addition to DiscoveryAgent and DiscoveryListener , you also use the classes UUID , ServiceRecord , and DataElement when discovering services.

The UUID Class

In Bluetooth, each service and service attribute is uniquely identified by a Universally Unique Identifier (UUID). As its name suggests, each such identifier is guaranteed to be unique across all time and space. The UUID class can represent short (16- or 32-bit) and long (128-bit) UUIDs. It provides constructors to create a UUID from a String or from a 16- or 32-bit value, a method to compare two UUIDs (if both are 128-bit), and a method to covert a UUID into a String . UUID instances are immutable, and only services identified by UUIDs are discoverable.

You can generate a UUID value with a command: uuidgen -t if you're running Linux, uuidgen if you're running Windows. The UUID will look something like this: 2d266186-01fb-47c2-8d9f-10b8ec891363 . When using the generated UUID to build a UUID object, you remove the hyphens.

The SDDB and the ServiceRecord Interface

At the center of service discovery are the Service Discovery Database (SDDB) and the Service Discovery Protocol (SDP). The SDDB is a database maintained by the Bluetooth implementation that contains service records, which represent services that are available to clients. The SDP is transparent to applications based on JABWT; it suffices to say that the SDP is used for service discovery. To retrieve service records an SDP client on the local device makes requests to an SDP server on a remote device.

Figure 8: The SDDB

Each service record is represented by an instance of ServiceRecord . This record contains attributes that describe the service in detail. The class provides several useful methods:

Figure 9 shows you the relationships between Bluetooth local and remote devices, the SDDB, and service records:

Figure 9: Discovering Services Using RemoteDevice SDDB, and ServiceRecord

To make a service available to clients, a server application creates a service record by creating a connection notifier, then inserts the record into its SDDB by invoking the connection notifier's acceptAndWait() method. Server applications can retrieve the service record and update it as appropriate, and client applications querying the remote SDDB for available services will find the service record there.

The DataElement Class

A service can have many attributes, some mandatory, others optional. A service attribute is represented by a DataElement object, which provides methods to set and get attribute values.

Mandatory attributes are set automatically when a service is registered. These include ServiceRecordHandle , ServiceClassIDList , ServiceRecordState , ServiceID , and ProtocolDescriptorList .

You can set optional attributes if you like. There are many, but three are of special interest: ServiceName , ServiceDescription , and ProviderName .

For more information about these attributes, please see the JABWT documentation or the Bluetooth specification.

Three main classes support device management:

The LocalDevice Class

The class LocalDevice represents the local Bluetooth device. The relationship between the Bluetooth application and LocalDevice is typically one-to-one:

Figure 10: The LocalDevice Class

LocalDevice provides methods to retrieve information about the local device, and to get access to the Bluetooth manager :

Properties you can retrieve by calling getProperty() include, among others:

You can learn more about Bluetooth properties in the Javadoc or the specification.

The RemoteDevice Class

An instance of RemoteDevice represents a remote Bluetooth device. Before a Bluetooth client application can consume services, it must discover remote devices by initiating a device inquiry. Typically the relationship between the Bluetooth application and RemoteDevice is one-to-many:

Figure 11: The RemoteDevice Class

Of the methods RemoteDevice provides, some are similar to the ones provided by LocalDevice :

The DeviceClass Class

A DeviceClass object represents a device's class of device (CoD), for example a printer or a phone. A CoD consists of a major class, a minor class, and service types or classes. DeviceClass provides these methods:

When a device is discovered, its class is discovered as well; when the Discovery Agent invokes deviceDiscovered() , one of the arguments is the DeviceClass . You can find the local device's CoD by calling its getDeviceClass() method.

JABWT connections are based on the Logical Link Control and Adaptation Layer Protocol. L2CAP is a low-level protocol for managing data packets up to 64 kilobytes long. L2CAP handles details such as message segmentation and reassembly (SAR), and connection multiplexing. In addition, the Serial Port Profile (SPP) provides RFCOMM, a serial emulation protocol over L2CAP.

L2CAP and RFCOMM connections are based on the Generic Connection Framework (GCF), a straightforward hierarchy of interfaces and classes to create connections and perform I/O. JABWT extends GCF by adding L2CAP and RFCOMM support through the L2CAPConnection and StreamConnection types respectively. While L2CAPConnection was introduced with JSR 82, StreamConnection was defined as part of the original javax.microedition.io GCF that was developed to rely on CLDC. Note that JABWT L2CAPConnection supports only connection-oriented L2CAP connections. Figure 12 illustrates the interfaces used in GCF-based communications over Bluetooth networks:

Figure 12: The Generic Connection Framework and Bluetooth Connection Types

The hierarchy defines L2CAP and Stream connections and connection notifiers. A connection defines a connection endpoint, while a connection notifier implements server behavior; it waits for and accepts incoming client connections.

Handling L2CAP connections is more involved than handling stream connections. With L2CAP, developers must deal with maximum message sizes (maximum transmission unit, or MTU), and with breaking up and reassembling long messages. These complexities are hidden from the developer when using stream connections, making them preferable for Bluetooth connectivity.

As with all GCF connection types, you create Bluetooth connections by calling the GCF connection factory javax.microedition.io.Connector . The connection URL scheme passed to Connector() determines the connection type to create: