Package totalcross.io.device.bluetooth

Class ServiceRecord

  • public class ServiceRecord
extends java.lang.Object
    The ServiceRecord class 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, totalcross.io.device.bluetooth.ServiceRecord[]) method of the DiscoveryListener interface. ServiceRecords are available to server applications via the method totalcross.io.device.bluetooth.LocalDevice#getRecord(totalcross.io.Connection).

    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 NameAttribute IDAttribute Value Type
    ServiceRecordHandle0x000032-bit unsigned integer
    ServiceClassIDList0x0001DATSEQ of UUIDs
    ServiceRecordState0x000232-bit unsigned integer
    ServiceID0x0003UUID
    ProtocolDescriptorList0x0004DATSEQ of DATSEQ of UUID and optional parameters
    BrowseGroupList0x0005DATSEQ of UUIDs
    LanguageBasedAttributeIDList0x0006DATSEQ of DATSEQ triples
    ServiceInfoTimeToLive0x000732-bit unsigned integer
    ServiceAvailability0x00088-bit unsigned integer
    BluetoothProfileDescriptorList0x0009DATSEQ of DATSEQ pairs
    DocumentationURL0x000AURL
    ClientExecutableURL0x000BURL
    IconURL0x000CURL
    VersionNumberList0x0200DATSEQ of 16-bit unsigned integers
    ServiceDatabaseState0x020132-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.

    Attribute NameAttribute ID OffsetAttribute Value Type
    ServiceName0x0000String
    ServiceDescription0x0001String
    ProviderName0x0002String
    Since:
    TotalCross 1.15

    • Field Summary

      Fields 
      Modifier and Type Field Description
      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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      java.lang.String getConnectionURL()
      Returns a string including optional parameters that can be used by a client to connect to the service described by this ServiceRecord.
      java.lang.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.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

      • 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:
        Constant Field Values

    • Method Detail

      • 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:
        TotalCross 1.27

      • 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:
        java.lang.IllegalArgumentException - if attrID is negative or greater than or equal to 216
        Since:
        TotalCross 1.27

      • getConnectionURL

        public java.lang.String getConnectionURL()
        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.
        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
        Since:
        TotalCross 1.15

      • getConnectionURL

        public java.lang.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.
        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:
        java.lang.IllegalArgumentException - if requiredSecurity is not one of the constants NOAUTHENTICATE_NOENCRYPT, AUTHENTICATE_NOENCRYPT, or AUTHENTICATE_ENCRYPT
        Since:
        TotalCross 1.27
        See Also:
        NOAUTHENTICATE_NOENCRYPT