HfpSession Class Reference
[Bluetooth Hands-Free Profile Implementation]

Session object for Hands-Free Profile. More...

#include <hfp.h>

Inheritance diagram for HfpSession:

[legend]

Collaboration diagram for HfpSession:

[legend]

List of all members.

Public Member Functions
HfpService *	GetService (void) const
	Query the service associated with the session.
bool	IsConnecting (void) const
	Query whether a connection attempt to the device is in progress.
bool	IsConnected (void) const
	Query whether the device is fully connected.
bool	IsConnectingAudio (void) const
	Query whether a voice audio (SCO) connection is being initiated.
bool	IsConnectedAudio (void) const
	Query whether a voice audio (SCO) connection is completed and available for audio streaming.
bool	Connect (ErrorInfo *error=0)
	Initiate a connection attempt to the device.
bool	HasConnectingCall (void) const
	Query whether the device has an incomplete outgoing call.
bool	HasEstablishedCall (void) const
	Query whether the device has an established call.
bool	HasWaitingCall (void) const
	Query whether the device has an incomplete incoming call.
const GsmClipResult *	WaitingCallIdentity (void) const
	Retrieve the caller ID value of the last incomplete call, either incoming or outgoing.
bool	GetServiceState (void) const
	Query whether the attached device has wireless service available.
int	GetSignalStrength (void) const
	Query the signal strength (bars) from an audio gateway.
int	GetRoaming (void) const
	Query whether the audio gateway is roaming.
int	GetBatteryCharge (void) const
	Query the battery charge level of the audio gateway.
bool	GetVoiceRecogActive (void) const
	Query the voice recognition state.
int	GetVolumeMic (void) const
	Query the microphone gain level.
int	GetVolumeSpeaker (void) const
	Query the speaker gain level.
bool	GetInBandRingToneEnable (void) const
	Query the in-band ring tone setting.
int	GetFeatures (void) const
	Query the feature bit set of the attached device.
bool	FeatureThreeWayCalling (void) const
	Query whether the attached device supports three-way calling.
bool	FeatureEcnr (void) const
	Query whether the attached device supports echo cancelation and/or noise reduction signal processing.
bool	FeatureVoiceRecog (void) const
	Query whether the attached device supports voice recognition.
bool	FeatureInBandRingTone (void) const
	Query whether the attached device supports in-band ringtones.
bool	FeatureRejectCall (void) const
	Query whether the attached device supports waiting call rejection.
bool	FeatureIndSignalStrength (void) const
	Query whether the attached device supports signal strength indication.
bool	FeatureIndRoaming (void) const
	Query whether the attached device supports roaming indication.
bool	FeatureIndBatteryCharge (void) const
	Query whether the attached device supports battery charge indication.
bool	IsCommandPending (void) const
	Query whether a service level command to the device is queued or otherwise pending completion.
HfpPendingCommand *	CmdQueryNumber (ErrorInfo *error=0)
	Query the telephone number of the audio gateway.
HfpPendingCommand *	CmdQueryOperator (ErrorInfo *error=0)
	Query operator information from the audio gateway.
HfpPendingCommand *	CmdQueryCurrentCalls (ErrorInfo *error=0)
	Query current calls from the audio gateway.
HfpPendingCommand *	CmdSetVoiceRecog (bool active, ErrorInfo *error=0)
	Request that the audio gateway activate or deactivate voice recognition.
HfpPendingCommand *	CmdAnswer (ErrorInfo *error=0)
	Request that the audio gateway answer the unanswered incoming call.
HfpPendingCommand *	CmdHangUp (ErrorInfo *error=0)
	Request that the audio gateway hang up the active call.
HfpPendingCommand *	CmdDial (const char *phnum, ErrorInfo *error=0)
	Request that the audio gateway place a new outgoing call.
HfpPendingCommand *	CmdRedial (ErrorInfo *error=0)
	Request that the audio gateway place a new outgoing call using the last dialed number.
HfpPendingCommand *	CmdSendDtmf (char code, ErrorInfo *error=0)
	Request that the audio gateway send a DTMF tone to the active call.
HfpPendingCommand *	CmdCallDropHeldUdub (ErrorInfo *error=0)
	Request that the audio gateway drop the held call, or reject the waiting call as User Declared User Busy.
HfpPendingCommand *	CmdCallSwapDropActive (ErrorInfo *error=0)
	Request that the audio gateway drop the active call and activate the held or waiting call.
HfpPendingCommand *	CmdCallDropIndex (unsigned int actnum, ErrorInfo *error=0)
	Drop a specific call.
HfpPendingCommand *	CmdCallSwapHoldActive (ErrorInfo *error=0)
	Request that the audio gateway hold the active call and activate the held or waiting call.
HfpPendingCommand *	CmdCallPrivateConsult (unsigned int callnum, ErrorInfo *error=0)
	Request private consultation mode with a call.
HfpPendingCommand *	CmdCallLink (ErrorInfo *error=0)
	Request that the audio gateway create a three-way call using the active call and the held or waiting call.
HfpPendingCommand *	CmdCallTransfer (ErrorInfo *error=0)
	Request that the audio gateway link the two calls and disconnect the subscriber from both calls.
bool	SndOpen (bool play, bool capture, ErrorInfo *error=0)
	Initiate an audio connection to the connected device.
void	SndClose (void)
	Disconnect the audio connection.
void	SndGetProps (SoundIoProps &props) const
	Query the SoundIo properties of the connected device.
void	SndGetFormat (SoundIoFormat &format) const
	Query the supported PCM format of the connected device.
bool	SndSetFormat (SoundIoFormat &format, ErrorInfo *error)
	Check whether a PCM format is compatible with the connected device.
bool	SndAsyncStart (bool play, bool capture, ErrorInfo *error)
	Initiate asynchronous audio handling.
void	SndAsyncStop (void)
	Halt asynchronous audio handling.
bool	SndIsAsyncStarted (void) const
	Query whether asynchronous audio handling is enabled.
rfcomm_secmode_t	GetSecMode (void) const
	Query the security mode of the connection to the device.
bool	IsAutoReconnect (void) const
	Query whether the autoreconnect mechanism is enabled for this device.
void	SetAutoReconnect (bool enable)
	Enable or disable the autoreconnect mechanism for this device.
bool	IsConnectionRemoteInitiated (void) const
	Query whether an in-progress or complete connection to the device was initiated by the device.
bool	IsPriorDisconnectVoluntary (void) const
	Query whether the last disconnection was voluntary or involuntary.
BtDevice *	GetDevice (void) const
	Query the BtDevice associated with the session.
void	Disconnect (bool voluntary=true)
	Request disconnection of the session.
BtHub *	GetHub (void) const
DispatchInterface *	GetDi (void) const
void *	GetPrivate (void) const
	Query the private pointer associated with the object.
void	SetPrivate (void *priv)
	Assign the private pointer associated with the object.
void	Get (void)
	Increment the reference count.
void	Put (void)
	Decrement the reference count.
Public Attributes
Callback< void, HfpSession *, ErrorInfo * >	cb_NotifyConnection
	Notification of an asynchronous change to the device connection state.
Callback< void, HfpSession *, ErrorInfo * >	cb_NotifyAudioConnection
	Notification of an asynchronous change to the voice audio connection state.
Callback< void, HfpSession *, bool, bool, bool >	cb_NotifyCall
	Notification of a change to the established call state.
Callback< void, HfpSession *, const char *, int >	cb_NotifyIndicator
	Notification of a change to a miscellaneous audio gateway state indicator.
Callback< void, HfpSession *, bool >	cb_NotifyVoiceRecog
	Notification of a change to the audio gateway's voice recognition state.
Callback< void, HfpSession *, bool, bool >	cb_NotifyVolume
	Notification of a change to the negotiated speaker or microphone gain level.
Callback< void, HfpSession *, bool >	cb_NotifyInBandRingTone
	Notification of a change to the audio gateway's in-band ring tone setting.
Callback< void, BtManaged * >	cb_NotifyDestroy
	Object destruction notification callback.

---

Detailed Description

Session object for Hands-Free Profile.

This class represents a Hands Free Profile session and connection to a remote audio gateway device (typically a cell phone). An HFP session through this object can allow the audio gateway to use a speakerphone facility provided by the local system. It supports numerous use cases:

• Interrogating the supported audio gateway features of the device
• Disseminating notifications from the device, e.g. signal strength
• Sending commands to the device, e.g. dial number, hangup
• Streaming audio to and from the device

Life Cycle

The associated HfpService object manages the life cycle of HfpSession objects. The HfpService keeps an index of HfpSession objects, and ensures that at most one exists per attached BtDevice device object. HfpSession objects may be instantiated through one of three paths:

• Through HfpService::GetSession(), with create = true. This method requires a reference to an existing BtDevice object, or other explicit knowledge of the Bluetooth address of the target device. This method will also only instantiate a new HfpSession object if one doesn't already exist for the associated BtDevice.
• Through HfpService::Connect(). This method is similar to HfpService::GetSession() above, but also initiates an outbound connection to the device.
• As part of an inbound connection, HfpService will automatically instantiate an HfpSession for the device if one does not already exist.

HfpSession objects are reference-counted Bluetooth managed objects, and are always destroyed under circumstances:

• Client reference count drops to zero. Put().
• The HfpSession is in the Disconnected state. See IsConnected(), IsConnecting().
• Auto-reconnect is not enabled. See RfcommSession::SetAutoReconnect().
• As with all managed objects, the actual destruction is performed in the context of a timer event.

The HfpSession class is designed so that clients may interact with it without defining derived classes. All notifications provided by HfpSession are performed through Callback callback objects.

Clients may override the instantiation path for HfpSession objects by registering their own factory method to HfpService::cb_HfpSessionFactory. As part of a specialized factory, clients may use the default factory method, HfpService::DefaultSessionFactory(). A specialized factory may be used to:

• Register all relevant callbacks with the HfpSession object from a single path, and before any may be invoked.
• Instantiate a class derived from HfpSession with additional functionality. This is recommended only as a last resort.

Callbacks

The HfpSession object provides numerous callbacks, and uses the Bluetooth module rules for non-nesting.

State

The session may be in one of three states:

• Disconnected: ! IsConnecting() && ! IsConnected()
• Connecting: IsConnecting()
• Connected: IsConnected()

When Disconnected or Connecting, none of the feature inquiries are meaningful, no state indicator and call state notifications will be delivered, the audio connection must be Disconnected, and no commands may be issued on the device.

Once connected, the device will accept commands, state indicator notifications will be delivered and certain values retained, and the voice audio channel may be connected.

---

Member Function Documentation

HfpService* GetService

(

void

)

const [inline]

Query the service associated with the session.

Returns:

A pointer to the BtService object associated with the session. A BtService object is not very useful, as the real service object is derived from BtServce, and added functionality is not exposed through BtService.

Reimplemented from RfcommSession.

bool IsConnecting

(

void

)

const [inline]

Query whether a connection attempt to the device is in progress.

Return values:

	true	A connection attempt is in progress
	false	The device is either fully connected or disconnected

See also:

IsConnected()

bool IsConnected

(

void

)

const [inline]

Query whether the device is fully connected.

Return values:

	true	The device is fully connected and accepting commands
	false	The device is not fully connected

See also:

IsConnecting()

bool IsConnectingAudio

(

void

)

const [inline]

Query whether a voice audio (SCO) connection is being initiated.

Return values:

	true	An audio connection is in progress but incomplete.
	false	An audio connection is complete or nonexistant.

See also:

IsConnectedAudio(), HfpSession::cb_NotifyAudioConnection

bool IsConnectedAudio

(

void

)

const [inline]

Query whether a voice audio (SCO) connection is completed and available for audio streaming.

Return values:

	true	Audio is connected and operational.
	false	Audio is disconnected or connecting.

See also:

IsConnectingAudio(), HfpSession::cb_NotifyAudioConnection

bool Connect

(

ErrorInfo *

error = 0

)

Initiate a connection attempt to the device.

This function will attempt to transition the device to the Connecting state. The process of connecting is always asynchronous, and if this function succeeds, a later transition to the Connected state will occur asynchronously after negotiation. As long as the client does not invoke Disconnect(), a future call to HfpSession::cb_NotifyConnection should be expected, to notify a transition to either the Connected or Disconnected state.

As a rule, no callbacks are invoked in a nested fashion from method calls. This function can affect the connection state, but will not directly generate a HfpSession::cb_NotifyConnection callback. Callers must notice state changes in-line.

Parameters:

[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	The connection attempt is in progress, and the device has transitioned to the Connecting state.
	false	The connection attempt failed. Reasons could include: The device is already connecting or connected. The local SDP daemon is unavailable. There are no available Bluetooth HCIs. The RFCOMM socket could not be created, e.g. because part or all of the bluetooth stack could not be loaded.

See also:

Disconnect(), RfcommSession::SetAutoReconnect()

HfpSession::cb_NotifyConnection

bool HasConnectingCall

(

void

)

const [inline]

Query whether the device has an incomplete outgoing call.

Return values:

	true	Unanswered outgoing call exists
	false	No unanswered outgoing call exists

bool HasEstablishedCall

(

void

)

const [inline]

Query whether the device has an established call.

Return values:

	true	Established call, either active or on hold, exists
	false	No established call exists

bool HasWaitingCall

(

void

)

const [inline]

Query whether the device has an incomplete incoming call.

Return values:

	true	Unanswered incoming call exists
	false	No unanswered incoming call exists

const GsmClipResult* WaitingCallIdentity

(

void

)

const [inline]

Retrieve the caller ID value of the last incomplete call, either incoming or outgoing.

Returns:

a GsmClipResult object containing the calling line identity, or NULL if the identity is not known, or there is no waiting or unanswered call. This object's contents are described in GSM 07.07 7.6. This object may be used until the global event handler is invoked again or CmdDial() / CmdRedial() is invoked.

bool GetServiceState

(

void

)

const [inline]

Query whether the attached device has wireless service available.

Queries the last value reported by the audio gateway for service availability.

Wireless service may be unavailable because the phone is out of range of a cell tower.

Note:

This function will only return meaningful values for connected devices that support service indication.

Return values:

	true	Service available
	false	Service unavailable

See also:

HfpSession::cb_NotifyIndicator

GSM 07.07 section 8.9

int GetSignalStrength

(

void

)

const [inline]

Query the signal strength (bars) from an audio gateway.

Queries the last value reported by the audio gateway for signal strength.

Returns:

An integer in the range 0-5, where 5 is the highest level of signal, or -1 if the signal strength is unknown.

Note:

This function will only return meaningful values for connected devices that support signal strength indication.

See also:

FeatureIndSignalStrength(), HfpSession::cb_NotifyIndicator

GSM 07.07 section 8.9

int GetRoaming

(

void

)

const [inline]

Query whether the audio gateway is roaming.

Queries the last value reported by the audio gateway for roaming.

Return values:

	0	Audio gateway is not roaming
	1	Audio gateway is roaming
	-1	Roaming state is unknown

Note:

This function will only return meaningful values for connected devices that support roaming indication.

See also:

FeatureIndRoaming(), HfpSession::cb_NotifyIndicator

GSM 07.07 section 8.9

int GetBatteryCharge

(

void

)

const [inline]

Query the battery charge level of the audio gateway.

Queries the last value reported by the audio gateway for battery charge level.

Returns:

An integer in the range 0-5, where 5 is the highest battery charge level, or -1 if the battery charge is unknown.

Note:

This function will only return meaningful values for connected devices that support battery charge indication.

See also:

FeatureIndBatteryCharge(), HfpSession::cb_NotifyIndicator

GSM 07.07 section 8.9

bool GetVoiceRecogActive

(

void

)

const [inline]

Query the voice recognition state.

If the audio gateway supports voice recognition, and is connected, it will use the microphone of the hands-free to listen for commands. Voice recognition can be activated directly on the audio gateway, or via CmdSetVoiceRecog(). Voice recognition can be deactivated when the audio gateway has recognized a voice command, when the audio gateway times out listening for a command, or via CmdSetVoiceRecog().

Audio gateway support for voice recognition can be tested via FeatureVoiceRecog().

Return values:

	true	Voice recognition activated
	false	Voice recognition deactivated or unsupported

Note:

This function will only return meaningful values when the device is in the connected state.

int GetVolumeMic

(

void

)

const [inline]

Query the microphone gain level.

If the audio gateway supports remote volume control, this method can be used to retrieve the microphone volume level synchronized with the audio gateway.

Returns:

The synchronized microphone volume level, 0-15, or -1 if the microphone volume level is unsynchronized.

int GetVolumeSpeaker

(

void

)

const [inline]

Query the speaker gain level.

If the audio gateway supports remote volume control, this method can be used to retrieve the speaker volume level synchronized with the audio gateway.

Returns:

The synchronized speaker volume level, 0-15, or -1 if the speaker volume level is unsynchronized.

bool GetInBandRingToneEnable

(

void

)

const [inline]

Query the in-band ring tone setting.

If the audio gateway supports in-band ring tones, it will send its in-band ring tone state on connection, and when it is changed. This accessor method can be used to query the last known value.

The in-band ring tone setting cannot be changed from the hands-free; it can only be set on the audio gateway.

Return values:

	0	In-band ring tones disabled or unsupported
	1	In-band ring tones enabled

Note:

This function will only return meaningful values when the device is in the connected state.

int GetFeatures

(

void

)

const [inline]

Query the feature bit set of the attached device.

This will return the raw reported features of the device, as defined in the Bluetooth Hands Free Profile specification. It is up to the client to interpret them. For simpler use, the FeatureXXX() methods are available, e.g. FeatureThreeWayCalling().

Returns:

The feature bit set reported by the device.

Note:

This function will only return meaningful values when the device is in the connected state.

bool FeatureThreeWayCalling

(

void

)

const [inline]

Query whether the attached device supports three-way calling.

If supported, CmdCallDropWaiting() may be used.

Note:

This information is only valid when the device is in the connected state.

Return values:

	true	Three way calling supported
	false	Three way calling not supported

bool FeatureEcnr

(

void

)

const [inline]

Query whether the attached device supports echo cancelation and/or noise reduction signal processing.

Note:

This information is only valid when the device is in the connected state.

Return values:

	true	EC/NR supported
	false	EC/NR not supported

bool FeatureVoiceRecog

(

void

)

const [inline]

Query whether the attached device supports voice recognition.

Note:

This information is only valid when the device is in the connected state.

Return values:

	true	Voice recognition supported
	false	Voice recognition not supported

bool FeatureInBandRingTone

(

void

)

const [inline]

Query whether the attached device supports in-band ringtones.

If the audio gateway supports in-band ringtones, it is able to play its own ringtone through the voice audio link, and will do so when in-band ringtones are enabled.

Note:

This information is only valid when the device is in the connected state.

Return values:

	true	In-band ringtones supported
	false	In-band ringtones not supported

bool FeatureRejectCall

(

void

)

const [inline]

Query whether the attached device supports waiting call rejection.

If supported, CmdCallDropWaiting() may be used.

Note:

This information is only valid when the device is in the connected state.

Return values:

	true	Call rejection supported
	false	Call rejection not supported

bool FeatureIndSignalStrength

(

void

)

const [inline]

Query whether the attached device supports signal strength indication.

If supported, the signal strength may be queried with GetSignalStrength().

Note:

This information is only valid when the device is in the connected state.

Return values:

	true	Signal strength indication supported
	false	Signal strength indication not supported

See also:

HfpSession::cb_NotifyIndicator

bool FeatureIndRoaming

(

void

)

const [inline]

Query whether the attached device supports roaming indication.

If roaming indication is supported, the roaming state may be queried with GetRoaming().

Note:

This information is only valid when the device is in the connected state.

Return values:

	true	Roaming state indication supported
	false	Roaming state indication not supported

See also:

HfpSession::cb_NotifyIndicator

bool FeatureIndBatteryCharge

(

void

)

const [inline]

Query whether the attached device supports battery charge indication.

If battery charge indication is supported, the battery charge state may be queried with GetBatteryCharge().

Note:

This information is only valid when the device is in the connected state.

Return values:

	true	Battery charge indication supported
	false	Battery charge indication not supported

See also:

HfpSession::cb_NotifyIndicator

bool IsCommandPending

(

void

)

const [inline]

Query whether a service level command to the device is queued or otherwise pending completion.

Return values:

	true	At least one command is pending
	false	The command queue is empty

HfpPendingCommand * CmdQueryNumber

(

ErrorInfo *

error = 0

)

Query the telephone number of the audio gateway.

Parameters:

[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

On success, the last parameter of the callback method to the resulting HfpPendingCommand object will be passed a GsmCnumResult structure. The object will be deleted after the callback method returns, so the callback method must duplicate the object if it wishes to reference it later.

HfpPendingCommand * CmdQueryOperator

(

ErrorInfo *

error = 0

)

Query operator information from the audio gateway.

Parameters:

[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

On success, the last parameter of the callback method to the resulting HfpPendingCommand object will be passed a GsmCopsResult structure. The object will be deleted after the callback method returns, so the callback method must duplicate the object if it wishes to reference it later.

HfpPendingCommand * CmdQueryCurrentCalls

(

ErrorInfo *

error = 0

)

Query current calls from the audio gateway.

Parameters:

[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

On success, the last parameter of the callback method to the resulting HfpPendingCommand object will be passed a pointer to a ListItem, which is the head of a list of GsmClccResult objects. The list head and all objects on the list will be deleted after the callback method returns, so the callback method must duplicate the objects that it wishes to reference later.

HfpPendingCommand * CmdSetVoiceRecog	(	bool	active,
		ErrorInfo *	error = 0
	)

Request that the audio gateway activate or deactivate voice recognition.

Note:

This command may only be expected to succeed if the device claims support for voice recognition, i.e. FeatureVoiceRecog() returns true.

Parameters:

[in]	active	Set to true to request activation of voice recognition mode, false to request deactivation.
[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

If successful, the cb_NotifyVoiceRecog callback will be invoked with the new voice recognition state.

HfpPendingCommand * CmdAnswer

(

ErrorInfo *

error = 0

)

Request that the audio gateway answer the unanswered incoming call.

Parameters:

[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

HfpPendingCommand * CmdHangUp

(

ErrorInfo *

error = 0

)

Request that the audio gateway hang up the active call.

Parameters:

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

Return values:

true

Command was queued

Returns:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

HfpPendingCommand * CmdDial	(	const char *	phnum,
		ErrorInfo *	error = 0
	)

Request that the audio gateway place a new outgoing call.

Parameters:

[in]	phnum	Phone number to be dialed
[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost or the phone number is too long

HfpPendingCommand * CmdRedial

(

ErrorInfo *

error = 0

)

Request that the audio gateway place a new outgoing call using the last dialed number.

The last dialed number is the number last dialed by the audio gateway, and may have been dialed before the audio gateway was connected to the hands-free.

Parameters:

[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

HfpPendingCommand * CmdSendDtmf	(	char	code,
		ErrorInfo *	error = 0
	)

Request that the audio gateway send a DTMF tone to the active call.

Parameters:

	code	DTMF code to be sent. May be numeric, #, or *.
[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.

Return values:

true

Command was queued

Returns:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

HfpPendingCommand * CmdCallDropHeldUdub

(

ErrorInfo *

error = 0

)

Request that the audio gateway drop the held call, or reject the waiting call as User Declared User Busy.

Note:

This command may only be expected to succeed if the device claims support for dropping waiting calls, i.e. FeatureDropHeldUdub() returns true.

Parameters:

[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

HfpPendingCommand * CmdCallSwapDropActive

(

ErrorInfo *

error = 0

)

Request that the audio gateway drop the active call and activate the held or waiting call.

Note:

This command may only be expected to succeed if the device supports active call drop-swapping, i.e. FeatureSwapDropActive() returns true.

Parameters:

[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

HfpPendingCommand * CmdCallDropIndex	(	unsigned int	actnum,
		ErrorInfo *	error = 0
	)

Drop a specific call.

Note:

This command may only be expected to succeed if the device supports dropping of specific calls, i.e. FeatureDropIndex() returns true.

Parameters:

[in]	actnum	Call number to be dropped
[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

HfpPendingCommand * CmdCallSwapHoldActive

(

ErrorInfo *

error = 0

)

Request that the audio gateway hold the active call and activate the held or waiting call.

Note:

This command may only be expected to succeed if the device supports active call hold-swapping, i.e. FeatureSwapHoldActive() returns true.

Parameters:

[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

HfpPendingCommand * CmdCallPrivateConsult	(	unsigned int	callnum,
		ErrorInfo *	error = 0
	)

Request private consultation mode with a call.

Note:

This command may only be expected to succeed if the device supports private consultation mode, i.e. FeaturePrivateConsult() returns true.

Parameters:

[in]	callnum	Call number to be made the active call
[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

HfpPendingCommand * CmdCallLink

(

ErrorInfo *

error = 0

)

Request that the audio gateway create a three-way call using the active call and the held or waiting call.

Note:

This command may only be expected to succeed if the device supports call linking, i.e. FeatureLink() returns true.

Parameters:

[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

HfpPendingCommand * CmdCallTransfer

(

ErrorInfo *

error = 0

)

Request that the audio gateway link the two calls and disconnect the subscriber from both calls.

Note:

This command may only be expected to succeed if the device supports explicit call transfer, i.e. FeatureTransfer() returns true.

Parameters:

[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:

An HfpPendingCommand to receive a notification when the command completes, with the command status, or 0 if the command could not be queued, e.g. because the device connection was lost

bool SndOpen	(	bool	play,
		bool	capture,
		ErrorInfo *	error = 0
	)

Initiate an audio connection to the connected device.

This method will initiate an outbound audio connection to the connected device.

Parameters:

[in]	play	Must be true
[in]	capture	Must be true
[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	Audio connection has been initiated. The connection will be incomplete, i.e. IsConnectingAudio(), and a callback to HfpSession::cb_NotifyAudioConnection will be pending.
	false	Audio is either already connected, the connection attempt failed, or the play and/or capture parameters were false.

Note:

If SCO audio support is disabled at the service level, this method will fail. See HfpService::SetScoEnabled().

void SndClose

(

void

)

Disconnect the audio connection.

Closes an existing audio connection, or cancels a pending audio connection.

As a rule, no callbacks are invoked in a nested fashion from method calls. This method is no exception and does not result in a call to either HfpSession::cb_NotifyAudioConnection or SoundIo::cb_NotifyPacket.

void SndGetProps

(

SoundIoProps &

props

)

const

Query the SoundIo properties of the connected device.

This method is provided as part of the audio handling interface.

void SndGetFormat

(

SoundIoFormat &

format

)

const

Query the supported PCM format of the connected device.

This method is provided as part of the audio handling interface.

bool SndSetFormat	(	SoundIoFormat &	format,
		ErrorInfo *	error
	)

Check whether a PCM format is compatible with the connected device.

This method is provided as part of the audio handling interface.

bool SndAsyncStart	(	bool	play,
		bool	capture,
		ErrorInfo *	error
	)

Initiate asynchronous audio handling.

Initiates periodic callbacks to SoundIo::cb_NotifyPacket as audio packets are sent to/received from the connected device.

Parameters:

[in]	play	Must be true
[in]	capture	Must be true
[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	Asynchronous audio handling has been enabled. Expect future callbacks to SoundIo::cb_NotifyPacket.
	false	Error enabling asynchronous audio handling. Reasons might include: Audio connection is not established, i.e. IsConnectedAudio() The play and/or capture parameters were false.

void SndAsyncStop

(

void

)

Halt asynchronous audio handling.

This method is provided as part of the audio handling interface.

bool SndIsAsyncStarted

(

void

)

const [inline]

Query whether asynchronous audio handling is enabled.

This method is provided as part of the audio handling interface.

rfcomm_secmode_t GetSecMode

(

void

)

const [inline, inherited]

Query the security mode of the connection to the device.

For information on the security mode, see rfcomm_secmode_t.

If the device is connected, this accessor will return the security mode associated with the socket.

Security modes are configured at the service level, as they must be set at the socket level prior to connection in order to take effect. For inbound connections, the service object is the keeper of the one listening socket that accepts inbound connections and assigns their security modes.

While it may be possible to try to manage security modes at the level of each session, at least for outbound connections, no compelling reasons have been identified at the time of this writing and management only at the level of the service is supported.

Returns:

The security mode applied to the service-level socket, if the device is in the Connecting or Connected state. If Disconnected, the return value is undefined.

See also:

RfcommService::SetSecMode()

bool IsAutoReconnect

(

void

)

const [inline, inherited]

Query whether the autoreconnect mechanism is enabled for this device.

Return values:

	true	Autoreconnect is enabled
	false	Autoreconnect is disabled.

See also:

SetAutoReconnect()

void SetAutoReconnect

(

bool

enable

)

[inherited]

Enable or disable the autoreconnect mechanism for this device.

If enabled, whenever the device is disconnected, a reconnection attempt will be made periodically through a timer. Auto-reconnection is useful for devices such as phones that regularly move in and out of range.

This function can affect the life cycle management of the object it is called on.

Parameters:

enable

Set to true to enable, false to disable.

See also:

IsAutoReconnect(), Connect()

bool IsConnectionRemoteInitiated

(

void

)

const [inline, inherited]

Query whether an in-progress or complete connection to the device was initiated by the device.

This is useful for connection auditing logic, e.g. to refuse connections from unknown devices.

Return values:

	true	The device initiated the connection
	false	The local UI or autoreconnect mechanism initiated the connection

bool IsPriorDisconnectVoluntary

(

void

)

const [inline, inherited]

Query whether the last disconnection was voluntary or involuntary.

When a connection is explicitly broken, e.g. selecting a disconnect function on the device or calling Disconnect(), it is considered voluntary. When a connection fails for implicit reasons such as a device moving out of radio range or an HCI being disconnected, it is considered involuntary. This function reports whether the last transition from the Connecting or Connected state to the Disconnected state was voluntary.

Return values:

	true	The last transition to the Disconnected state was voluntary.
	false	The last transition to the Disconnected state was involuntary.

Note:

This information is useful for deciding whether to disable auto-reconnection of a service to a particular device.

BtDevice* GetDevice

(

void

)

const [inline, inherited]

Query the BtDevice associated with the session.

Returns:

A pointer to the BtDevice to which the session is attached.

Note:

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

void Disconnect

(

bool

voluntary = true

)

[inline, inherited]

Request disconnection of the session.

This abstract interface allows one to request any connection-oriented session object derived from BtSession to disconnect itself.

Parameters:

voluntary

Whether the disconnection should be presented as voluntary and explicit, i.e. selecting disconnect on a list, or involuntary, i.e. exiting Bluetooth radio range.

BtHub* GetHub

(

void

)

const [inline, inherited]

Query the presiding BtHub

DispatchInterface* GetDi

(

void

)

const [inline, inherited]

Query the dispatcher interface of the presiding BtHub

void* GetPrivate

(

void

)

const [inline, inherited]

Query the private pointer associated with the object.

All BtManaged derived objects have a single pointer field reserved for the use of clients. It is always initialized to zero when the object is constructed, and clients may assign it as they wish.

Returns:

The current value of the private pointer

void SetPrivate

(

void *

priv

)

[inline, inherited]

Assign the private pointer associated with the object.

All BtManaged derived objects have a single pointer field reserved for the use of clients. It is always initialized to zero when the object is constructed, and clients may assign it as they wish.

Parameters:

priv

New value to assign to the private pointer

void Get

(

void

)

[inline, inherited]

Increment the reference count.

As per managed objects, BtManaged derived objects are not deleted so long as they have a positive reference count.

See also:

Put()

void Put

(

void

)

[inherited]

Decrement the reference count.

As per managed objects, when the object's reference count reaches zero, the object will be destroyed in the context of a timer event.

See also:

Get()

---

Member Data Documentation

Callback<void, HfpSession *, ErrorInfo *> cb_NotifyConnection

Notification of an asynchronous change to the device connection state.

The connection state, from the perspective of HfpSession clients, has three states:

• Disconnected: ! IsConnecting() && ! IsConnected()
• Connecting: IsConnecting()
• Connected: IsConnected()

The audio gateway may transition from Disconnected to Connecting, from Connecting to Connected, and from either Connecting or Connected to Disconnected. There is no legal transition directly from Disconnected to Connected.

As a rule, no callbacks are invoked in a nested fashion from method calls. State changes effected directly by Connect() and Disconnect() are not reported through this mechanism, and clients must notice such state changes directly. State changes caused by connections initiated by the audio gateway or the auto-reconnect mechanism, connections that have completed negotiation, and connection attempts that have failed for reasons other than Disconnect() are reported.

For example, if a HfpSession object in the Disconnected state has its Connect() method invoked, it will transition to the Connecting state, but no notification will be generated through HfpSession::cb_NotifyConnection. Later, after negotiation completes, and the object transitions to the Connected state, a notification WILL be generated because the event causing the transition was system-generated and while it may have been the result of an earlier call to Connect(), the notification is not being generated from directly underneath that call.

The transition to the Connected state is always done from the Connecting state, and will always be notified through this callback. Because most queries and commands cannot be made of the device until it enters the Connected state, it is critical that clients receive notification of it.

Parameters:

	HfpSession*	The HfpSession object that has had an asynchronous state transition to its service-level connection.
	error	Error information structure. If the state transition was to the Disconnected state, the ErrorInfo* parameter is nonzero, and contains information about why the connection was lost. Otherwise, it is 0.

See also:

IsConnecting(), IsConnected(), IsConnectionRemoteInitiated(), IsPriorDisconnectVoluntary().

Callback<void, HfpSession*, ErrorInfo*> cb_NotifyAudioConnection

Notification of an asynchronous change to the voice audio connection state.

The voice audio connection states include:

• Disconnected: ! IsConnectingAudio() && ! IsConnectedAudio()
• Connecting: IsConnectingAudio()
• Connected: IsConnectedAudio()

Similar to the device connection state, the audio connection state can transition from Disconnected to Connecting, e.g. by SoundIo::SndOpen() or a remote connection attempt. It can transition from Connecting to Connected following negotiation. It can transition from Connecting or Connected to Disconnected by SoundIo::SndClose() or Disconnect(). It cannot transition directly from Disconnected to Connected.

As a rule, no callbacks are invoked in a nested fashion from method calls. Similar to HfpSession::cb_NotifyConnection, this callback is only invoked on asynchronous changes to the audio connection state above and never directly through method calls.

The audio connection will always be Disconnected whenever the device is not Connected.

Parameters:

	HfpSession*	The HfpSession object that has had an asynchronous state transition to its audio connection.
	error	Error information structure. If the state transition of the device audio was to the Disconnected state, the ErrorInfo* parameter is nonzero, and contains information about why the audio connection was lost. Otherwise, it is 0.

See also:

IsConnectingAudio(), IsConnectedAudio()

Callback<void, HfpSession *, bool, bool, bool> cb_NotifyCall

Notification of a change to the established call state.

Parameters:

	HfpSession*	Pointer to the HfpSession originating the call. Largely redundant as Callback can store and substitute parameters.
	bool	Set to true if the device's active call state has changed. Use HasEstablishedCall() to test wiether an established call exists or not.
	bool	Set to true if the device's waiting or held call state has changed. Use HasConnectingCall() to test whether an outbound call is in progress, and HasWaitingCall() to test whether an inbound call is ready to be answered. Use WaitingCallIdentity() to retrieve the Caller ID value provided in the case of an incoming call.
	bool	Set to true when the device signals a ring. Clients may use this to play a ring tone or execute alerting activity.

Note:

In the place of a single ring notification, this notification may be triggered twice in short succession, initially without a known calling line identity, and then with identity.

See also:

HasEstablishedCall(), HasConnectingCall(), HasWaitingCall(), WaitingCallIdentity()

Callback<void, HfpSession *, const char *, int> cb_NotifyIndicator

Notification of a change to a miscellaneous audio gateway state indicator.

Parameters:

	char*	Name of indicator
	int	New value of indicator

Some well-known indicator names include:

• "service" -- (0,1) depending on the state of wireless service to the audio gateway. This value is also reported by GetServiceState().
• "roam" -- (0,1) depending on whether the audio gateway is "roaming". This value is also reported by GetRoaming().
• "signal" -- (0-5) where 5 is the best wireless signal quality to the audio gateway. This value is also reported by GetSignalStrength().
• "battchg" -- (0-5) where 5 is the highest level of battery charge on the audio gateway. This value is also reported by GetBatteryCharge().

See also:

GSM 07.07 section 8.9

Callback<void, HfpSession *, bool> cb_NotifyVoiceRecog

Notification of a change to the audio gateway's voice recognition state.

Parameters:

bool

Set to true if the audio gateway has activated voice recognition mode, false otherwise

The last known voice recognition state can also be accessed via GetVoiceRecogActive(). Activation or deactivation can be requested via CmdSetVoiceRecog().

See also:

Bluetooth HFP v1.5 section 4.25

Callback<void, HfpSession *, bool, bool> cb_NotifyVolume

Notification of a change to the negotiated speaker or microphone gain level.

Parameters:

	bool1	Set to true if the microphone gain level has been changed by audio gateway
	bool2	Set to true if the speaker gain level has been changed by audio gateway

The gain values can be accessed via GetVolumeMic() and GetVolumeSpeaker().

See also:

Bluetooth HFP v1.5 section 4.28

Callback<void, HfpSession *, bool> cb_NotifyInBandRingTone

Notification of a change to the audio gateway's in-band ring tone setting.

Parameters:

bool

Set to true if the audio gateway has enabled in-band ring tones, false otherwise

The in-band ring tone setting can also be accessed via GetInBandRingToneEnable()

See also:

Bluetooth HFP v1.5 section 4.13.4

Callback<void, BtManaged*> cb_NotifyDestroy [inherited]

Object destruction notification callback.

This callback is invoked proir to deletion of the managed object, so that clients may release associated resources. This callback occurs in the context of a timer event, and complies with the rule of not invoking client callbacks in a nested fashion.

The decision to destroy the object is final. The client may not attempt to preserve the object by acquiring additional references from this callback.

---

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

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

---