Wiki Navigation

Bluetooth Services

Description

The service interfaces aim provide an easy way to develop Bluetooth services. For remote service search(handles/records) check the Adapter interface. This section is restricted to local interactions only. There are two interfaces related to Bluetooth services:

Service interface: retrieve information about the registered service. eg: name, description, status, Bus id, ...
Database interface: manage SDP records and service connection authorizations

BlueZ services can be classified as external and internal. Internal are services registered automatically when the system starts. External are services running in the standalone mode where the user start the service and ask for registration. Once the service is registered, an object instance will be available, the methods provided are described below.

org.bluez.Service

The following API may be out-of-date check the utils/hcid/dbus-api.txt to get the latest version.

Service hierarchy
=================

Service         org.bluez
Interface       org.bluez.Service
Object path     path from org.bluez.Manager.ListServices()

Methods         dict GetInfo()

                        Returns the service properties.

                string GetIdentifier()

                        This method returns the service identifier.

                string GetName()

                        This method returns the service name.

                string GetDescription()

                        This method returns the service description.

                string GetBusName() [experimental]

                        Returns the unique bus name of the service if it has
                        been started.

                        Possible errors: org.bluez.Error.NotAvailable

                void Start()

                        This method tells the system to start the
                        service.

                void Stop()

                        This method tells the system to stop the
                        service.

                boolean IsRunning()

                        Returns true if the service has been started and
                        is currently active. Otherwise, it returns false.

                boolean IsExternal()

                        Returns true if the service was registered using the
                        Database.RegisterService method instead of a .service
                        file. The Start and Stop methods are not applicable to
                        external services and will return an error.

                array{string} ListUsers() [experimental]

                        Returns list of current users (device addresses)
                        of the service.

                void RemoveUser(string address) [experimental]

                        Removes a user of the service. The address parameter
                        must match one of the current users of the service.

                void SetTrusted(string address) [experimental]

                        Marks the user as trusted.

                        Possible errors: org.bluez.Error.InvalidArguments
                                         org.bluez.Error.AlreadyExists

                boolean IsTrusted(string address) [experimental]

                        Returns true if the user is trusted or false otherwise.
                        The address parameter must match one of the
                        current users of the service.

                        Possible errors: org.bluez.Error.InvalidArguments

                void RemoveTrust(string address) [experimental]

                        Marks the user as not trusted.

                        Possible errors: org.bluez.Error.InvalidArguments
                                         org.bluez.Error.DoesNotExist

Signals         void Started()

                        The object path of this signal contains which service
                        was started.

                void Stopped()

                        The object path of this signal contains which service
                        was stopped.

                void TrustAdded(string address)

                        Sent when SetTrusted() is called.

                void TrustRemoved(string address)

                        Sent when RemoveTrust() is called.

Architecture

The hcid is the main entity of the architecture. It implements methods to setup the Bluetooth adapters, retrieve remote device properties, control the pairing procedure and control the services registration/searches. The following figure shows a high level view of the architecture and how the D-Bus messages are transmitted.

Service Activation

Services specified by the files under the directory "/etc/bluetooth" are automatically initiated when the "hcid" daemon starts. BlueZ uses 'inotify' mechanism to track the service configuration files changes(create/delete).

The following file(headset.service) describes the headset service file:

[Bluetooth Service]
Identifier=headset
Name=Headset service
Description=Bluetooth Headset and Handsfree service
AutoStart=true

The identifier is the argument used when a Client wants to find or activate a service. For more information read FindService? and ActivateService? methods in the Manager interface. The 'AutoStart?' attribute means that the service will be initialized automatically when the system starts.

Storage

Internal services such as Audio, Input and Network store some data making possible register previously used objects automatically when the service daemon starts. The service data files are stored under the Bluetooth adapter address directory at: "/var/lib/bluetooth".

A generic assumption that every service must follow is register objects paths even the Bluetooth source address(local adapter) is not available(Removable Bluetooth adapter can be attached later).

Message Sequence Chart

Manager Entity

TBD

Service paths and interfaces

When a new service is registered the hcid assign/register a new D-Bus path. The path name standard is "/org/bluez/service_{identifier}" for internal services and "/org/bluez/external_{identifier}" for external services. Registered paths can be retrieved using ListServices? methods at the Manager interface.

Available Services

Audio: HSP, HFP, A2DP and AVRCP profiles
Input: HID and "fake input" devices
Network: PAN Profile service
Serial: Serial(RFCOMM) connections service