Service Records

Each Bluetooth device supports one or more services, such as basic printing or generic telephony. Each service is identified by a UUIDsometimes a custom one, sometimes a standardized one. For example, the UUID for the basic printing service is 0x1122. (Normally, these are written using their short forms rather than the full 128-bit forms.)

Devices publish service records to tell other devices how to communicate with them. The Bluetooth specification lays out the exact structure and meaning of a service record in excruciating detail, but as usual Java encapsulates this in a much easier-to-use interface, javax.bluetooth.ServiceRecord.

A service record is essentially an indexed list of attributes. Attributes do not have names, only values. Given a ServiceRecord object, the getAttributeIDs( ) method returns an array of all the IDs of the attributes in the service record:

public int[] getAttributeIDs( )

You can then iterate through this list, passing each ID in turn to the getAttributeValue( ) method to retrieve each attribute:

public DataElement getAttributeValue(int attrID)

.6.1. The DataElement Class

Bluetooth attributes can have a variety of types, such as string, UUID, boolean, URL, sequence, null, and several signed and unsigned integer types. Java represents each of these as a DataElement object. These types, and the Java types they map to, are summarized in Table 25-4.

Most of these types do not map precisely onto Java primitive types, so the Java Bluetooth API encapsulates them all in the javax.bluetooth.DataElement class. This class has three methods to read the value out of a DataElement as a long, boolean, or Object:

public long getLong( ) public boolean getBoolean( ) public Object getValue( )

The getdataType( ) method tells you the Bluetooth type of the DataElement object:

public int getDataType( )

The return value is one of the named constants found in the third column of Table 25-4. Once you know the type of value to expect, you can use one of the three getter methods to return the value as the corresponding Java object or primitive type. If you try to get a mismatched typefor example, an INT_4 as a boolean or a URL as a longthese methods throw a ClassCastException.

Data elements can also wrap two list types. DATSEQ is an ordered sequence of values. DATALT is a list of values from which any one should be chosen. For either of these two types, getValue( ) returns a java.util.Enumeration. In this case, the getSize( ) method returns the number of items in that enumeration:

public int getSize( )

The addElement( ) method appends a new item of one of the 18 Bluetooth types to a DATSEQ or DATALT:

public void addElement(DataElement element)

The insertElementAt( ) method inserts a new data element into the specified position in a DATSEQ or DATALT:

public void insertElement(DataElement element, int position)

The removeElement( ) removes the first occurrence of the specified new data element from the DATSEQ or DATALT:

public void removeElement(DataElement element)

The same element may appear in the list more than once. These methods all throw a ClassCastException if you attempt to use them on a DataElement that does not represent a DATALT or DATSEQ.

.6.2. Finding Service Records

Like the remote devices themselves, the service records for a device are obtained via the DiscoveryAgent class. The simplest way to find a known service is to ask for it by UUID using the selectService( ) method:

public String selectService(UUID uuid, int security, boolean master) throws BluetoothStateException

This returns a connection string with the URL used to connect to the service, such as:

btspp://00904B2A88D6:1;authenticate=false;encrypt=false;master=false

The security argument is usually one of these three named constants, depending on what combination of authentication and encryption you desire:

• ServiceRecord.NOAUTHENTICATE_NOENCRYPT
• ServiceRecord.AUTHENTICATE_NOENCRYPT
• ServiceRecord.AUTHENTICATE_ENCRYPT

Finally, the master argument is TRue if the client insists on being the master of the connection and false if it can act as the master or the slave.

For example, suppose you want to find a basic printing service. The UUID for this is 0x1122, so this code fragment locates one if theres one to be found:

UUID printingID = new UUID(0x1122); String url = agent.selectService( printingID, ServiceRecord.AUTHENTICATE_NOENCRYPT, false);

If it can locate the requested service, it returns null.

What if theres more than one available device that supports the relevant service? In this case, the results are implementation dependent, but usually one or another is returned. (The Avetana stack actually throws a custom checked exception here, which is not conformant with the specification.)

The searchServices( ) method asks a specific device what services it supports:

public int searchServices(int[] attrSet, UUID[] uuidSet, RemoteDevice device, DiscoveryListener listener) throws BluetoothStateException

This approach is somewhat more reliable if you might have more than one device that offers a given service. The uuidSet argument contains the UUIDs for all the protocols you e looking for. Table 25-5 lists the UUIDs (in 2-byte form) of the services you can request. The attrSet argument contains the list of attributes (in addition to the default attributes) whose information should be provided. device is the specific device to query for services, and listener is the listener to tell about any services that are found. The method returns an ID you can use if you later need to cancel the search, which you can do with the following method:

public boolean cancelServiceSearch(int transID)

Table 25-6 lists some of the attributes you can request. The first fiveServiceRecordHandle, ServiceClassIDList, ServiceRecordState, ServiceID, and ProtocolDescriptorListare always returned. The others need to be specifically requested.

Some of these IDs may vary depending on the profile. For instance, 0x0301 means "external network" in the Cordless Telephony Profile but "supported data stores" in the Synchronization Profile.

.6.3. The ServiceRecord Interface

The ServiceRecord interface provides a number of setter and getter methods for inspecting and updating service records. By far the most important thing youll need from a ServiceRecord object is the connection string. This is the URL youll use to open a connection to the device:

public String getConnectionURL(int requiredSecurity, boolean mustBeMaster)

The security argument is one of these three named constants, depending on what combination of authentication and encryption you desire:

• ServiceRecord.NOAUTHENTICATE_NOENCRYPT
• ServiceRecord.AUTHENTICATE_NOENCRYPT
• ServiceRecord.AUTHENTICATE_ENCRYPT

The master argument is true if the client insists on being the master of the connection or false if it can act as the master or the slave.

The value you get back is a complete GCF Bluetooth URL, such as:

btspp://00904B2A88D6:1;authenticate=false;encrypt=false;master=false

Once you have the URL, you can talk to the device using the methods of the last chapter.

You can add or remove parameters from the URL using substring operations. For instance, you could change the above URL to:

btspp://00904B2A88D6:1;authenticate=false;encrypt=false;master=true

However, getConnectionURL() is the only way to get the necessary protocol, address, and channel for the device.

The getAttributeIDs( ) method returns an array of the IDs of all the attributes this service possesses:

public int[] getAttributeIDs( )

You can retrieve one of these attributes with the getAttributeValue( ) method:

public DataElement getAttributeValue(int attrID)

This returns a DataElement object that wraps the Bluetooth object in a Java class, as described in Table 25-4.

Example 25-4 is a program that searches for all L2CAP (UUID 0x0100) services. When it finds one, it lists its URL. Notice that you have to explicitly start a search for each devices services. That is, Example 25-4 first starts a search for devices as previously seen in Example 25-3. When a device is found, it searches that device for services using searchServices( ). For each service, it requests all attributes that might be present.

Example 25-4. Finding all L2CAP services

Most other Bluetooth protocols are built on top of L2CAP, so this program will probably find all the accessible devices. Heres what I got when I ran it on my system after making sure all devices were discoverable:

Found Earthmate Blue Logger GPS at 00904B2A88D6 Searching 00904B2A88D6 for services Service Search 1 started Found service btspp://00904B2A88D6:1;authenticate=false;encrypt=false;master=false Service search 1 complete Found elharos mouse at 000A95095A59 Searching 000A95095A59 for services Service Search 2 started Found service btl2cap://000A95095A59:11;authenticate=false;encrypt=false;master=false Found service btl2cap://000A95095A59:1;authenticate=false;encrypt=false;master=false Service search 2 complete Found WACOM Pen Tablet at 0013C2000D23 Searching 0013C2000D23 for services Service Search 3 started Found service btl2cap://0013C2000D23:11;authenticate=false;encrypt=false;master=false Found service btl2cap://0013C2000D23:1;authenticate=false;encrypt=false;master=false Service search 3 complete Device search 0 complete

You can see there are three devices on this system: a GPS unit, a pen tablet, and a mouse. The GPS unit has a single serial port (RFCOMM) connection, which well make use of in the next section. The mouse and the graphics tablet each have two L2CAP URLs, one for the control channel and one for the interrupt channel. This is the common pattern for HID devices.

More often, youll want to look for a particular service with a particular UUID. This normally happens asynchronously, but theres a maximum number of searches you can run at once. (The exact number varies from device to device but can be read from the bluetooth.sd.trans.max property.) Consequently, you need to keep track of the searches and cancel the ongoing searches when youve found what you e looking for. Example 25-5 demonstrates. The static BluetoothServiceFinder.getConnectionURL( ) method finds a service with a specified UUID. Well use this class again shortly.

Example 25-5. A utility class to find a specified service