Public Member Functions | |
| Start () | |
| Attempt to start the Bluetooth service. | |
| Stop () | |
| Shut down the Bluetooth service. | |
| StartInquiry () | |
| Start inquiry (scan for devices). | |
| StopInquiry () | |
| Stop an inquiry in progress. | |
| GetName (in string address, out string name) | |
| Read the Bluetooth name of a given device. | |
| AddDevice (in string address, in bool set_known, out objectpath object) | |
| Add a device to HFPD's device list, and claim ownership of it. | |
| RemoveDevice (in string address) | |
| Release a claim on a device. | |
| SaveSettings () | |
| Save persistent properties to the HFPD configuration file. | |
| signal | SystemStateChanged (out bool state) |
| Notification of Bluetooth system state change. | |
| signal | InquiryStateChanged (out bool state) |
| Notification of Bluetooth inquiry state change. | |
| signal | InquiryResult (out string address, out uint32 device_class) |
| Notification of newly-discovered Bluetooth inquiry result. | |
| signal | AudioGatewayAdded (out objectpath object) |
| Notification of newly-created AudioGateway object. | |
| signal | AudioGatewayRemoved (out objectpath object) |
| Notification of destroyed AudioGateway object. | |
Public Attributes | |
| const uint32 | Version |
| Interface version provided by HFPD. | |
| const bool | SystemState |
| Current state of Bluetooth system inside of HFPD. | |
| const objectpath | AudioGateways [] |
| Set of object paths for known AudioGateway objects. | |
| bool | AutoSave |
| Configuration file auto-save property. | |
| string | SaveFile |
| Path and name of the HFPD local configuration file. | |
| bool | AutoRestart |
| Property to control periodic restart attempts for the Bluetooth service. | |
| byte | SecMode |
| Security mode for HFP service-level connections. | |
| bool | AcceptUnknown |
| Property controlling whether unknown devices are allowed to initiate service-level connections. | |
| bool | ScoEnabled |
| Property controlling whether SCO audio functionality will be used. | |
| bool | VoicePersist |
| Property controlling handling of audio connections for unclaimed devices. | |
| bool | VoiceAutoConnect |
| Property controlling handling of audio connections from unclaimed but permanently known devices. | |
| uint32 | ReportCapabilities |
| Hands-free capability bit field reported to audio gateway devices when handshaking. | |
| string | ServiceName |
| Service name string set in HFPD's SDP record. | |
| string | ServiceDesc |
| Service description string set in HFPD's SDP record. | |
The main access object provides a number of basic functions useful for implementing hands-free profile.
The HFPD process will instantiate one object that implements this interface at path /net/sf/nohands/hfpd
| net.sf.nohands.hfpd.HandsFree.Start | ( | ) |
Attempt to start the Bluetooth service.
This method will attempt to start the Bluetooth service within the HFPD process. This includes binding to a local Bluetooth adapter, opening a socket to receive incoming HFP service-level connections, and registering an SDP record. Unless the service is started, Bluetooth devices will not observe the local system as implementing the Hands-Free Profile and will not be able to use it.
If the Bluetooth service is already started, this method will do nothing.
| net.sf.nohands.hfpd.Error | Thrown for uninteresting errors. | |
| net.sf.nohands.hfpd.Error.BtNoKernelSupport | Kernel lacks required Bluetooth support. | |
| net.sf.nohands.hfpd.Error.BtServiceConflict | Another service has claimed the SCO listening socket. | |
| net.sf.nohands.hfpd.Error.BtScoConfigError | The attached HCI has misconfigured SCO settings, which can only be resolved by a superuser. |
| net.sf.nohands.hfpd.HandsFree.Stop | ( | ) |
Shut down the Bluetooth service.
If the Bluetooth service is started, this method will cause it to be stopped. Its SDP record will be deregistered, and its listening Bluetooth sockets will be closed.
If the Bluetooth service is already stopped, this method will do nothing.
| net.sf.nohands.hfpd.HandsFree.StartInquiry | ( | ) |
Start inquiry (scan for devices).
Initiates a Bluetooth inquiry to enumerate discoverable devices.
When an inquiry is started, it will generate an InquiryStateChanged() signal. While it is in progress, nearby discoverable devices will be identified and reported to D-Bus clients through the InquiryResult() signal. After approximately five seconds, the inquiry will be terminated, which will cause an InquiryStateChanged() signal to be generated.
| net.sf.nohands.hfpd.Error | Thrown if an inquiry could not be started, i.e. because one is already in progress or the Bluetooth service has not been started. |
| net.sf.nohands.hfpd.HandsFree.StopInquiry | ( | ) |
Stop an inquiry in progress.
Aborts an in-progress inquiry. If an inquiry was in progress when this method was invoked, and was successfully stopped, an InquiryStateChanged() signal will be generated.
| net.sf.nohands.hfpd.HandsFree.GetName | ( | in string | address, | |
| out string | name | |||
| ) |
Read the Bluetooth name of a given device.
This method executes the read name function on a given Bluetooth device and returns the name as a string.
| [in] | address | Address of the Bluetooth device to read the name of, in colon-separated form, e.g. "01:23:45:67:89:AB" |
| [out] | name | Name of the device as read, returned as a string, e.g. "Motorola Phone" |
| net.sf.nohands.hfpd.Error | Thrown on any sort of error, unspecific of the reason of failure. |
| net.sf.nohands.hfpd.HandsFree.AddDevice | ( | in string | address, | |
| in bool | set_known, | |||
| out objectpath | object | |||
| ) |
Add a device to HFPD's device list, and claim ownership of it.
This method will create a new device record inside of HFPD for a device with address, and will mark it as owned by the caller's D-Bus client.
Claimed devices are granted access to specific services provided by HFPD:
false. The D-Bus client that claimed the device will be informed of this through the AudioGateway.StateChanged signal emitted by the object created to represent the device.When HFPD starts, no devices are claimed. The D-Bus client must enumerate the list of devices it wishes to claim each time it connects to HFPD through D-Bus, using this method.
Only one D-Bus client is allowed to claim each device. If a request is made to claim a device that has already been claimed by a different D-Bus client, the request will fail.
HFPD monitors D-Bus disconnections. When a D-Bus client that has claimed devices is disconnected, its claimed devices are automatically released and reverted to the unclaimed state. The following set of actions will be taken on devices claimed by disconnected D-Bus clients:
true.
| [in] | address | Bluetooth address of the target device, in colon-separated form, e.g. "01:23:45:67:89:AB" |
| [in] | set_known | Set to true to mark the device as permanently known to HFPD, so that it may connect to HFPD and open an audio channel when not claimed by a D-Bus client. This mark will be saved to HFPD's configuration file and will be persistent. |
| [out] | object | D-Bus path to the AudioGateway object created to represent the device. |
| net.sf.nohands.hfpd.Error | Thrown on any sort of error, unspecific of the reason of failure. |
| net.sf.nohands.hfpd.HandsFree.RemoveDevice | ( | in string | address | ) |
Release a claim on a device.
For devices that have been claimed by a given D-Bus client, this method releases the claim on the device and disconnects the device if it is connected.
| [in] | address | Bluetooth address of the device to have its claim released, in colon-separated form, e.g. "01:23:45:67:89:AB" |
| net.sf.nohands.hfpd.Error | Thrown on any sort of error, unspecific of the reason of failure. |
| net.sf.nohands.hfpd.HandsFree.SaveSettings | ( | ) |
Save persistent properties to the HFPD configuration file.
This method will cause the HFPD configuration file, located at the path in HandsFree.SaveFile, to be rewritten and filled with the current set of non-default values for configuration options.
It is not necessary to call this method if the HandsFree.AutoSave property is set to true.
| net.sf.nohands.hfpd.Error | Thrown if the configuration file could not be created or overwritten. |
| signal net.sf.nohands.hfpd.HandsFree.SystemStateChanged | ( | out bool | state | ) |
Notification of Bluetooth system state change.
This signal is sent whenever the Bluetooth system state changes, e.g. when it transitions from started to stopped due to the unplugging of a Bluetooth dongle.
| [out] | state | The parameter is set to true if the Bluetooth system transitioned to the started state, false if it transitioned to the stopped state. |
| signal net.sf.nohands.hfpd.HandsFree.InquiryStateChanged | ( | out bool | state | ) |
Notification of Bluetooth inquiry state change.
This signal is sent whenever a Bluetooth inquiry is started or completed.
| [out] | state | The parameter is set to true if a Bluetooth inquiry has been started, false if a running Bluetooth inquiry has completed or has been terminated by StopInquiry(). |
| signal net.sf.nohands.hfpd.HandsFree.InquiryResult | ( | out string | address, | |
| out uint32 | device_class | |||
| ) |
Notification of newly-discovered Bluetooth inquiry result.
This signal is sent whenever a previously started Bluetooth inquiry discovered a new, unique device.
| [out] | address | The Bluetooth address of the newly discovered device, formatted as a colon-separated string, e.g. "01:23:45:67:89:AB" |
| [out] | device_class | The reported Bluetooth device class of the newly discovered device. This can be used to filter devices, e.g. to display only those that implement audio gateway functionality. |
| signal net.sf.nohands.hfpd.HandsFree.AudioGatewayAdded | ( | out objectpath | object | ) |
Notification of newly-created AudioGateway object.
When a D-Bus client claims a previously unknown device, and when a previously unknown device initiates an inbound service level connection, this signal is emitted.
The new AudioGateway object is also added to HandsFree.AudioGateways.
| object | D-Bus path to new AudioGateway object. |
| signal net.sf.nohands.hfpd.HandsFree.AudioGatewayRemoved | ( | out objectpath | object | ) |
Notification of destroyed AudioGateway object.
When no reasons remain to retain an AudioGateway object, it is removed from the list of known AudioGateway objects and its D-Bus object is destroyed. This signal informs of such an event.
An AudioGateway object can be removed when:
The removed AudioGateway object is also removed from HandsFree.AudioGateways.
| object | D-Bus path to removed AudioGateway object. |
| const uint32 net.sf.nohands.hfpd.HandsFree.Version |
Interface version provided by HFPD.
This property can be accessed using the standard D-Bus property interface.
The D-Bus interface provided by HFPD is subject to changes and evolution. This property provides a fast way for a D-Bus client to determine whether the HFPD it is attempting to use implements the D-Bus interfaces that it expects. If a client reads this property and finds an unexpected value, it should fail and warn about a version mismatch.
This document describes version 4 of the HFPD D-Bus interface.
A version number value in this field covers all HFPD D-Bus interfaces, including HandsFree, SoundIo, and AudioGateway.
| const bool net.sf.nohands.hfpd.HandsFree.SystemState |
Current state of Bluetooth system inside of HFPD.
This property can be accessed using the standard D-Bus property interface.
If true, the Bluetooth system has been started and is usable.
If false, the Bluetooth system is stopped.
| const objectpath net.sf.nohands.hfpd.HandsFree.AudioGateways[] |
Set of object paths for known AudioGateway objects.
This property can be accessed using the standard D-Bus property interface.
This property contains a list of the object paths of all AudioGateway objects known to HFPD. It can be used to enumerate known audio gateway devices.
Changes to this property are indicated by AudioGatewayAdded() and AudioGatewayRemoved() signals.
The D-Bus signature of this property is "ao".
Configuration file auto-save property.
This property can be accessed using the standard D-Bus property interface.
If true, changes to persistent configuration options will be automatically written to the local HFPD configuration file when they are modified.
If false, changes to persistent configuration options must be explicitly written to the local HFPD configuration file in order to persist. This is done using SaveSettings(). This is default. It makes the most sense for frontends such as hfconsole that use configuration dialogs, and expect to apply new settings immediately but save them to the configuration file only when the user clicks "OK."
Path and name of the HFPD local configuration file.
This property can be accessed using the standard D-Bus property interface.
This value identifies the configuration file that HFPD uses to store local settings. It defaults to "~/.hfpdrc"
Property to control periodic restart attempts for the Bluetooth service.
This property can be accessed using the standard D-Bus property interface.
When the Bluetooth service cannot be started, e.g. because there is no dongle plugged in, this property enables periodic attempts to start the Bluetooth service.
If set to true, periodic auto-restart is enabled. This is the default value.
If set to false, periodic auto-restart is disabled.
false when certain severe errors are encountered. These include:AutoRestart is a persistent option that is saved to the HFPD configuration file.
Security mode for HFP service-level connections.
This property can be accessed using the standard D-Bus property interface.
This property allows the D-Bus client to control the security requirements placed on RFCOMM service-level connections for HFP. It may be set to one of three values:
Changes to this value affect new connections only, existing connections are not affected.
The Bluetooth Hands-Free Profile specification version 1.5 does not place any specific requirements on the security of RFCOMM service-level connections for HFP. This value defaults to 1 (PIN authentication).
Property controlling whether unknown devices are allowed to initiate service-level connections.
This property can be accessed using the standard D-Bus property interface.
If true, devices not claimed by a D-Bus client and not marked permanently known are permitted to initiate service-level connections to hfpd.
If false, incoming service-level connections from devices not claimed by a D-Bus client and not marked permanently known are refused. This is the default.
In order for an unknown device to initiate pairing and make itself known to a D-Bus client, this value must be set to true. In this case, D-Bus clients will be informed of inbound connections from previously unknown devices by the AudioGatewayAdded() signal. Otherwise, all new device pairing must be initiated by D-Bus clients, typically using StartInquiry() and AddDevice().
Property controlling whether SCO audio functionality will be used.
This property can be accessed using the standard D-Bus property interface.
If true, SCO audio support is enabled. This allows voice audio data to be exchanged over Bluetooth, and is the default.
If false, SCO audio will not be used. This may permit hfpd to operate in environments where another service provides support for streaming SCO audio to the local sound card.
Property controlling handling of audio connections for unclaimed devices.
This property can be accessed using the standard D-Bus property interface.
When the D-Bus owner of a claimed device is disconnected from D-Bus, often because a defect in the D-Bus client caused it to crash, normally all of its claimed devices will be immediately disconnected. If one of the devices has its audio connection configured and routed through the local sound card, it may be undesirable to disconnect it immediately. This property controls special handling of devices in the aforementioned situation.
If true, the device will remain connected until its audio connection is dropped, either due to the device itself dropping the connection, or a sound card failure. When the audio connection is dropped, the device will be disconnected immediately.
If false, the device will be disconnected immediately. Audio will be rerouted through the device itself.
Property controlling handling of audio connections from unclaimed but permanently known devices.
This property can be accessed using the standard D-Bus property interface.
When a permanently known device connects to HFPD, it may do so outside the supervision of a D-Bus client. Normally, the D-Bus client is responsible for noticing when a device initiates an audio connection, and for either routing the audio connection to the local sound card or immeidately dropping the audio connection. It may be desirable for HFPD to automatically try to route audio connections initiated by permanently known devices. This property controls special handling of devices in the aforementioned situation.
If true, HFPD will attempt to automatically route incoming audio connections from permanently known, unclaimed devices to the local sound card. If routing fails, the audio connection to the device will be closed.
If false, HFPD will refuse incoming audio connections from permanently known, unclaimed devices. For security, this is the default value.
Hands-free capability bit field reported to audio gateway devices when handshaking.
This property can be accessed using the standard D-Bus property interface.
The Bluetooth Hands-Free Profile specification identifies a supported features bit field that is presented by the hands-free to the audio gateway device when initiating a service level connection. This property allows D-Bus clients access to the reported supported features.
This field can be used to inform devices not to expect the hands-free to support specific features, such as voice recognition activation and volume control.
Most D-Bus clients should not need to change the value of this property.
Service name string set in HFPD's SDP record.
This property can be accessed using the standard D-Bus property interface.
The SDP record created by HFPD has a customizable service name string. It is not generally end-user visible, but can be queried using "sdptool records local". The default value is "Handsfree".
Service description string set in HFPD's SDP record.
This property can be accessed using the standard D-Bus property interface.
The SDP record created by HFPD has a customizable service description string. It is not generally end-user visible, but can be queried using "sdptool records local". By default, the description field is empty.
1.5.4