Bluetooth Hands-Free Profile Implementation


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...


enum  { ,
 Error values for subsystem LIBHFP_ERROR_SUBSYS_BT. More...
 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:

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().


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.

LIBHFP_ERROR_BT_SYSCALL  System call failure
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_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_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()
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.

Generated on Fri Jan 9 05:58:36 2009 for libhfp by  doxygen 1.5.4