HfpService Class Reference
[Bluetooth Hands-Free Profile Implementation]

Service Handler for Hands-Free Profile. More...

#include <hfp.h>

Inheritance diagram for HfpService:

[legend]

Collaboration diagram for HfpService:

[legend]

List of all members.

Public Member Functions
HfpSession *	DefaultSessionFactory (BtDevice *)
	Default factory method for HfpSession objects.
HfpSession *	GetSession (BtDevice *devp, bool create=true)
	Look up and possibly create an HfpSession for a Bluetooth address.
HfpSession *	GetSession (bdaddr_t const &addr, bool create=true)
	Look up and possibly create an HfpSession for a Bluetooth address.
HfpSession *	GetSession (const char *addrst, bool create=true)
	Look up and possibly create an HfpSession for a Bluetooth address by address string.
HfpSession *	Connect (BtDevice *devp, ErrorInfo *error=0)
	Initiate a connection to an audio gateway device with a known address.
HfpSession *	Connect (bdaddr_t const &addr, ErrorInfo *error=0)
	Initiate a connection to an audio gateway device with a known address.
HfpSession *	Connect (const char *addrstr, ErrorInfo *error=0)
	Initiate a connection to an audio gateway device by Bluetooth address string.
HfpSession *	GetFirstSession (void) const
	Query the first session object.
HfpSession *	GetNextSession (HfpSession *sessp) const
	Query the next session object in enumeration order.
bool	GetScoEnabled (void) const
	Query whether SCO audio functionality is enabled.
bool	SetScoEnabled (bool sco_enable, ErrorInfo *error=0)
	Set whether SCO audio functionality is enabled.
int	GetCaps (void) const
bool	SetCaps (int caps, ErrorInfo *error=0)
const char *	GetServiceName (void) const
bool	SetServiceName (const char *desc, ErrorInfo *error=0)
const char *	GetServiceDesc (void) const
bool	SetServiceDesc (const char *desc, ErrorInfo *error=0)
rfcomm_secmode_t	GetSecMode (void) const
	Query the security mode of the listening socket.
bool	SetSecMode (rfcomm_secmode_t sec, ErrorInfo *error=0)
	Set the security mode of the listening socket.
BtHub *	GetHub (void) const
DispatchInterface *	GetDi (void) const
BtSession *	GetNextSession (BtSession *) const
Public Attributes
Callback< HfpSession *, BtDevice * >	cb_HfpSessionFactory
	Factory for HfpSession objects, implemented as a callback.

---

Detailed Description

Service Handler for Hands-Free Profile.

HfpService is a building block of Hands-Free Profile support, implementing single-instance functions including inbound connection handling and automatic reconnection. As such, one instance of HfpService is created per system.

Each attachable Audio Gateway device (typically a cell phone) is represented by a BtDevice object. HfpService supports the creation of an HfpSession object attached to the BtDevice, to support a Hands Free Profile session with the device. The life cycle of HfpSession objects is described in the Audio Gateway Life Cycle section.

Service Operation

Clients will typically instantiate one HfpService object, register callbacks, e.g. HfpService::cb_HfpSessionFactory, read known devices from a configuration file, and instantiate an HfpSession object for each with GetSession(). The HfpSession objects can be marked auto-reconnect, via RfcommSession::SetAutoReconnect(), so that they may be automatically connected when they enter radio range.

Whenever Hands-Free Profile service is active, HfpService maintains a listening socket for inbound HFP service level connections. Devices not previously known to HfpService may initiate connections, and will have HfpSession objects created for them. The HfpService client may control access by:

• Refusing to create HfpSession objects for unknown Bluetooth addresses, using HfpService::cb_HfpSessionFactory
• Forcing disconnections when devices initiate connections and their HfpSession objects enter the Connecting state, using HfpSession::cb_NotifyDeviceConnection
• Requiring authentication, using SetSecMode().

Authentication is managed at the system level and is beyond the scope of HfpService or HfpSession other than imposing a requirement that system authentication be upheld. Additionally, Bluetooth HFP 1.5 does not mandate any level of security on its RFCOMM connections.

---

Member Function Documentation

HfpSession * DefaultSessionFactory

(

BtDevice *

devp

)

Default factory method for HfpSession objects.

Clients wishing to override HfpService::cb_HfpSessionFactory may use this method to construct base HfpSession objects.

HfpSession* GetSession	(	BtDevice *	devp,
		bool	create = true
	)			[inline]

Look up and possibly create an HfpSession for a Bluetooth address.

This function can be used to search for an existing HfpSession object associated with a known Bluetooth address, and possibly create a new one if none is found.

Parameters:

	devp	BtDevice object with which the HfpSession must be associated.
	create	Set to true to create a new HfpSession for the target BtDevice if none already exists.

Returns:

The associated HfpSession object, which may have been newly constructed if create = true. NULL on memory allocation failure or other error.

Note:

If a session is found or created successfully, it is returned with an additional reference added to it, to prevent it from being inadvertently destroyed as per life cycle management. The caller is responsible for releasing the reference with HfpSession::Put().

Reimplemented from RfcommService.

HfpSession* GetSession	(	bdaddr_t const &	addr,
		bool	create = true
	)			[inline]

Look up and possibly create an HfpSession for a Bluetooth address.

This function can be used to search for an existing HfpSession object associated with a known Bluetooth address, and possibly create a new one if none is found.

Parameters:

[in]	addr	Bluetooth address of the device with which the HfpSession must be associated. A BtDevice object representing the address will be looked up and possibly created as the first step.
	create	Set to true to create a new HfpSession, and possibly a new BtDevice, if none already exists.

Returns:

The associated HfpSession object, which may have been newly constructed if create = true. NULL on memory allocation failure or other error.

Note:

If a session is found or created successfully, it is returned with an additional reference added to it, to prevent it from being inadvertently destroyed as per life cycle management. The caller is responsible for releasing the reference with HfpSession::Put().

Reimplemented from RfcommService.

HfpSession* GetSession	(	const char *	addrst,
		bool	create = true
	)			[inline]

Look up and possibly create an HfpSession for a Bluetooth address by address string.

This overload of GetDevice() is useful for configuration file parsing paths that create HfpSession objects for known devices. An ASCII hexadecimal Bluetooth address stored in a configuration file can be used directly by this routine.

Parameters:

[in]	addrst	Address of the device represented as a string, e.g. "00:07:61:D2:55:37" but not "Motorola" or "Logitech."
	create	Set to true to create a new HfpSession, and possibly a new BtDevice, if none already exists.

Returns:

The associated HfpSession object, which may have been newly constructed if create = true. NULL on memory allocation failure or other error.

Note:

If a session is found or created successfully, it is returned with an additional reference added to it, to prevent it from being inadvertently destroyed as per life cycle management. The caller is responsible for releasing the reference with HfpSession::Put().

Warning:

This function accepts a string representation of a Bluetooth address, e.g. "00:07:61:D2:55:37", NOT a Bluetooth name, e.g. "Motorola."

This function uses str2ba() to convert the string to a bdaddr_t, and malformed Bluetooth addresses are not reported.

Reimplemented from RfcommService.

HfpSession * Connect	(	BtDevice *	devp,
		ErrorInfo *	error = 0
	)

Initiate a connection to an audio gateway device with a known address.

This function will:

1. Search for an HfpSession record associated with a BtDevice. If none is found, one will be created.
2. Initiate an outbound connection on the resulting HfpSession, if it is in the Disconnected state. See HfpSession::Connect().
3. Return the HfpSession.

Parameters:

[in]	devp	BtDevice representing the target device.
[out]	error	Error information structure. If this method fails and returns 0, and error is not 0, error will be filled out with information on the cause of the failure.

Returns:

The HfpSession object associated with raddr, which is hopefully in the Connecting or Connected state, or 0 on failure.

Note:

If a device is found or created successfully, it is returned with an additional reference added to it, to prevent it from being inadvertently destroyed as per life cycle management. The caller is responsible for releasing the reference with HfpSession::Put().

See also:

GetDevice(), HfpSession::Connect()

HfpSession * Connect	(	bdaddr_t const &	addr,
		ErrorInfo *	error = 0
	)

Initiate a connection to an audio gateway device with a known address.

This function will:

1. Search for an HfpSession record associated with a Bluetooth address addr. If none is found, one will be created.
2. Initiate an outbound connection on the resulting HfpSession, if it is in the Disconnected state. See HfpSession::Connect().
3. Return the HfpSession.

Parameters:

[in]	addr	Bluetooth address of the device to be created and connected to.
[out]	error	Error information structure. If this method fails and returns 0, and error is not 0, error will be filled out with information on the cause of the failure.

Returns:

The HfpSession object associated with raddr, which is hopefully in the Connecting or Connected state, or 0 on failure.

Note:

If a device is found or created successfully, it is returned with an additional reference added to it, to prevent it from being inadvertently destroyed as per life cycle management. The caller is responsible for releasing the reference with HfpSession::Put().

See also:

GetDevice(), HfpSession::Connect()

HfpSession * Connect	(	const char *	addrstr,
		ErrorInfo *	error = 0
	)

Initiate a connection to an audio gateway device by Bluetooth address string.

This overload of Connect() is useful for configuration file parsing paths that initiate connections to known devices. An ASCII hexadecimal Bluetooth address stored in a configuration file can be used directly by this routine.

This function will:

1. Search for an HfpSession record associated with the provided Bluetooth address. If none is found, one will be created.
2. Initiate an outbound connection on the resulting HfpSession, if it is in the Disconnected state. See HfpSession::Connect().
3. Return the HfpSession.

Parameters:

[in]	addrstr	Address of the device represented as a string, e.g. "00:07:61:D2:55:37" but not "Motorola" or "Logitech."
[out]	error	Error information structure. If this method fails and returns 0, and error is not 0, error will be filled out with information on the cause of the failure.

Returns:

The HfpSession object associated with addrstr, which is hopefully in the Connecting or Connected state, or 0 on failure.

Note:

If a device is found or created successfully, it is returned with an additional reference added to it, to prevent it from being inadvertently destroyed as per life cycle management. The caller is responsible for releasing the reference with HfpSession::Put().

Warning:

This function accepts a string representation of a Bluetooth address, e.g. "00:07:61:D2:55:37", NOT a Bluetooth name, e.g. "Motorola."

This function uses str2ba() to convert the string to a bdaddr_t, and malformed Bluetooth addresses are not reported.

See also:

GetDevice(), HfpSession::Connect()

HfpSession* GetFirstSession

(

void

)

const [inline]

Query the first session object.

Returns:

The first HfpSession object associated with this service object, in enumeration order.

Note:

The HfpSession returned does not have a reference added to it. Callers should take care to avoid dangling pointers.

Reimplemented from BtService.

HfpSession* GetNextSession

(

HfpSession *

sessp

)

const [inline]

Query the next session object in enumeration order.

Returns:

The HfpSession object associated with this service object, following sessp in the enumeration order.

Note:

The HfpSession returned does not have a reference added to it. Callers should take care to avoid dangling pointers.

bool GetScoEnabled

(

void

)

const [inline]

Query whether SCO audio functionality is enabled.

This method retrieves the state of the SCO audio functionality. For more information, see SetScoEnabled().

bool SetScoEnabled	(	bool	sco_enable,
		ErrorInfo *	error = 0
	)

Set whether SCO audio functionality is enabled.

In some situations, it is desirable to use a different subsystem to handle SCO audio connections and audio processing. This option allows SCO audio support to be completely disabled, presumably so that libhfp may coexist with another subsystem that already handles SCO audio.

Unfortunately, this is not terribly useful. Most packages that implement SCO audio support do so properly in the sense of only permitting it with a service-level connection of some sort. The BlueZ 4.x audio components are an example of this.

If SCO support is enabled:

• A SCO listener socket will be registered, and bound to the local address of the selected HCI.
• Inbound SCO connections will be accepted for connected sessions, and notified through the session's HfpSession::cb_NotifyAudioConnection callback. For disconnected or incompletely connected sessions, SCO audio connections will be refused.
• Outbound SCO connection requests from connected HfpSession objects, through HfpSession::SndOpen(), will not automatically fail.

Parameters:

[in]	sco_enable	Set to true to enable SCO audio handling support, false to disable.
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	SCO enablement value successfully changed
	false	SCO enablement value could not be changed. This can be caused by attempting to enable SCO support when the HfpSession is active and the SCO listener socket could not be created. The reason for the failure will be reported through error, if error is not 0.

int GetCaps

(

void

)

const [inline]

Query advertised hands-free capabilities

bool SetCaps	(	int	caps,
		ErrorInfo *	error = 0
	)

Set advertised hands-free capabilities

const char* GetServiceName

(

void

)

const [inline]

Query service name advertised in SDP record

bool SetServiceName	(	const char *	desc,
		ErrorInfo *	error = 0
	)

Set service name advertised in SDP record

const char* GetServiceDesc

(

void

)

const [inline]

Query service description advertised in SDP record

bool SetServiceDesc	(	const char *	desc,
		ErrorInfo *	error = 0
	)

Set service description advertised in SDP record

rfcomm_secmode_t GetSecMode

(

void

)

const [inline, inherited]

Query the security mode of the listening socket.

Returns:

The security mode applied to the listening socket

Note:

The security mode set on the listening socket is also used for all new outbound connections.

See also:

SetSecMode()

bool SetSecMode	(	rfcomm_secmode_t	sec,
		ErrorInfo *	error = 0
	)			[inherited]

Set the security mode of the listening socket.

The security mode of the listening socket sets the security mode of all inbound connections. The RfcommSession and HfpSession objects also apply it to all outbound connections, and it is effectively used as policy for all RFCOMM connections.

Parameters:

[in]	sec	Security mode to be applied
[out]	error	Error information structure. If this method fails and returns false, and error is not 0, error will be filled out with information on the cause of the failure.

Return values:

	true	Security mode was successfully applied
	false	Error attempting to apply security mode

Note:

Changes to the security mode of the listening socket do not affect existing connections to audio gateway devices. Changes will take effect on the next inbound or outbound connection. To determine the security mode in effect for a specific connection, use HfpService::GetSecMode().

See also:

GetSecMode(), HfpSession::GetSecMode().

BtHub* GetHub

(

void

)

const [inline, inherited]

Query the presiding BtHub

DispatchInterface* GetDi

(

void

)

const [inline, inherited]

Query the dispatcher interface of the presiding BtHub

BtSession * GetNextSession

(

BtSession *

sessp

)

const [inherited]

Enumerate the next session associated with the service

---

Member Data Documentation

Callback<HfpSession*, BtDevice*> cb_HfpSessionFactory

Factory for HfpSession objects, implemented as a callback.

Clients of HfpService may use this callback to construct derivatives of HfpSession with additional functionality, or to pre-register callbacks before any of the object's methods are invoked.

This callback specifically violates the rule of not invoking callbacks in a nested fashion from client method calls, as it may be called nested from Connect() and GetDevice() with create=true. Clients choosing to receive this callback may not make additional HfpService / HfpSession method calls aside from constructors and DefaultSessionFactory().

Parameters:

baddr_t&

Bluetooth address of the device to be represented.

Returns:

Newly created HfpSession object representing the device, or NULL on failure.

---

The documentation for this class was generated from the following files:

• include/libhfp/hfp.h
• libhfp/hfp.cpp

---