The HFP for Linux package provides a service daemon,
hfpd, that performs most of the low-level functions required to implement the hands-free side of Bluetooth Hands-Free Profile. The
hfpd process attaches to the D-Bus session bus, and is entirely controlled via D-Bus messages. All of its status can be retrieved via D-Bus, and changes to its status are notified through D-Bus signals.
The D-Bus APIs are ideally suited for constructing hands-free applications using high-level languages, such as Python, C#, or even Perl. As a lower level and much more complicated alternative, one may use the libhfp C++ APIs.
The D-Bus APIs described in this document are relatively complete. The hfconsole application is implemented entirely in Python, and uses dbus-python to access D-Bus APIs described in this document. It does not directly depend on BlueZ, and does not use the BlueZ D-Bus APIs or Python bindings. The APIs described here, and PyGTK, are the only dependencies of hfconsole in order for it to do its job.
The HFPD process acquires the D-Bus unique name
The install target of the HFP for Linux Makefiles will install a D-Bus service description file for HFPD. This allows dbus-daemon to start HFPD as needed. D-Bus clients of this API only need to send messages to the HFPD unique name in order for HFPD to be started. D-Bus clients do not need to be concerned with starting and stopping HFPD themselves.
Two known object paths are intended as the primary points of access to D-Bus clients:
/net/sf/nohands/hfpd, with interface net.sf.nohands.hfpd.HandsFree
/net/sf/nohands/hfpd/soundio, with interface net.sf.nohands.hfpd.SoundIo
For each known audio gateway device, an object with interface net.sf.nohands.hfpd.AudioGateway will be instantiated. A new object of this type can be instantiated for an audio gateway device with a specific Bluetooth address using net.sf.nohands.hfpd.HandsFree.AddDevice(), and the paths of all such objects of this type are enumerated in net.sf.nohands.hfpd.HandsFree.AudioGateways.
All interfaces provided by HFPD are introspectable and should be usable with most any language binding.
hfpd = dbus.Interface( dbus.get_object('net.sf.nohands.hfpd', '/net/sf/nohands/hfpd'), dbus_interface = 'net.sf.nohands.hfpd.HandsFree') hfpd.SecMode = 2
Unfortunately, a number of D-Bus language bindings, including dbus-python, skimp on properties and do not provide access to properties in the most transparent possible way. Depending on the language and bindings package used, a D-Bus client application of HFPD may need to take extra measures to access properties, often manually invoking
org.freedesktop.DBus.Properties.Set . For example, the above must instead be implemented as:
hfpd = dbus.Interface( dbus.get_object('net.sf.nohands.hfpd', '/net/sf/nohands/hfpd'), dbus_interface = 'net.sf.nohands.hfpd.HandsFree') hfpdprop = dbus.Interface( dbus.get_object('net.sf.nohands.hfpd', '/net/sf/nohands/hfpd'), dbus_interface = 'org.freedesktop.DBus.Properties') hfpdprop.Set('net.sf.nohands.hfpd.HandsFree', 'SecMode', 2)
For more information on the standard D-Bus properties interface, consult the D-Bus specification.
It is also possible to create a D-Bus client that does not claim any devices. Such a client might maintain a status display, and either depend on another client to claim and manage audio gateway devices, or depend on HFPD's list of permanently known audio gateway devices to permit incoming connections.