HfpSession Class Reference
[Bluetooth Hands-Free Profile Implementation]

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

#include <hfp.h>

Inheritance diagram for HfpSession:

Inheritance graph
[legend]
Collaboration diagram for HfpSession:

Collaboration graph
[legend]

List of all members.

Public Member Functions

HfpServiceGetService (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.
HfpPendingCommandCmdQueryNumber (ErrorInfo *error=0)
 Query the telephone number of the audio gateway.
HfpPendingCommandCmdQueryOperator (ErrorInfo *error=0)
 Query operator information from the audio gateway.
HfpPendingCommandCmdQueryCurrentCalls (ErrorInfo *error=0)
 Query current calls from the audio gateway.
HfpPendingCommandCmdSetVoiceRecog (bool active, ErrorInfo *error=0)
 Request that the audio gateway activate or deactivate voice recognition.
HfpPendingCommandCmdAnswer (ErrorInfo *error=0)
 Request that the audio gateway answer the unanswered incoming call.
HfpPendingCommandCmdHangUp (ErrorInfo *error=0)
 Request that the audio gateway hang up the active call.
HfpPendingCommandCmdDial (const char *phnum, ErrorInfo *error=0)
 Request that the audio gateway place a new outgoing call.
HfpPendingCommandCmdRedial (ErrorInfo *error=0)
 Request that the audio gateway place a new outgoing call using the last dialed number.
HfpPendingCommandCmdSendDtmf (char code, ErrorInfo *error=0)
 Request that the audio gateway send a DTMF tone to the active call.
HfpPendingCommandCmdCallDropHeldUdub (ErrorInfo *error=0)
 Request that the audio gateway drop the held call, or reject the waiting call as User Declared User Busy.
HfpPendingCommandCmdCallSwapDropActive (ErrorInfo *error=0)
 Request that the audio gateway drop the active call and activate the held or waiting call.
HfpPendingCommandCmdCallDropIndex (unsigned int actnum, ErrorInfo *error=0)
 Drop a specific call.
HfpPendingCommandCmdCallSwapHoldActive (ErrorInfo *error=0)
 Request that the audio gateway hold the active call and activate the held or waiting call.
HfpPendingCommandCmdCallPrivateConsult (unsigned int callnum, ErrorInfo *error=0)
 Request private consultation mode with a call.
HfpPendingCommandCmdCallLink (ErrorInfo *error=0)
 Request that the audio gateway create a three-way call using the active call and the held or waiting call.
HfpPendingCommandCmdCallTransfer (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.
BtDeviceGetDevice (void) const
 Query the BtDevice associated with the session.
void Disconnect (bool voluntary=true)
 Request disconnection of the session.
BtHubGetHub (void) const
DispatchInterfaceGetDi (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:

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:

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

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:

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:

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:

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:

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:

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:
Generated on Fri Jan 9 05:58:39 2009 for libhfp by  doxygen 1.5.4