3.4. SDP API

3.4.1. Universally Unique Identifier

An universally unique identifier (UUID) is guaranteed to be unique across all space and all time. UUIDs can be independently created in a distributed fashion. No central registry of assigned UUIDs is required. A UUID is a 128-bit value. UUIDs are used to uniquely identify service classes.

To reduce the burden of storing and transferring 128-bit UUID values, a range of UUID values has been preallocated for assignment to often-used, registered purposes. The first UUID in this preallocated range is known as the Bluetooth Base UUID and has the value 00000000-0000-1000-8000- 00805F9B34FB, from the Bluetooth Assigned Numbers document. UUID values in the preallocated range have aliases that are represented as 16-bit or 32-bit values. These aliases are often called 16-bit and 32-bit UUIDs, but it is important to note that each actually represents a 128-bit UUID value.

UUID object (see definition below) is used to store UUID, which can store 16, 32 or 128 bits UUID. To simplify interface to this object Affix provides set of functions to create UUID from a value and convert one type of UUID to another.

typedef struct {
    int type;
    union {
        uint16_t uuid16Bit;
        uint32_t uuid32Bit;
        uint128_t uuid128Bit;
    } value ;
} uuid_t;

3.4.2. A Service Record

Types of services varies a lot. A service can provide information, perform an action (like printing) or control some third resource. Implementation might be done with hardware or software or combining these.

A SDP server maintains information about it's services in a list of service records. A service record contains a set of attributes that describes the characteristics of the service. Affix defines service record like follows:

typedef struct {
    uint32_t serviceRecordHandle;
    BD_ADDR *bda; /* service owner */
    int      state;
    sdppdu_t pdu; /* PDU form and the entire service record */
    slist_t  *targetPattern; /* all possible uuid_t */
    slist_t  *attributeList;
    int      fd; /* to remove service */
} sdpsvc_t ;

Above structure is a composite of many attributes. Still not all of them need be present. References of those composites not present would be set to NULL. The service record handle identifies the service uniquely within the server. Note that identifiers in two separate servers do not match although the service might be the same.

There is one exception to that. A service record handle whose meaning is the same on all SDP servers. It's value is 0x00000000 and it represents the SDP server itself.

3.4.3. Service Attributes

Each service attribute describes a single characteristic of a service. Universal attributes are defined in the SDP specification. Below is listed some of the universal attributes. In addition to those service providers can define their own attributes. An attribute consist of two components: service attribute ID and the value.

The attribute ID is 16 bit unsigned integer which distinguishes all the attributes within one service record. It also defines the type of the attributes value (see the following chapter). A service class defines a set of attributes that are common to that classes instances. All services belonging to a given service class assign the same meaning to each particular attribute ID.

The following table lists the most common universal attributes. Table has the definitions and a brief description of the purpose. You can find the rest of the definitions in file sdp.h.

In addition to universal attributes, a service could have "service specific attributes". These attributes make sense only in the context of the said service. Dynamic attributes could be either basic attributes or constructed.

The attribute value is a variable length field whose meaning is determined by the attribute ID associated with it and by the service class of the service record in which the attribute is contained. SDP uses a simple mechanism to describe the data contained within an attribute value.

A data element is a typed data representation. It has header and data fields. Header field in turn has also two fields: data type and size. This is called Data Type Descriptor (DTD). A data element type is represented as a 5-bit type descriptor. The type descriptor is contained in the most significant (high-order) 5 bits of the first byte of the data element header. Data types are defined in sdp.h and are in form SDP_DTD_<type>. Where <type> is the data type. For example:

#define SDP_DTD_UINT32 0x0A /* Defines an unsigned 32 bit integer*/
#define SDP_DTD_STR16 0x26 /* Defines a string which length is stored in a 16 bit integer */

SDP defines two special data types: sequence and alternative. Data element sequence, a data element whose data field is a sequence of data elements. Alternative is a data element whose data field is a sequence of data elements from which one data element is to be selected.

The data element size descriptor is represented as a 3-bit size index followed by 0, 8, 16, or 32 bits. The size index is contained in the least significant (low order) 3 bits of the first byte of the data element header.

3.4.4. Attribute API

The generic data structure sdpdata is meant to hold any attribute, universal or dynamic. Each sdpdata structure contains one attribute. The sdpdata object contains the service attribute identifier, a Data Type Descriptor followed by the value. Protocol Data Unit (PDU) is a serialized presentation of the object.

typedef struct sdpdata {
    uint8_t dtd;
    uint16_t attrId;
    union {
        int8_t    int8;
        int16_t   int16;
        int32_t   int32;
        int64_t   int64;
        uint128_t int128;
        uint8_t   uint8;
        uint16_t  uint16;
        uint32_t  uint32;
        uint64_t  uint64;
        uint128_t uint128;
        uuid_t    uuid;
        char      *stringPtr;
        slist_t   *dataSeq;
    } value;
    sdppdu_t pdu;
    int unitSize;
} sdpdata_t;

Affix has set of functions that can be used to create and manipulate attributes.

Service attributes are stored in service records. Affix has functions to add, remove and get attributes from a service record. These functions are the glue between these two structures.

3.4.5. Service Client SDP API

The client SDP API is used by a client to find services provided by a remote device and to find out what attributes they have. The overall function set is shown on the following table:

3.4.6. Service Provider SDP API

Bluetooth service developers can use the following API to register services with the "local" SDP server. The "on-the-wire" formats of service registrations mimic the SDP. However a key difference is that service registrations Protocol data units (PDU) are never sent on Bluetooth channels, but done using TCP sockets. The service registration requests and responses use the "reserved range" of SDP PDU Identifiers. There is no problem since it is not sent on BT channels. The following are the APIs available for service implementers to register their service with the SDP server on the device.

attr = sdp_set_class_attr(sdpSvcRec);
sdp_add_class(attr, SDP_UUID_SDP_SERVER);
sdp_add_uuid16_to_pattern(sdpSvcRec, SDP_UUID_SDP_SERVER);