javax.bluetooth
Interface ServiceRecord


public interface ServiceRecord

The ServiceRecord interface describes characteristics of a Bluetooth service. A ServiceRecord contains a set of service attributes, where each service attribute is an (ID, value) pair. A Bluetooth attribute ID is a 16-bit unsigned integer, and an attribute value is a DataElement.

The structure and use of service records is specified by the Bluetooth specification in the Service Discovery Protocol (SDP) document. Most of the Bluetooth Profile specifications also describe the structure of the service records used by the Bluetooth services that conform to the profile.

An SDP Server maintains a Service Discovery Database (SDDB) of service records that describe the services on the local device. Remote SDP clients can use the SDP to query an SDP server for any service records of interest. A service record provides sufficient information to allow an SDP client to connect to the Bluetooth service on the SDP server's device.

ServiceRecords are made available to a client application via an argument of the servicesDiscovered method of the DiscoveryListener interface. ServiceRecords are available to server applications via the method getRecord() on LocalDevice.

There might be many service attributes in a service record, and the SDP protocol makes it possible to specify the subset of the service attributes that an SDP client wants to retrieve from a remote service record. The ServiceRecord interface treats certain service attribute IDs as default IDs, and, if present, these service attributes are automatically retrieved during service searches.

The Bluetooth Assigned Numbers document ( http://www.bluetooth.org) defines a large number of service attribute IDs. Here is a subset of the most common service attribute IDs and their types.
Attribute NameAttribute ID Attribute Value Type
ServiceRecordHandle0x0000 32-bit unsigned integer
ServiceClassIDList0x0001 DATSEQ of UUIDs
ServiceRecordState0x0002 32-bit unsigned integer
ServiceID0x0003 UUID
ProtocolDescriptorList0x0004 DATSEQ of DATSEQ of UUID and optional parameters
BrowseGroupList0x0005 DATSEQ of UUIDs
LanguageBasedAttributeIDList0x0006 DATSEQ of DATSEQ triples
ServiceInfoTimeToLive0x0007 32-bit unsigned integer
ServiceAvailability0x0008 8-bit unsigned integer
BluetoothProfileDescriptorList0x0009 DATSEQ of DATSEQ pairs
DocumentationURL0x000A URL
ClientExecutableURL0x000BURL
IconURL0x000CURL
VersionNumberList0x0200 DATSEQ of 16-bit unsigned integers
ServiceDatabaseState0x0201 32-bit unsigned integer

The following table lists the common string-valued attribute ID offsets used in a ServiceRecord. These offsets must be added to a base value to obtain the actual service ID. (For more information, see the Service Discovery Protocol Specification located in the Bluetooth Core Specification at http://www.bluetooth.com).
Attribute NameAttribute ID Offset Attribute Value Type
ServiceName0x0000String
ServiceDescription0x0001String
ProviderName0x0002String

Since:
JDE 4.2.1

Field Summary
static int AUTHENTICATE_ENCRYPT
          Authentication and encryption are required for connections to this service.
static int AUTHENTICATE_NOENCRYPT
          Authentication is required for connections to this service, but not encryption.
static int NOAUTHENTICATE_NOENCRYPT
          Authentication and encryption are not needed on a connection to this service.
 
Method Summary
 int[] getAttributeIDs()
          Returns the service attribute IDs whose value could be retrieved by a call to getAttributeValue().
 DataElement getAttributeValue(int attrID)
          Returns the value of the service attribute ID provided it is present in the service record, otherwise this method returns null.
 String getConnectionURL(int requiredSecurity, boolean mustBeMaster)
          Returns a String including optional parameters that can be used by a client to connect to the service described by this ServiceRecord.
 RemoteDevice getHostDevice()
          Returns the remote Bluetooth device that populated the service record with attribute values.
 boolean populateRecord(int[] attrIDs)
          Retrieves the values by contacting the remote Bluetooth device for a set of service attribute IDs of a service that is available on a Bluetooth device.
 boolean setAttributeValue(int attrID, DataElement attrValue)
          Modifies this ServiceRecord to contain the service attribute defined by the attribute-value pair (attrID, attrValue).
 void setDeviceServiceClasses(int classes)
          Used by a server application to indicate the major service class bits that should be activated in the server's DeviceClass when this ServiceRecord is added to the SDDB.
 

Field Detail

AUTHENTICATE_ENCRYPT

public static final int AUTHENTICATE_ENCRYPT
Authentication and encryption are required for connections to this service. Used with getConnectionURL() method.

AUTHENTICATE_ENCRYPT is set to the constant value 0x02 (2).

See Also:
getConnectionURL(int, boolean)
Since:
JDE 4.2.1

AUTHENTICATE_NOENCRYPT

public static final int AUTHENTICATE_NOENCRYPT
Authentication is required for connections to this service, but not encryption. It is OK for encryption to be either on or off for the connection. Used with getConnectionURL() method.

AUTHENTICATE_NOENCRYPT is set to the constant value 0x01 (1).

See Also:
getConnectionURL(int, boolean)
Since:
JDE 4.2.1

NOAUTHENTICATE_NOENCRYPT

public static final int NOAUTHENTICATE_NOENCRYPT
Authentication and encryption are not needed on a connection to this service. Used with getConnectionURL() method.

NOAUTHENTICATE_NOENCRYPT is set to the constant value 0x00 (0).

See Also:
getConnectionURL(int, boolean)
Since:
JDE 4.2.1
Method Detail

getAttributeIDs

public int[] getAttributeIDs()
Returns the service attribute IDs whose value could be retrieved by a call to getAttributeValue(). The list of attributes being returned is not sorted and includes default attributes.
Returns:
an array of service attribute IDs that are in this object and have values for them; if there are no attribute IDs that have values, this method will return an array of length zero.
Since:
JDE 4.2.1
See Also:
getAttributeValue(int)

getAttributeValue

public DataElement getAttributeValue(int attrID)
Returns the value of the service attribute ID provided it is present in the service record, otherwise this method returns null.
Parameters:
attrID - the attribute whose value is to be returned
Returns:
the value of the attribute ID if present in the service record, otherwise null
Throws:
IllegalArgumentException - if attrID is negative or greater than or equal to 216
Since:
JDE 4.2.1

getConnectionURL

public String getConnectionURL(int requiredSecurity,
                               boolean mustBeMaster)
Returns a String including optional parameters that can be used by a client to connect to the service described by this ServiceRecord. The return value can be used as the first argument to Connector.open(). In the case of a Serial Port service record, this string might look like "btspp://0050CD00321B:3;authenticate=true;encrypt=false;master=true", where "0050CD00321B" is the Bluetooth address of the device that provided this ServiceRecord, "3" is the RFCOMM server channel mentioned in this ServiceRecord, and there are three optional parameters related to security and master/slave roles.

If this method is called on a ServiceRecord returned from LocalDevice.getRecord(), it will return the connection string that a remote device will use to connect to this service.

Parameters:
requiredSecurity - determines whether authentication or encryption are required for a connection
mustBeMaster - true indicates that this device must play the role of master in connections to this service; false indicates that the local device is willing to be either the master or the slave
Returns:
a string that can be used to connect to the service or null if the ProtocolDescriptorList in this ServiceRecord is not formatted according to the Bluetooth specification
Throws:
IllegalArgumentException - if requiredSecurity is not one of the constants NOAUTHENTICATE_NOENCRYPT, AUTHENTICATE_NOENCRYPT, or AUTHENTICATE_ENCRYPT
Since:
JDE 4.2.1
See Also:
NOAUTHENTICATE_NOENCRYPT, AUTHENTICATE_NOENCRYPT, AUTHENTICATE_ENCRYPT

getHostDevice

public RemoteDevice getHostDevice()
Returns the remote Bluetooth device that populated the service record with attribute values. It is important to note that the Bluetooth device that provided the value might not be reachable anymore, since it can move, turn off, or change its security mode denying all further transactions.
Returns:
the remote Bluetooth device that populated the service record, or null if the local device populated this ServiceRecord
Since:
JDE 4.2.1

populateRecord

public boolean populateRecord(int[] attrIDs)
                       throws IOException
Retrieves the values by contacting the remote Bluetooth device for a set of service attribute IDs of a service that is available on a Bluetooth device. (This involves going over the air and contacting the remote device for the attribute values.) The system might impose a limit on the number of service attribute ID values one can request at a time. Applications can obtain the value of this limit as a String by calling LocalDevice.getProperty("bluetooth.sd.attr.retrievable.max"). The method is blocking and will return when the results of the request are available. Attribute IDs whose values could be obtained are added to this service record. If there exist attribute IDs for which values are retrieved this will cause the old values to be overwritten. If the remote device cannot be reached, an IOException will be thrown.
Parameters:
attrIDs - the list of service attributes IDs whose value are to be retrieved; the number of attributes cannot exceed the property bluetooth.sd.attr.retrievable.max; the attributes in the request must be legal, i.e. their values are in the range of [0, 216-1]. The input attribute IDs can include attribute IDs from the default attribute set too.
Returns:
true if the request was successful in retrieving values for some or all of the attribute IDs; false if it was unsuccessful in retrieving any values
Throws:
IOException - if the local device is unable to connect to the remote Bluetooth device that was the source of this ServiceRecord; if this ServiceRecord was deleted from the SDDB of the remote device
IllegalArgumentException - if the size of attrIDs exceeds the system specified limit as defined by bluetooth.sd.attr.retrievable.max; if the attrIDs array length is zero; if any of their values are not in the range of [0, 216-1]; if attrIDs has duplicate values
NullPointerException - if attrIDs is null
RuntimeException - if this ServiceRecord describes a service on the local device rather than a service on a remote device
Since:
JDE 4.2.1

setAttributeValue

public boolean setAttributeValue(int attrID,
                                 DataElement attrValue)
Modifies this ServiceRecord to contain the service attribute defined by the attribute-value pair (attrID, attrValue). If the attrID does not exist in the ServiceRecord, this attribute-value pair is added to this ServiceRecord object. If the attrID is already in this ServiceRecord, the value of the attribute is changed to attrValue. If attrValue is null, the attribute with the attribute ID of attrID is removed from this ServiceRecord object. If attrValue is null and attrID does not exist in this object, this method will return false.

This method makes no modifications to a service record in the SDDB. In order for any changes made by this method to be reflected in the SDDB, a call must be made to the acceptAndOpen() method of the associated notifier to add this ServiceRecord to the SDDB for the first time, or a call must be made to the updateRecord() method of LocalDevice to modify the version of this ServiceRecord that is already in the SDDB.

This method prevents the ServiceRecordHandle from being modified by throwing an IllegalArgumentException.

Parameters:
attrID - the service attribute ID
attrValue - the DataElement which is the value of the service attribute
Returns:
true if the service attribute was successfully added, removed, or modified; false if attrValue is null and attrID is not in this object
Throws:
IllegalArgumentException - if attrID does not represent a 16-bit unsigned integer; if attrID is the value of ServiceRecordHandle (0x0000)
RuntimeException - if this method is called on a ServiceRecord that was created by a call to DiscoveryAgent.searchServices()
Since:
JDE 4.2.1

setDeviceServiceClasses

public void setDeviceServiceClasses(int classes)
Used by a server application to indicate the major service class bits that should be activated in the server's DeviceClass when this ServiceRecord is added to the SDDB. When client devices do device discovery, the server's DeviceClass is provided as one of the arguments of the deviceDiscovered method of the DiscoveryListener interface. Client devices can consult the DeviceClass of the server device to get a general idea of the kind of device this is (e.g., phone, PDA, or PC) and the major service classes it offers (e.g., rendering, telephony, or information). A server application should use the setDeviceServiceClasses method to describe its service in terms of the major service classes. This allows clients to obtain a DeviceClass for the server that accurately describes all of the services being offered.

When acceptAndOpen() is invoked for the first time on the notifier associated with this ServiceRecord, the classes argument from the setDeviceServiceClasses method is OR'ed with the current setting of the major service class bits of the local device. The OR operation potentially activates additional bits. These bits may be retrieved by calling getDeviceClass() on the LocalDevice object. Likewise, a call to LocalDevice.updateRecord() will cause the major service class bits to be OR'ed with the current settings and updated.

The documentation for DeviceClass gives examples of the integers that describe each of the major service classes and provides a URL for the complete list. These integers can be used individually or OR'ed together to describe the appropriate value for classes.

Later, when this ServiceRecord is removed from the SDDB, the implementation will automatically deactivate the device bits that were activated as a result of the call to setDeviceServiceClasses. The only exception to this occurs if there is another ServiceRecord that is in the SDDB and setDeviceServiceClasses has been sent to that other ServiceRecord to request that some of the same bits be activated.

Parameters:
classes - an integer whose binary representation indicates the major service class bits that should be activated
Throws:
IllegalArgumentException - if classes is not an OR of one or more of the major service class integers in the Bluetooth Assigned Numbers document. While Limited Discoverable Mode is included in this list of major service classes, its bit is activated by placing the device in Limited Discoverable Mode (see the GAP specification), so if bit 13 is set this exception will be thrown.
RuntimeException - if the ServiceRecord receiving the message was obtained from a remote device
Since:
JDE 4.2.1



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.