Bluetooth Hands-Free Profile Implementation

Classes
class	BtHub
	Bluetooth Device Manager. More...
class	BtManaged
	Base Class for Bluetooth Reference-Counted Objects. More...
class	BtHci
	Bluetooth Local Adapter Record. More...
class	BtDevice
	Bluetooth Device Record. More...
class	BtService
	Service object base class. More...
class	BtSession
	Session object base class. More...
class	RfcommService
	Service building block for RFCOMM profiles. More...
class	RfcommSession
	Session building block for RFCOMM profiles. More...
class	HfpService
	Service Handler for Hands-Free Profile. More...
class	HfpPendingCommand
	Audio Gateway Pending Command Object. More...
class	HfpSession
	Session object for Hands-Free Profile. More...
Enumerations
enum	{ ,   LIBHFP_ERROR_BT_SYSCALL, LIBHFP_ERROR_BT_HCI, LIBHFP_ERROR_BT_NO_SUPPORT, LIBHFP_ERROR_BT_SERVICE_CONFLICT,   LIBHFP_ERROR_BT_BAD_SCO_CONFIG, LIBHFP_ERROR_BT_SHUTDOWN, LIBHFP_ERROR_BT_NOT_CONNECTED, LIBHFP_ERROR_BT_NOT_CONNECTED_SCO,   LIBHFP_ERROR_BT_ALREADY_STARTED, LIBHFP_ERROR_BT_TIMEOUT, LIBHFP_ERROR_BT_PROTOCOL_VIOLATION, LIBHFP_ERROR_BT_USER_DISCONNECT,   LIBHFP_ERROR_BT_COMMAND_ABORTED, LIBHFP_ERROR_BT_COMMAND_REJECTED }
	Error values for subsystem LIBHFP_ERROR_SUBSYS_BT. More...
enum	rfcomm_secmode_t { RFCOMM_SEC_NONE, RFCOMM_SEC_AUTH, RFCOMM_SEC_CRYPT }
	Bluetooth RFCOMM connection security modes. More...

---

Detailed Description

This group contains objects required to use the Bluetooth Hands-Free Profile service. It includes a complete object model for Bluetooth devices, service classes, and sessions, along with life cycle management policies for device and session objects.

Object Model Overview

The BtHub is a single-instance object. It must be instantiated by the client application at start time. BtHub maintains per-application resources, including a connection to the local Service Discovery Protocol daemon used to register and advertise available services.

BtService derived objects encapsulate service-specific single instance resources. They are instantiated as needed by the client application, and registered with BtHub via BtHub::AddService() and BtHub::RemoveService(). Specifically, HfpService maintains a listening RFCOMM socket so that audio gateway devices may initiate connections. Service state is managed collectively by BtHub. BtHub will invoke the BtService::Start() and BtService::Stop() methods of each service object when Bluetooth service availability changes, i.e. when a USB Bluetooth HCI is inserted or removed.

BtDevice objects are indexed and maintained by BtHub. All BtDevice objects in the index have unique addresses. BtHub::GetDevice() can be used to look up or instantiate a BtDevice record for a specific Bluetooth address. BtHub will also instantiate BtDevice objects automatically when reporting device inquiry results.

BtSession derived objects, including HfpSession, encapsulate resources associated with an session of a service. As an example, HfpSession includes:

• The RFCOMM socket used to communicate with the device.
• Methods for controlling the device, e.g. HfpSession::CmdDial().
• Callbacks for notifying changes of the device state, e.g. HfpSession::cb_NotifyConnection.

BtSession objects are managed objects and are always instantiated by their presiding BtService derived object. They can be instantiated manually, e.g. HfpService::GetSession(), or automatically in response to remotely initiated connections.

Managed Objects

BtDevice and BtSession are managed objects, which derive from BtManaged. These objects are reference-counted. When they are deleted, they are deleted in a deferred fashion from a timer event. BtManaged objects also contain a pointer value reserved for client use. See BtManaged::SetPrivate().

Callbacks

As a rule, none of the callbacks provided by Bluetooth components are ever invoked in a nested fashion from client method calls. This breaks potential recursive loops and complex situations that might form if clients invoke method calls from callbacks, e.g.

 Connect() ->
    HfpSession::cb_NotifyConnection -> 
       Disconnect() ->
          HfpSession::cb_NotifyConnection ->
             Connect() -> ...

A client may therefore invoke any method call from any callback without having to worry about nested callbacks. However, this requires clients to be mindful of state transitions that they originate directly with method calls. For example, HfpSession::cb_NotifyConnection is invoked when the state of the device connection changes, but only if it changes by means other than the Connect() or Disconnect() methods. The client must directly notice the effects of its calls to Connect() and Disconnect(), rather than expecting all changes to be reported through HfpSession::cb_NotifyConnection.

---

Enumeration Type Documentation

anonymous enum

Error values for subsystem LIBHFP_ERROR_SUBSYS_BT.

Enumerator:

LIBHFP_ERROR_BT_SYSCALL	System call failure
LIBHFP_ERROR_BT_HCI	HCI error code
LIBHFP_ERROR_BT_NO_SUPPORT	Bluetooth support missing from kernel
LIBHFP_ERROR_BT_SERVICE_CONFLICT	Conflict over listening address for Bluetooth service
LIBHFP_ERROR_BT_BAD_SCO_CONFIG	SCO misconfiguration
LIBHFP_ERROR_BT_SHUTDOWN	Bluetooth system is shut down
LIBHFP_ERROR_BT_NOT_CONNECTED	Device is not connected
LIBHFP_ERROR_BT_NOT_CONNECTED_SCO	SCO connection has not been established
LIBHFP_ERROR_BT_ALREADY_STARTED	System or service has already been started
LIBHFP_ERROR_BT_TIMEOUT	Operation timed out
LIBHFP_ERROR_BT_PROTOCOL_VIOLATION	Protocol has been violated
LIBHFP_ERROR_BT_USER_DISCONNECT	User-initiated disconnection of device
LIBHFP_ERROR_BT_COMMAND_ABORTED	Command aborted
LIBHFP_ERROR_BT_COMMAND_REJECTED	Command rejected by device

enum rfcomm_secmode_t

Bluetooth RFCOMM connection security modes.

This enumeration describes levels of security to be applied to Bluetooth sockets when communicating with devices.

See also:

RfcommService::SetSecMode(), HfpSession::GetSecMode()

Enumerator:

RFCOMM_SEC_NONE	No authentication or encryption are mandatory.
RFCOMM_SEC_AUTH	Authentication is mandatory but encryption is not.
RFCOMM_SEC_CRYPT	Authentication and encryption are mandatory.

---