Hands Free Profile (HFP)

Files
file	wiced_bt_hfp_hf.h

Data Structures
struct	wiced_bt_hfp_hf_call_data_t
struct	wiced_bt_hfp_hf_event_data_t
struct	wiced_bt_hfp_hf_volume_data_t

Typedefs
typedef void(*	wiced_bt_hfp_hf_event_cb_t )(wiced_bt_hfp_hf_event_t event, wiced_bt_hfp_hf_event_data_t *p_data)

Enumerations
enum	wiced_bt_hfp_ag_supported_features_t
enum	wiced_bt_hfp_hf_call_action_t {   WICED_BT_HFP_HF_CALL_ACTION_DIAL, WICED_BT_HFP_HF_CALL_ACTION_ANSWER, WICED_BT_HFP_HF_CALL_ACTION_HANGUP, WICED_BT_HFP_HF_CALL_ACTION_HOLD_0,   WICED_BT_HFP_HF_CALL_ACTION_HOLD_1, WICED_BT_HFP_HF_CALL_ACTION_HOLD_2 }
enum	wiced_bt_hfp_hf_callsetup_state_t {   WICED_BT_HFP_HF_CALLSETUP_STATE_IDLE, WICED_BT_HFP_HF_CALLSETUP_STATE_INCOMING, WICED_BT_HFP_HF_CALLSETUP_STATE_DIALING, WICED_BT_HFP_HF_CALLSETUP_STATE_ALERTING,   WICED_BT_HFP_HF_CALLSETUP_STATE_WAITING }
enum	wiced_bt_hfp_hf_connection_state_t { WICED_BT_HFP_HF_STATE_DISCONNECTED, WICED_BT_HFP_HF_STATE_CONNECTED, WICED_BT_HFP_HF_STATE_SLC_CONNECTED }
enum	wiced_bt_hfp_hf_event_t {   WICED_BT_HFP_HF_CONNECTION_STATE_EVT, WICED_BT_HFP_HF_AG_FEATURE_SUPPORT_EVT, WICED_BT_HFP_HF_SERVICE_STATE_EVT, WICED_BT_HFP_HF_SERVICE_TYPE_EVT,   WICED_BT_HFP_HF_CALL_SETUP_EVT, WICED_BT_HFP_HF_RING_EVT, WICED_BT_HFP_HF_INBAND_RING_STATE_EVT, WICED_BT_HFP_HF_RSSI_IND_EVT,   WICED_BT_HFP_HF_BATTERY_STATUS_IND_EVT, WICED_BT_HFP_HF_VOLUME_CHANGE_EVT, WICED_BT_HFP_HF_CLIP_IND_EVT, WICED_BT_HFP_HF_AT_RESULT_CODE_IND_EVT }
enum	wiced_bt_hfp_hf_inband_ring_state_t { WICED_BT_HFP_HF_INBAND_RING_DISABLED, WICED_BT_HFP_HF_INBAND_RING_ENABLED }
enum	wiced_bt_hfp_hf_service_state_t { WICED_BT_HFP_HF_SERVICE_STATE_NOT_AVAILABLE, WICED_BT_HFP_HF_SERVICE_STATE_AVAILABLE }
enum	wiced_bt_hfp_hf_service_type_t { WICED_BT_HFP_HF_SERVICE_TYPE_HOME, WICED_BT_HFP_HF_SERVICE_TYPE_ROAMING }
enum	wiced_bt_hfp_hf_supported_features_t
enum	wiced_bt_hfp_hf_volume_type_t { WICED_BT_HFP_HF_SPEAKER, WICED_BT_HFP_HF_MIC }

Functions
wiced_result_t	wiced_bt_hfp_hf_connect (wiced_bt_device_address_t bd_address)
wiced_result_t	wiced_bt_hfp_hf_deinit (void)
wiced_result_t	wiced_bt_hfp_hf_disconnect (wiced_bt_device_address_t bd_address)
wiced_result_t	wiced_bt_hfp_hf_init (wiced_bt_hfp_hf_config_data_t *p_config_data, wiced_bt_hfp_hf_event_cb_t event_cb)
wiced_result_t	wiced_bt_hfp_hf_notify_volume (wiced_bt_device_address_t bd_address, wiced_bt_hfp_hf_volume_type_t volume_type, uint8_t volume_level)
wiced_result_t	wiced_bt_hfp_hf_perform_call_action (wiced_bt_device_address_t bd_address, wiced_bt_hfp_hf_call_action_t action, char *number)
wiced_result_t	wiced_bt_hfp_hf_send_at_cmd (wiced_bt_device_address_t bd_address, char *at_cmd)

Detailed Description

The profile defines how two devices supporting the Hands-Free Profile shall interact with each other on a point-to-point basis. An implementation of the Hands-Free Profile typically enables a headset, or an embedded hands-free unit to connect, wirelessly, to a cellular phone for the purposes of acting as the cellular phone's audio input and output mechanism and allowing typical telephony functions to be performed without access to the actual phone.

The most common examples of such devices are in-car Hands-Free units used together with cellular phones, or wearable wireless headsets.

Typedef Documentation

typedef void(* wiced_bt_hfp_hf_event_cb_t)(wiced_bt_hfp_hf_event_t event, wiced_bt_hfp_hf_event_data_t *p_data)

HF control path callback type

Application implements callback of this type to receive HF events and commands.

Parameters

event	HF event.
p_data	pointer to event data.

Returns

none

Enumeration Type Documentation

enum wiced_bt_hfp_ag_supported_features_t

AG supported feature flags.

enum wiced_bt_hfp_hf_call_action_t

Call action command

Enumerator
WICED_BT_HFP_HF_CALL_ACTION_DIAL	Place an outgoing call request
WICED_BT_HFP_HF_CALL_ACTION_ANSWER	Answer an incoming call
WICED_BT_HFP_HF_CALL_ACTION_HANGUP	Hangup an active call, reject an incoming call, end an outgoing call (which is being setup)
WICED_BT_HFP_HF_CALL_ACTION_HOLD_0	Release a held call, or reject a waiting call (UDUB)
WICED_BT_HFP_HF_CALL_ACTION_HOLD_1	Release active call and activate a held or waiting call
WICED_BT_HFP_HF_CALL_ACTION_HOLD_2	Place active call on hold, and accept a waiting call or retrieve a held call

enum wiced_bt_hfp_hf_callsetup_state_t

States of a call during setup procedure

Enumerator
WICED_BT_HFP_HF_CALLSETUP_STATE_IDLE	No call set up in progress
WICED_BT_HFP_HF_CALLSETUP_STATE_INCOMING	There is an incoming call
WICED_BT_HFP_HF_CALLSETUP_STATE_DIALING	Outgoing call is being setup up
WICED_BT_HFP_HF_CALLSETUP_STATE_ALERTING	Remote party is being alterted of the call
WICED_BT_HFP_HF_CALLSETUP_STATE_WAITING	Incoming call is waiting (received when a call is already active)

enum wiced_bt_hfp_hf_connection_state_t

HF Control Connection States

Enumerator
WICED_BT_HFP_HF_STATE_DISCONNECTED	HF control connection is closed
WICED_BT_HFP_HF_STATE_CONNECTED	HF control connection established
WICED_BT_HFP_HF_STATE_SLC_CONNECTED	HF synchronized with AG's state, ready to send/recive commands/notifications

enum wiced_bt_hfp_hf_event_t

HF Events. These are received via wiced_bt_hfp_hf_event_cb_t() callback function. See wiced_bt_hfp_hf_event_data_t for payload.

Enumerator
WICED_BT_HFP_HF_CONNECTION_STATE_EVT	Received on control path connection state change
WICED_BT_HFP_HF_AG_FEATURE_SUPPORT_EVT	Indicates HFP features supported in AG
WICED_BT_HFP_HF_SERVICE_STATE_EVT	Indicates AG's cellular network connection state
WICED_BT_HFP_HF_SERVICE_TYPE_EVT	Indicates whether AG is connected to home or romaing network
WICED_BT_HFP_HF_CALL_SETUP_EVT	Received when there is a change in call state, e.g., incoming call, call termination
WICED_BT_HFP_HF_RING_EVT	Ring indication (during incoming call) received
WICED_BT_HFP_HF_INBAND_RING_STATE_EVT	Indicates if the AG supports sending the ring-tone to HF over audio connection
WICED_BT_HFP_HF_RSSI_IND_EVT	Indicates AG's cellular signal strength
WICED_BT_HFP_HF_BATTERY_STATUS_IND_EVT	Indicates AG's battery status
WICED_BT_HFP_HF_VOLUME_CHANGE_EVT	Received when there is a change in the microphone or speaker volume is changed by AG
WICED_BT_HFP_HF_CLIP_IND_EVT	Indicates calling line identification name/number
WICED_BT_HFP_HF_AT_RESULT_CODE_IND_EVT	Indicates the result code from AG

enum wiced_bt_hfp_hf_inband_ring_state_t

In-band ring tone setting in AG

Enumerator
WICED_BT_HFP_HF_INBAND_RING_DISABLED	AG will not send ring-tone thru an audio connection, HF should use some means to alert the user of an incoming call
WICED_BT_HFP_HF_INBAND_RING_ENABLED	AG will send the ring-tone thru an audio connection

enum wiced_bt_hfp_hf_service_state_t

AG's serivce states

Enumerator
WICED_BT_HFP_HF_SERVICE_STATE_NOT_AVAILABLE	AG's cellular services not available
WICED_BT_HFP_HF_SERVICE_STATE_AVAILABLE	AG is connected to cellular services

enum wiced_bt_hfp_hf_service_type_t

AG's serivce type

Enumerator
WICED_BT_HFP_HF_SERVICE_TYPE_HOME	AG is connected to home network
WICED_BT_HFP_HF_SERVICE_TYPE_ROAMING	AG is connected to a romaing network

enum wiced_bt_hfp_hf_supported_features_t

HF device supported feature flags.

enum wiced_bt_hfp_hf_volume_type_t

Audio input/output device on the HF Device

Enumerator
WICED_BT_HFP_HF_SPEAKER	Refers to speaker on the HF Device
WICED_BT_HFP_HF_MIC	Refers to microphone on the HF Device

Function Documentation

wiced_result_t wiced_bt_hfp_hf_connect

(

wiced_bt_device_address_t

bd_address

)

API to initiate a HFP connection to an AG

Called by the application to connect to an AG with the given address.

Parameters

bd_address

BD address of the AG.

Returns

wiced_result_t (WICED_BT_XXX)

wiced_result_t wiced_bt_hfp_hf_deinit

(

void

)

API to deregister the HFP-HF component from the stack and to cleanup the internal data structures.

Called by the application when the HFP-HF component is no longer needed by it.

Returns

wiced_result_t (WICED_BT_XXX)

wiced_result_t wiced_bt_hfp_hf_disconnect

(

wiced_bt_device_address_t

bd_address

)

API to disconnect from an AG

Called by the application to disconnect from an AG with the given address.

Parameters

bd_address

BD address of the AG.

Returns

wiced_result_t (WICED_BT_XXX)

wiced_result_t wiced_bt_hfp_hf_init	(	wiced_bt_hfp_hf_config_data_t *	p_config_data,
		wiced_bt_hfp_hf_event_cb_t	event_cb
	)

API to initialize the HFP-HF component and register with the stack.

Called by the application before any other API is called. Application provides the SINK configuration data and callback to receive control events.

Parameters

num_server	Number of Handsfree server to be created
a_config_data	HF configuration parameters array for each server. See wiced_bt_hfp_hf_config_data_t.
event_cb	Callback function for receiving HF events.

Returns

wiced_result_t (WICED_BT_XXX)

wiced_result_t wiced_bt_hfp_hf_notify_volume	(	wiced_bt_device_address_t	bd_address,
		wiced_bt_hfp_hf_volume_type_t	volume_type,
		uint8_t	volume_level
	)

API to send the current speaker/mic volume level to AG

Called by the application to notify the AG of the change in volume of mic or speaker.

Parameters

bd_address	BD address of the AG.
volume_type	Mic or speaker for which the volume was changed.
volume_level	Volume level from 0 to 15.

Returns

wiced_result_t (WICED_BT_XXX)

wiced_result_t wiced_bt_hfp_hf_perform_call_action	(	wiced_bt_device_address_t	bd_address,
		wiced_bt_hfp_hf_call_action_t	action,
		char *	number
	)

API to manipulate a call (i.e., to answer, hold, hangup, reject, etc)

Allows the application to take actions indicated in wiced_bt_hfp_hf_call_action_t.

Parameters

bd_address	BD address of the AG
action	Action to be initiated, see wiced_bt_hfp_hf_call_action_t.
number	Contains a NUL terminated number to be called, if NULL, the last number redial (LNR) is initiated. valid when action is WICED_BT_HFP_HF_CALL_ACTION_DIAL, for all other actions this is ignored.

Returns

wiced_result_t (WICED_BT_XXX)

wiced_result_t wiced_bt_hfp_hf_send_at_cmd	(	wiced_bt_device_address_t	bd_address,
		char *	at_cmd
	)

API to send the at command to the AG

Called by the application to send an at command to AG. The command sent is pass thru for library. The response is received thru WICED_BT_HFP_HF_AT_RESULT_CODE_IND_EVT.

Parameters

bd_address	BD address of the AG.
at_cmd	Null terminated at command string to be sent to AG.

Returns

wiced_result_t (WICED_BT_XXX)