# Bluetooth® HFP Client API

## Overview

HFP (Hands-Free Profile) Client API provides functions to enable a Bluetooth device to act as an HFP Client, allowing communication with an Audio Gateway (AG) device, such as a smartphone, to handle voice calls, volume control, and other hands-free operations.

## Application Examples

- bluetooth/bluedroid/classic_bt/hfp_hf demonstrates how to use the Hands-Free Client Component to communicate with a device that implements Hands-Free Audio Gateway (HF-AG), such as a smartphone.

## API Reference

### Header File

- components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h

- This header file can be included with:

  >     #include "esp_hf_client_api.h"

- This header file is a part of the API provided by the `bt` component. To declare that your component depends on `bt`, add the following to your CMakeLists.txt:

  >     REQUIRES bt

  > or

  >     PRIV_REQUIRES bt

### Functions

esp_err_t esp_hf_client_register_callback(esp_hf_client_cb_t callback)

  Register application callback function to HFP client module. This function should be called only after esp_bluedroid_enable() completes successfully.

  Parameters:

    callback -- [in] HFP client event callback function

  Returns:

    - ESP_OK: success

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: if callback is a NULL function pointer

esp_err_t esp_hf_client_init(void)

  Initialize the bluetooth HFP client module. This function should be called after esp_bluedroid_enable() completes successfully. ESP_HF_CLIENT_PROF_STATE_EVT with ESP_HF_INIT_SUCCESS will reported to the APP layer.

  Returns:

    - ESP_OK: if the initialization request is sent successfully

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_deinit(void)

  De-initialize for HFP client module. This function should be called only after esp_bluedroid_enable() completes successfully. ESP_HF_CLIENT_PROF_STATE_EVT with ESP_HF_DEINIT_SUCCESS will reported to the APP layer.

  Returns:

    - ESP_OK: success

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_connect(esp_bd_addr_t remote_bda)

  Establish a Service Level Connection to remote bluetooth HFP audio gateway(AG) device. This function must be called after esp_hf_client_init() and before esp_hf_client_deinit().

  Parameters:

    remote_bda -- [in] remote bluetooth device address

  Returns:

    - ESP_OK: connect request is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_disconnect(esp_bd_addr_t remote_bda)

  Disconnect from the remote HFP audio gateway. This function must be called after esp_hf_client_init() and before esp_hf_client_deinit().

  Parameters:

    remote_bda -- [in] remote bluetooth device address

  Returns:

    - ESP_OK: disconnect request is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_connect_audio(esp_bd_addr_t remote_bda)

  Create audio connection with remote HFP AG. As a precondition to use this API, Service Level Connection shall exist with AG.

  Parameters:

    remote_bda -- [in] remote bluetooth device address

  Returns:

    - ESP_OK: connect audio request is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_disconnect_audio(esp_bd_addr_t remote_bda)

  Release the established audio connection with remote HFP AG. As a precondition to use this API, Service Level Connection shall exist with AG.

  Parameters:

    remote_bda -- [in] remote bluetooth device address

  Returns:

    - ESP_OK: disconnect audio request is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_start_voice_recognition(void)

  Enable voice recognition in the AG. As a precondition to use this API, Service Level Connection shall exist with AG.

  Returns:

    - ESP_OK: starting voice recognition is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_stop_voice_recognition(void)

  Disable voice recognition in the AG. As a precondition to use this API, Service Level Connection shall exist with AG.

  Returns:

    - ESP_OK: stopping voice recognition is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_volume_update(esp_hf_volume_control_target_t type, int volume)

  Volume synchronization with AG. As a precondition to use this API, Service Level Connection shall exist with AG.

  Parameters:

    - type -- [in] volume control target, speaker or microphone

    - volume -- [in] gain of the speaker of microphone, ranges 0 to 15

  Returns:

    - ESP_OK: volume update is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_dial(const char *number)

  Place a call with a specified number, if number is NULL, last called number is called. As a precondition to use this API, Service Level Connection shall exist with AG.

  Parameters:

    number -- [in] number string of the call. If NULL, the last number is called(aka re-dial)

  Returns:

    - ESP_OK: a call placing is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_dial_memory(int location)

  Place a call with number specified by location(speed dial). As a precondition to use this API, Service Level Connection shall exist with AG.

  Parameters:

    location -- [in] location of the number in the memory

  Returns:

    - ESP_OK: a memory call placing is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_send_chld_cmd(esp_hf_chld_type_t chld, int idx)

  Send call hold and multiparty commands, or enhanced call control commands(Use AT+CHLD). As a precondition to use this API, Service Level Connection shall exist with AG.

  Parameters:

    - chld -- [in] AT+CHLD call hold and multiparty handling AT command.

    - idx -- [in] used in Enhanced Call Control Mechanisms, used if chld is ESP_HF_CHLD_TYPE_REL_X or ESP_HF_CHLD_TYPE_PRIV_X

  Returns:

    - ESP_OK: command AT+CHLD is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_send_btrh_cmd(esp_hf_btrh_cmd_t btrh)

  Send response and hold action command(Send AT+BTRH command) As a precondition to use this API, Service Level Connection shall exist with AG.

  Parameters:

    btrh -- [in] response and hold action to send

  Returns:

    - ESP_OK: command AT+BTRH is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_answer_call(void)

  Answer an incoming call(send ATA command). As a precondition to use this API, Service Level Connection shall exist with AG.

  Returns:

    - ESP_OK: a call answering is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_reject_call(void)

  Reject an incoming call or terminate an ongoing call(send AT+CHUP command). As a precondition to use this API, Service Level Connection shall exist with AG.

  Returns:

    - ESP_OK: the call rejecting is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_query_current_calls(void)

  Query list of current calls in AG(send AT+CLCC command). As a precondition to use this API, Service Level Connection shall exist with AG.

  Returns:

    - ESP_OK: query of current calls is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_query_current_operator_name(void)

  Query the name of currently selected network operator in AG(use AT+COPS commands). As a precondition to use this API, Service Level Connection shall exist with AG.

  Returns:

    - ESP_OK: query of current operator name is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_retrieve_subscriber_info(void)

  Get subscriber information number from AG(send AT+CNUM command) As a precondition to use this API, Service Level Connection shall exist with AG.

  Returns:

    - ESP_OK: the retrieving of subscriber information is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_send_dtmf(char code)

  Transmit DTMF codes during an ongoing call(use AT+VTS commands) As a precondition to use this API, Service Level Connection shall exist with AG.

  Parameters:

    code -- [in] dtmf code, single ascii character in the set 0-9, #, *, A-D

  Returns:

    - ESP_OK: the DTMF codes are sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_send_xapl(char *information, uint32_t features)

  Send command to enable Vendor specific feature to indicate battery level and docker status This is an Apple-specific command, but used by most devices, including Android and Windows.

  Parameters:

    - information -- [in] XAPL vendorID-productID-version, such as "0505-1995-0610" vendorID: A string representation of the hex value of the vendor ID from the manufacturer, without the 0x prefix. productID: A string representation of the hex value of the product ID from the manufacturer, without the 0x prefix. version: The revision of the software

    - features -- [in] A base-10 representation of a bit field. such as ESP_HF_CLIENT_XAPL_FEAT_BATTERY_REPORT

  Returns:

    - ESP_OK: Feature enable request is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_send_iphoneaccev(uint32_t bat_level, bool docked)

  Send Battery level and docker status Enable this feature using XAPL command first This is Apple-specific commands, but used by most device, including Android and Windows.

  Parameters:

    - bat_level -- [in] Battery Level: value between 0 and 9

    - docked -- [in] Dock State: false = undocked, true = docked

  Returns:

    - ESP_OK: battery level is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_request_last_voice_tag_number(void)

  Request a phone number from AG corresponding to last voice tag recorded (send AT+BINP command). As a precondition to use this API, Service Level Connection shall exist with AG.

  Returns:

    - ESP_OK: the phone number request corresponding to last voice tag recorded is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_send_nrec(void)

  Disable echo cancellation and noise reduction in the AG (use AT+NREC=0 command). As a precondition to use this API, Service Level Connection shall exist with AG.

  Returns:

    - ESP_OK: NREC=0 request is sent to lower layer

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_pkt_stat_nums_get(uint16_t sync_conn_handle)

  Get the number of packets received and sent This function is only used in the case that Voice Over HCI is enabled and the audio state is connected. When the operation is completed, the callback function will be called with ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT.

  Parameters:

    sync_conn_handle -- [in] the (e)SCO connection handle

  Returns:

    - ESP_OK: if the request is sent successfully

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_err_t esp_hf_client_register_audio_data_callback(esp_hf_client_audio_data_cb_t callback)

  Register HFP client audio data output function; the callback is only used in the case that Voice Over HCI is enabled.

  Parameters:

    callback -- [in] HFP client incoming audio data callback function

  Returns:

    - ESP_OK: success

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_FAIL: others

esp_hf_audio_buff_t *esp_hf_client_audio_buff_alloc(uint16_t size)

  Allocate a audio buffer to store and send audio data. This function is only used in the case that Voice Over HCI is enabled.

  Parameters:

    size -- [in] buffer size to allocate

  Returns:

    allocated audio buffer, if Bluedroid is not enabled, no memory, or size is zeros, will return NULL

void esp_hf_client_audio_buff_free(esp_hf_audio_buff_t *audio_buf)

  Free a audio buffer allocated by esp_hf_client_audio_buff_alloc. This function is only used in the case that Voice Over HCI is enabled.

  Parameters:

    audio_buf -- [in] audio buffer to free

esp_err_t esp_hf_client_audio_data_send(esp_hf_sync_conn_hdl_t sync_conn_hdl, esp_hf_audio_buff_t *audio_buf)

  Send audio data, the audio buffer should by allocated by esp_hf_client_audio_buff_alloc. If the length of the audio data is equal to preferred_frame_size indicated by ESP_HF_CLIENT_AUDIO_STATE_EVT, then we can reduce one memory copy inside the Bluedroid stack. This function is only used in the case that Voice Over HCI is enabled.

  Parameters:

    - sync_conn_hdl -- [in] (e)SCO connection handle

    - audio_buf -- [in] audio buffer that audio data stored

  Returns:

    - ESP_OK: success

    - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled

    - ESP_ERR_INVALID_ARG: invalid parameter

void esp_hf_client_pcm_resample_init(uint32_t src_sps, uint32_t bits, uint32_t channels)

  Initialize the down sampling converter. This is a utility function that can only be used in the case that Voice Over HCI is enabled.

  Parameters:

    - src_sps -- [in] original samples per second(source audio data, i.e. 48000, 32000, 16000, 44100, 22050, 11025)

    - bits -- [in] number of bits per pcm sample (16)

    - channels -- [in] number of channels (i.e. mono(1), stereo(2)...)

void esp_hf_client_pcm_resample_deinit(void)

  Deinitialize the down sampling converter.

int32_t esp_hf_client_pcm_resample(void *src, uint32_t in_bytes, void *dst)

  Down sampling utility to convert high sampling rate into 8K/16bits 1-channel mode PCM samples. This can only be used in the case that Voice Over HCI is enabled.

  Parameters:

    - src -- [in] pointer to the buffer where the original sampling PCM are stored

    - in_bytes -- [in] length of the input PCM sample buffer in byte

    - dst -- [in] pointer to the buffer which is to be used to store the converted PCM samples

  Returns:

    number of samples converted

esp_err_t esp_hf_client_get_profile_status(esp_hf_client_profile_status_t *profile_status)

  This function is used to get the status of hf client.

  Parameters:

    profile_status -- [out] - hf client status

  Returns:

    - ESP_OK: success

    - other: failed

### Unions

union esp_hf_client_cb_param_t
  #include <esp_hf_client_api.h>

  HFP client callback parameters.

  Public Members

  struct esp_hf_client_cb_param_t::hf_client_conn_stat_param conn_stat

    HF callback param of ESP_HF_CLIENT_CONNECTION_STATE_EVT

  struct esp_hf_client_cb_param_t::hf_client_audio_stat_param audio_stat

    HF callback param of ESP_HF_CLIENT_AUDIO_STATE_EVT

  struct esp_hf_client_cb_param_t::hf_client_bvra_param bvra

    HF callback param of ESP_HF_CLIENT_BVRA_EVT

  struct esp_hf_client_cb_param_t::hf_client_service_availability_param service_availability

    HF callback param of ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT

  struct esp_hf_client_cb_param_t::hf_client_network_roaming_param roaming

    HF callback param of ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT

  struct esp_hf_client_cb_param_t::hf_client_signal_strength_ind_param signal_strength

    HF callback param of ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT

  struct esp_hf_client_cb_param_t::hf_client_battery_level_ind_param battery_level

    HF callback param of ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT

  struct esp_hf_client_cb_param_t::hf_client_current_operator_param cops

    HF callback param of ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT

  struct esp_hf_client_cb_param_t::hf_client_call_ind_param call

    HF callback param of ESP_HF_CLIENT_CIND_CALL_EVT

  struct esp_hf_client_cb_param_t::hf_client_call_setup_ind_param call_setup

    HF callback param of `ESP_HF_CLIENT_CIND_CALL_SETUP_EVT`

  struct esp_hf_client_cb_param_t::hf_client_call_held_ind_param call_held

    HF callback param of ESP_HF_CLIENT_CIND_CALL_HELD_EVT

  struct esp_hf_client_cb_param_t::hf_client_btrh_param btrh

    HF callback param of ESP_HF_CLIENT_BTRH_EVT

  struct esp_hf_client_cb_param_t::hf_client_clip_param clip

    HF callback param of ESP_HF_CLIENT_CLIP_EVT

  struct esp_hf_client_cb_param_t::hf_client_ccwa_param ccwa

    HF callback param of ESP_HF_CLIENT_CCWA_EVT

  struct esp_hf_client_cb_param_t::hf_client_clcc_param clcc

    HF callback param of ESP_HF_CLIENT_CLCC_EVT

  struct esp_hf_client_cb_param_t::hf_client_volume_control_param volume_control

    HF callback param of ESP_HF_CLIENT_VOLUME_CONTROL_EVT

  struct esp_hf_client_cb_param_t::hf_client_at_response_param at_response

    HF callback param of ESP_HF_CLIENT_AT_RESPONSE_EVT

  struct esp_hf_client_cb_param_t::hf_client_cnum_param cnum

    HF callback param of ESP_HF_CLIENT_CNUM_EVT

  struct esp_hf_client_cb_param_t::hf_client_bsirparam bsir

    HF callback param of ESP_HF_CLIENT_BSIR_EVT

  struct esp_hf_client_cb_param_t::hf_client_binp_param binp

    HF callback param of ESP_HF_CLIENT_BINP_EVT

  struct esp_hf_client_cb_param_t::hf_client_pkt_status_nums pkt_nums

    HF callback param of ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT

  struct esp_hf_client_cb_param_t::hf_client_prof_stat_param prof_stat

    status to indicate hf client prof init or deinit

  struct hf_client_at_response_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_AT_RESPONSE_EVT.

    Public Members

    esp_hf_at_response_code_t code

      AT response code

    esp_hf_cme_err_t cme

      Extended Audio Gateway Error Result Code

  struct hf_client_audio_stat_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_AUDIO_STATE_EVT.

    Public Members

    esp_hf_client_audio_state_t state

      audio connection state

    esp_bd_addr_t remote_bda

      remote bluetooth device address

    esp_hf_sync_conn_hdl_t sync_conn_handle

      (e)SCO connection handle

    uint16_t preferred_frame_size

      valid only when Voice Over HCI is enabled, recommended frame size to send

  struct hf_client_battery_level_ind_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT.

    Public Members

    int value

      battery charge value, ranges from 0 to 5

  struct hf_client_binp_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_BINP_EVT.

    Public Members

    const char *number

      phone number corresponding to the last voice tag in the HF

  struct hf_client_bsirparam
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_BSIR_EVT.

    Public Members

    esp_hf_client_in_band_ring_state_t state

      setting state of in-band ring tone

  struct hf_client_btrh_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_BTRH_EVT.

    Public Members

    esp_hf_btrh_status_t status

      call hold and response status result code

  struct hf_client_bvra_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_BVRA_EVT.

    Public Members

    esp_hf_vr_state_t value

      voice recognition state

  struct hf_client_call_held_ind_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CIND_CALL_HELD_EVT.

    Public Members

    esp_hf_call_held_status_t status

      bluetooth proprietary call hold status indicator

  struct hf_client_call_ind_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CIND_CALL_EVT.

    Public Members

    esp_hf_call_status_t status

      call status indicator

  struct hf_client_call_setup_ind_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CIND_CALL_SETUP_EVT.

    Public Members

    esp_hf_call_setup_status_t status

      call setup status indicator

  struct hf_client_ccwa_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CCWA_EVT.

    Public Members

    const char *number

      phone number string of waiting call

  struct hf_client_clcc_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CLCC_EVT.

    Public Members

    int idx

      numbering(starting with 1) of the call

    esp_hf_current_call_direction_t dir

      direction of the call

    esp_hf_current_call_status_t status

      status of the call

    esp_hf_current_call_mpty_type_t mpty

      multi-party flag

    char *number

      phone number(optional)

  struct hf_client_clip_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CLIP_EVT.

    Public Members

    const char *number

      phone number string of call

  struct hf_client_cnum_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CNUM_EVT.

    Public Members

    const char *number

      phone number string

    esp_hf_subscriber_service_type_t type

      service type that the phone number relates to

  struct hf_client_conn_stat_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CONNECTION_STATE_EVT.

    Public Members

    esp_hf_client_connection_state_t state

      HF connection state

    uint32_t peer_feat

      AG supported features

    uint32_t chld_feat

      AG supported features on call hold and multiparty services

    esp_bd_addr_t remote_bda

      remote bluetooth device address

  struct hf_client_current_operator_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT.

    Public Members

    const char *name

      name of the network operator

  struct hf_client_network_roaming_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT.

    Public Members

    esp_hf_roaming_status_t status

      roaming status

  struct hf_client_pkt_status_nums
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT.

    Public Members

    uint32_t rx_total

      the total number of packets received

    uint32_t rx_correct

      the total number of packets data correctly received

    uint32_t rx_err

      the total number of packets data with possible invalid

    uint32_t rx_none

      the total number of packets data no received

    uint32_t rx_lost

      the total number of packets data partially lost

    uint32_t tx_total

      the total number of packets send

    uint32_t tx_discarded

      the total number of packets send lost

  struct hf_client_prof_stat_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_PROF_STATE_EVT.

    Public Members

    esp_hf_prof_state_t state

      hf client profile state param

  struct hf_client_service_availability_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT.

    Public Members

    esp_hf_network_state_t status

      service availability status

  struct hf_client_signal_strength_ind_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT.

    Public Members

    int value

      signal strength value, ranges from 0 to 5

  struct hf_client_volume_control_param
    #include <esp_hf_client_api.h>

    ESP_HF_CLIENT_VOLUME_CONTROL_EVT.

    Public Members

    esp_hf_volume_control_target_t type

      volume control target, speaker or microphone

    int volume

      gain, ranges from 0 to 15

### Structures

struct esp_hf_client_profile_status_t

  HF client profile status parameters.

  Public Members

  bool hf_client_inited

    hf client initialization

  uint8_t slc_conn_num

    Number of Service Level Connections

  uint8_t sync_conn_num

    Number of (e)SCO Connections

### Macros

ESP_BT_HF_CLIENT_NUMBER_LEN

  Maximum length of the phone number string in HFP Client

ESP_BT_HF_CLIENT_OPERATOR_NAME_LEN

  Maximum length of the operator name string in HFP Client

ESP_BT_HF_AT_SEND_XAPL_LEN

  Length of the XAPL string in AT command for HFP Client

ESP_HF_CLIENT_PEER_FEAT_3WAY

  Three-way calling

ESP_HF_CLIENT_PEER_FEAT_ECNR

  Echo cancellation and/or noise reduction

ESP_HF_CLIENT_PEER_FEAT_VREC

  Voice recognition

ESP_HF_CLIENT_PEER_FEAT_INBAND

  In-band ring tone

ESP_HF_CLIENT_PEER_FEAT_VTAG

  Attach a phone number to a voice tag

ESP_HF_CLIENT_PEER_FEAT_REJECT

  Ability to reject incoming call

ESP_HF_CLIENT_PEER_FEAT_ECS

  Enhanced Call Status

ESP_HF_CLIENT_PEER_FEAT_ECC

  Enhanced Call Control

ESP_HF_CLIENT_PEER_FEAT_EXTERR

  Extended error codes

ESP_HF_CLIENT_PEER_FEAT_CODEC

  Codec Negotiation

ESP_HF_CLIENT_PEER_FEAT_HF_IND

  HF Indicators

ESP_HF_CLIENT_PEER_FEAT_ESCO_S4

  eSCO S4 Setting Supported

ESP_HF_CLIENT_CHLD_FEAT_REL

  0 Release waiting call or held calls

ESP_HF_CLIENT_CHLD_FEAT_REL_ACC

  1 Release active calls and accept other waiting or held call

ESP_HF_CLIENT_CHLD_FEAT_REL_X

  1x Release specified active call only

ESP_HF_CLIENT_CHLD_FEAT_HOLD_ACC

  2 Active calls on hold and accept other waiting or held call

ESP_HF_CLIENT_CHLD_FEAT_PRIV_X

  2x Request private mode with specified call(put the rest on hold)

ESP_HF_CLIENT_CHLD_FEAT_MERGE

  3 Add held call to multiparty

ESP_HF_CLIENT_CHLD_FEAT_MERGE_DETACH

  4 Connect two calls and leave(disconnect from multiparty)

ESP_HF_CLIENT_XAPL_FEAT_RESERVED

  reserved

ESP_HF_CLIENT_XAPL_FEAT_BATTERY_REPORT

  The accessory supports battery reporting (reserved only for battery operated accessories)

ESP_HF_CLIENT_XAPL_FEAT_DOCKED

  The accessory is docked or powered (reserved only for battery operated accessories).

ESP_HF_CLIENT_XAPL_FEAT_SIRI_STATUS_REPORT

  The accessory supports Siri status reporting

ESP_HF_CLIENT_XAPL_NR_STATUS_REPORT

  The accessory supports noise reduction (NR) status reporting

### Type Definitions

typedef void (*esp_hf_client_audio_data_cb_t)(esp_hf_sync_conn_hdl_t sync_conn_hdl, esp_hf_audio_buff_t *audio_buf, bool is_bad_frame)

  HFP client incoming audio data callback function, user should copy audio_buf struct to other place before return. This callback is used in case of Voice Over HCI.

  Param sync_conn_hdl:

    [in] (e)SCO connection handle

  Param audio_buf:

    [in] pointer to incoming data(payload of HCI synchronous data packet), user should free audio buffer by calling esp_hf_client_audio_buff_free

  Param is_bad_frame:

    [in] whether this packet is marked as bad frame by baseband

typedef void (*esp_hf_client_cb_t)(esp_hf_client_cb_event_t event, esp_hf_client_cb_param_t *param)

  HFP client callback function type.

  Param event:

    [in] : Event type

  Param param:

    [in] : Pointer to callback parameter

### Enumerations

enum esp_hf_client_connection_state_t

  Bluetooth HFP RFCOMM connection and service level connection status.

  Values:

  enumerator ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTED

    RFCOMM data link channel released

  enumerator ESP_HF_CLIENT_CONNECTION_STATE_CONNECTING

    connecting remote device on the RFCOMM data link

  enumerator ESP_HF_CLIENT_CONNECTION_STATE_CONNECTED

    RFCOMM connection established

  enumerator ESP_HF_CLIENT_CONNECTION_STATE_SLC_CONNECTED

    service level connection established

  enumerator ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTING

    disconnecting with remote device on the RFCOMM data link

enum esp_hf_client_audio_state_t

  Bluetooth HFP audio connection status.

  Values:

  enumerator ESP_HF_CLIENT_AUDIO_STATE_DISCONNECTED

    audio connection released

  enumerator ESP_HF_CLIENT_AUDIO_STATE_CONNECTING

    audio connection has been initiated

  enumerator ESP_HF_CLIENT_AUDIO_STATE_CONNECTED

    audio connection is established

  enumerator ESP_HF_CLIENT_AUDIO_STATE_CONNECTED_MSBC

    mSBC audio connection is established

enum esp_hf_client_in_band_ring_state_t

  in-band ring tone state

  Values:

  enumerator ESP_HF_CLIENT_IN_BAND_RINGTONE_NOT_PROVIDED
  enumerator ESP_HF_CLIENT_IN_BAND_RINGTONE_PROVIDED

enum esp_hf_client_cb_event_t

  HF CLIENT callback events.

  Values:

  enumerator ESP_HF_CLIENT_CONNECTION_STATE_EVT

    connection state changed event

  enumerator ESP_HF_CLIENT_AUDIO_STATE_EVT

    audio connection state change event

  enumerator ESP_HF_CLIENT_BVRA_EVT

    voice recognition state change event

  enumerator ESP_HF_CLIENT_CIND_CALL_EVT

    call indication

  enumerator ESP_HF_CLIENT_CIND_CALL_SETUP_EVT

    call setup indication

  enumerator ESP_HF_CLIENT_CIND_CALL_HELD_EVT

    call held indication

  enumerator ESP_HF_CLIENT_CIND_SERVICE_AVAILABILITY_EVT

    network service availability indication

  enumerator ESP_HF_CLIENT_CIND_SIGNAL_STRENGTH_EVT

    signal strength indication

  enumerator ESP_HF_CLIENT_CIND_ROAMING_STATUS_EVT

    roaming status indication

  enumerator ESP_HF_CLIENT_CIND_BATTERY_LEVEL_EVT

    battery level indication

  enumerator ESP_HF_CLIENT_COPS_CURRENT_OPERATOR_EVT

    current operator information

  enumerator ESP_HF_CLIENT_BTRH_EVT

    call response and hold event

  enumerator ESP_HF_CLIENT_CLIP_EVT

    Calling Line Identification notification

  enumerator ESP_HF_CLIENT_CCWA_EVT

    call waiting notification

  enumerator ESP_HF_CLIENT_CLCC_EVT

    list of current calls notification

  enumerator ESP_HF_CLIENT_VOLUME_CONTROL_EVT

    audio volume control command from AG, provided by +VGM or +VGS message

  enumerator ESP_HF_CLIENT_AT_RESPONSE_EVT

    AT command response event

  enumerator ESP_HF_CLIENT_CNUM_EVT

    subscriber information response from AG

  enumerator ESP_HF_CLIENT_BSIR_EVT

    setting of in-band ring tone

  enumerator ESP_HF_CLIENT_BINP_EVT

    requested number of last voice tag from AG

  enumerator ESP_HF_CLIENT_RING_IND_EVT

    ring indication event

  enumerator ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT

    requested number of packet different status

  enumerator ESP_HF_CLIENT_PROF_STATE_EVT

    Indicate HF CLIENT init or deinit complete

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.