|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 DiscoveryListener.servicesDiscovered(int, javax.bluetooth.ServiceRecord[])
method
of the DiscoveryListener
interface.
ServiceRecords
are available to server applications via the method
LocalDevice.getRecord(javax.microedition.io.Connection)
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/assigned-numbers/sdp.htm) defines a large number of service attribute IDs. Here is a subset of the most common service attribute IDs and their types.
Attribute Name | Attribute ID | Attribute Value Type |
---|---|---|
ServiceRecordHandle | 0x0000 | 32-bit unsigned integer |
ServiceClassIDList | 0x0001 | DATSEQ of UUIDs |
ServiceRecordState | 0x0002 | 32-bit unsigned integer |
ServiceID | 0x0003 | UUID |
ProtocolDescriptorList | 0x0004 | DATSEQ of DATSEQ of UUID and optional parameters |
BrowseGroupList | 0x0005 | DATSEQ of UUIDs |
LanguageBasedAttributeIDList | 0x0006 | DATSEQ of DATSEQ triples |
ServiceInfoTimeToLive | 0x0007 | 32-bit unsigned integer |
ServiceAvailability | 0x0008 | 8-bit unsigned integer |
BluetoothProfileDescriptorList | 0x0009 | DATSEQ of DATSEQ pairs |
DocumentationURL | 0x000A | URL |
ClientExecutableURL | 0x000B | URL |
IconURL | 0x000C | URL |
VersionNumberList | 0x0200 | DATSEQ of 16-bit unsigned integers |
ServiceDatabaseState | 0x0201 | 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/dev/specifications.asp
).
Attribute Name | Attribute ID Offset | Attribute Value Type |
---|---|---|
ServiceName | 0x0000 | String |
ServiceDescription | 0x0001 | String |
ProviderName | 0x0002 | String |
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(int) . |
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 |
---|
static final int NOAUTHENTICATE_NOENCRYPT
getConnectionURL(int, boolean)
method.
NOAUTHENTICATE_NOENCRYPT
is set to the constant value 0x00 (0).
getConnectionURL(int, boolean)
,
Constant Field Valuesstatic final int AUTHENTICATE_NOENCRYPT
getConnectionURL(int, boolean)
method.
AUTHENTICATE_NOENCRYPT
is set to the constant value 0x01 (1).
getConnectionURL(int, boolean)
,
Constant Field Valuesstatic final int AUTHENTICATE_ENCRYPT
getConnectionURL(int, boolean)
method.
AUTHENTICATE_ENCRYPT
is set to the constant value 0x02 (2).
Method Detail |
---|
DataElement getAttributeValue(int attrID)
null
.
attrID
- the attribute whose value is to be returned
null
IllegalArgumentException
- if attrID
is negative or greater than
or equal to 216RemoteDevice getHostDevice()
null
if the local device populated this ServiceRecord
int[] getAttributeIDs()
getAttributeValue(int)
. The list of attributes being returned is not
sorted and includes default attributes.
getAttributeValue(int)
boolean populateRecord(int[] attrIDs) throws IOException
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 {link java.lang.IOException} will be thrown.
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.
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
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, 2^16-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 deviceString getConnectionURL(int requiredSecurity, boolean mustBeMaster)
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(String, int, boolean)
. 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(javax.microedition.io.Connection)
,
it will return the connection string that a remote device will use to
connect to this service.
requiredSecurity
- determines whether authentication or encryption are required
for a connectionmustBeMaster
- 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
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
IllegalArgumentException
- if requiredSecurity is not one of the constants
NOAUTHENTICATE_NOENCRYPT
,
AUTHENTICATE_NOENCRYPT
, or
AUTHENTICATE_ENCRYPT
AUTHENTICATE_ENCRYPT
,
NOAUTHENTICATE_NOENCRYPT
,
AUTHENTICATE_NOENCRYPT
void setDeviceServiceClasses(int classes)
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
DiscoveryListener.deviceDiscovered(RemoteDevice, DeviceClass)
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(int)
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(int)
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 LocalDevice.getDeviceClass()
on the LocalDevice
object. Likewise, a call to
LocalDevice.updateRecord(ServiceRecord)
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(int)
has been sent to
that other ServiceRecord
to request that some of the same bits be
activated.
classes
- an integer whose binary representation indicates the major
service class bits that should be activated
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 deviceboolean setAttributeValue(int attrID, DataElement attrValue)
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.
attrID
- the service attribute IDattrValue
- the DataElement
which is the value of
the service attribute
true
if the service attribute was successfully added,
removed, or modified; false
if attrValue
is
null
and attrID
is not in this object
IllegalArgumentException
- if attrID
does not represent a 16-bit unsigned
integer; if attrID
is the value of
ServiceRecord
Handle (0x0000)
RuntimeException
- if this method is called on a ServiceRecord
that was
created by a call to
DiscoveryAgent.searchServices(int[], UUID[], RemoteDevice, DiscoveryListener)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |