# Bluetooth® HFP Defines

## Overview

This file contains definitions for constants, enumerations, and structures used in the Bluetooth Hands-Free Profile (HFP), enabling features like call management, audio control, and network status reporting.

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

- bluetooth/bluedroid/classic_bt/hfp_ag demonstrates how to use the Hands-Free Audio Gateway (HF-AG) component to communicate with a device that implements Hands-Free Client Role, such as a headphone set. It provides commands for configuring the project, establishing connections, controlling volume, and answering or rejecting calls.

## API Reference

### Header File

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

- This header file can be included with:

  >     #include "esp_hf_defs.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

### Structures

struct esp_hf_audio_buff_t

  HFP audio buffer.

  Public Members

  uint16_t buff_size

    buffer size

  uint16_t data_len

    audio data length, data length should not greater than buffer size

  uint8_t *data

    pointer to audio data start

### Macros

ESP_HF_MSBC_CHANNEL_MODE

  mSBC channel mode

ESP_HF_MSBC_SAMPLING_RATE

  mSBC sampling rate

ESP_HF_MSBC_ALLOCATION_METHOD

  mSBC allocation method

ESP_HF_MSBC_SUBBANDS

  mSBC subbands

ESP_HF_MSBC_BLOCK_LENGTH

  mSBC block length

ESP_HF_MSBC_BITPOOL

  mSBC bitpool

ESP_HF_MSBC_ENCODED_FRAME_SIZE

  mSBC frame size

### Type Definitions

typedef uint16_t esp_hf_sync_conn_hdl_t

  HFP synchronous connection handle

### Enumerations

enum esp_hf_prof_state_t

  profile states

  Values:

  enumerator ESP_HF_INIT_SUCCESS

    Indicate init successful

  enumerator ESP_HF_INIT_ALREADY

    Indicate init repeated

  enumerator ESP_HF_INIT_FAIL

    Indicate init fail

  enumerator ESP_HF_DEINIT_SUCCESS

    Indicate deinit successful

  enumerator ESP_HF_DEINIT_ALREADY

    Indicate deinit repeated

  enumerator ESP_HF_DEINIT_FAIL

    Indicate deinit fail

enum esp_hf_in_band_ring_state_t

  in-band ring tone state

  Values:

  enumerator ESP_HF_IN_BAND_RINGTONE_NOT_PROVIDED

    Indicates that the in-band ringtone is not provided by the Hands-Free device

  enumerator ESP_HF_IN_BAND_RINGTONE_PROVIDED

    Indicates that the in-band ringtone is provided by the Hands-Free device

enum esp_hf_vr_state_t

  voice recognition state

  Values:

  enumerator ESP_HF_VR_STATE_DISABLED

    voice recognition disabled

  enumerator ESP_HF_VR_STATE_ENABLED

    voice recognition enabled

enum esp_hf_volume_control_target_t

  Bluetooth HFP audio volume control target.

  Values:

  enumerator ESP_HF_VOLUME_CONTROL_TARGET_SPK

    speaker

  enumerator ESP_HF_VOLUME_CONTROL_TARGET_MIC

    microphone

enum esp_hf_audio_state_t

  Bluetooth HFP audio connection status.

  Values:

  enumerator ESP_HF_AUDIO_STATE_DISCONNECTED

    audio connection released

  enumerator ESP_HF_AUDIO_STATE_CONNECTING

    audio connection has been initiated

  enumerator ESP_HF_AUDIO_STATE_CONNECTED

    audio connection is established

  enumerator ESP_HF_AUDIO_STATE_CONNECTED_MSBC

    mSBC audio connection is established

enum esp_hf_volume_type_t

  Bluetooth HFP audio volume type.

  Values:

  enumerator ESP_HF_VOLUME_TYPE_SPK

    speaker

  enumerator ESP_HF_VOLUME_TYPE_MIC

    microphone

enum esp_hf_network_state_t

  +CIND network service availability status

  Values:

  enumerator ESP_HF_NETWORK_STATE_NOT_AVAILABLE

    Indicates that the network service is not available

  enumerator ESP_HF_NETWORK_STATE_AVAILABLE

    Indicates that the network service is available

enum esp_hf_ciev_report_type_t

  +CIEV report type

  Values:

  enumerator ESP_HF_IND_TYPE_CALL

    position of call indicator

  enumerator ESP_HF_IND_TYPE_CALLSETUP

    position of callsetup indicator

  enumerator ESP_HF_IND_TYPE_SERVICE

    position of service indicator

  enumerator ESP_HF_IND_TYPE_SIGNAL

    position of signal strength indicator, range: 0-5

  enumerator ESP_HF_IND_TYPE_ROAM

    position of roaming indicator

  enumerator ESP_HF_IND_TYPE_BATTCHG

    position of battery charge indicator, range: 0-5

  enumerator ESP_HF_IND_TYPE_CALLHELD

    position of callheld indicator

enum esp_hf_service_type_t

  +CIEV Service type

  Values:

  enumerator ESP_HF_SERVICE_TYPE_HOME

    Indicates the service is in the home

  enumerator ESP_HF_SERVICE_TYPE_ROAMING

    Indicates the service is in roaming

enum esp_hf_call_status_t

  +CIND call status indicator values

  Values:

  enumerator ESP_HF_CALL_STATUS_NO_CALLS

    no call in progress

  enumerator ESP_HF_CALL_STATUS_CALL_IN_PROGRESS

    call is present(active or held)

enum esp_hf_call_setup_status_t

  +CIND call setup status indicator values

  Values:

  enumerator ESP_HF_CALL_SETUP_STATUS_IDLE

    no call setup in progress

  enumerator ESP_HF_CALL_SETUP_STATUS_INCOMING

    incoming call setup in progress

  enumerator ESP_HF_CALL_SETUP_STATUS_OUTGOING_DIALING

    outgoing call setup in dialing state

  enumerator ESP_HF_CALL_SETUP_STATUS_OUTGOING_ALERTING

    outgoing call setup in alerting state

enum esp_hf_roaming_status_t

  +CIND roaming status indicator values

  Values:

  enumerator ESP_HF_ROAMING_STATUS_INACTIVE

    roaming is not active

  enumerator ESP_HF_ROAMING_STATUS_ACTIVE

    a roaming is active

enum esp_hf_call_held_status_t

  +CIND call held indicator values

  Values:

  enumerator ESP_HF_CALL_HELD_STATUS_NONE

    no calls held

  enumerator ESP_HF_CALL_HELD_STATUS_HELD_AND_ACTIVE

    both active and held call

  enumerator ESP_HF_CALL_HELD_STATUS_HELD

    call on hold, no active call

enum esp_hf_current_call_status_t

  +CLCC status of the call

  Values:

  enumerator ESP_HF_CURRENT_CALL_STATUS_ACTIVE

    active

  enumerator ESP_HF_CURRENT_CALL_STATUS_HELD

    held

  enumerator ESP_HF_CURRENT_CALL_STATUS_DIALING

    dialing (outgoing calls only)

  enumerator ESP_HF_CURRENT_CALL_STATUS_ALERTING

    alerting (outgoing calls only)

  enumerator ESP_HF_CURRENT_CALL_STATUS_INCOMING

    incoming (incoming calls only)

  enumerator ESP_HF_CURRENT_CALL_STATUS_WAITING

    waiting (incoming calls only)

  enumerator ESP_HF_CURRENT_CALL_STATUS_HELD_BY_RESP_HOLD

    call held by response and hold

enum esp_hf_current_call_direction_t

  +CLCC direction of the call

  Values:

  enumerator ESP_HF_CURRENT_CALL_DIRECTION_OUTGOING

    outgoing

  enumerator ESP_HF_CURRENT_CALL_DIRECTION_INCOMING

    incoming

enum esp_hf_current_call_mpty_type_t

  +CLCC multi-party call flag

  Values:

  enumerator ESP_HF_CURRENT_CALL_MPTY_TYPE_SINGLE

    not a member of a multi-party call

  enumerator ESP_HF_CURRENT_CALL_MPTY_TYPE_MULTI

    member of a multi-party call

enum esp_hf_current_call_mode_t

  +CLCC call mode

  Values:

  enumerator ESP_HF_CURRENT_CALL_MODE_VOICE

    the current call is a voice call

  enumerator ESP_HF_CURRENT_CALL_MODE_DATA

    the current call is a data call

  enumerator ESP_HF_CURRENT_CALL_MODE_FAX

    the current call is a fax call

enum esp_hf_call_addr_type_t

  +CLCC address type

  Values:

  enumerator ESP_HF_CALL_ADDR_TYPE_UNKNOWN

    unknown address type

  enumerator ESP_HF_CALL_ADDR_TYPE_INTERNATIONAL

    international address

enum esp_hf_subscriber_service_type_t

  +CNUM service type of the phone number

  Values:

  enumerator ESP_HF_SUBSCRIBER_SERVICE_TYPE_UNKNOWN

    unknown

  enumerator ESP_HF_SUBSCRIBER_SERVICE_TYPE_VOICE

    voice service

  enumerator ESP_HF_SUBSCRIBER_SERVICE_TYPE_FAX

    fax service

enum esp_hf_btrh_status_t

  +BTRH response and hold result code

  Values:

  enumerator ESP_HF_BTRH_STATUS_HELD

    incoming call is put on held in AG

  enumerator ESP_HF_BTRH_STATUS_ACCEPTED

    held incoming call is accepted in AG

  enumerator ESP_HF_BTRH_STATUS_REJECTED

    held incoming call is rejected in AG

enum esp_hf_btrh_cmd_t

  AT+BTRH response and hold action code.

  Values:

  enumerator ESP_HF_BTRH_CMD_HOLD

    put the incoming call on hold

  enumerator ESP_HF_BTRH_CMD_ACCEPT

    accept a held incoming call

  enumerator ESP_HF_BTRH_CMD_REJECT

    reject a held incoming call

enum esp_hf_nrec_t

  Values:

  enumerator ESP_HF_NREC_STOP

    Stop the NREC

  enumerator ESP_HF_NREC_START

    Start the NREC

enum esp_hf_call_waiting_status_t

  +CCWA response status

  Values:

  enumerator ESP_HF_CALL_WAITING_INACTIVE

    inactive call waiting

  enumerator ESP_HF_CALL_WAITING_ACTIVE

    active call waiting

enum esp_hf_wbs_config_t

  Values:

  enumerator ESP_HF_WBS_NONE

    No Wideband Speech (WBS) codec support

  enumerator ESP_HF_WBS_NO

    Wideband Speech (WBS) codec is not enabled

  enumerator ESP_HF_WBS_YES

    Wideband Speech (WBS) codec is enabled

enum esp_hf_connection_state_t

  Bluetooth HFP RFCOMM connection and service level connection status.

  Values:

  enumerator ESP_HF_CONNECTION_STATE_DISCONNECTED

    RFCOMM data link channel released

  enumerator ESP_HF_CONNECTION_STATE_CONNECTING

    connecting remote device on the RFCOMM data link

  enumerator ESP_HF_CONNECTION_STATE_CONNECTED

    RFCOMM connection established

  enumerator ESP_HF_CONNECTION_STATE_SLC_CONNECTED

    service level connection established

  enumerator ESP_HF_CONNECTION_STATE_DISCONNECTING

    disconnecting with remote device on the RFCOMM data link

enum esp_hf_chld_type_t

  AT+CHLD command values.

  Values:

  enumerator ESP_HF_CHLD_TYPE_REL

    <0>, Terminate all held or set UDUB("busy") to a waiting call

  enumerator ESP_HF_CHLD_TYPE_REL_ACC

    <1>, Terminate all active calls and accept a waiting/held call

  enumerator ESP_HF_CHLD_TYPE_HOLD_ACC

    <2>, Hold all active calls and accept a waiting/held call

  enumerator ESP_HF_CHLD_TYPE_MERGE

    <3>, Add all held calls to a conference

  enumerator ESP_HF_CHLD_TYPE_MERGE_DETACH

    <4>, connect the two calls and disconnect the subscriber from both calls

  enumerator ESP_HF_CHLD_TYPE_REL_X

    <1x>, release specified calls only

  enumerator ESP_HF_CHLD_TYPE_PRIV_X

    <2x>, request private consultation mode with specified call

enum esp_hf_at_response_code_t

  Values:

  enumerator ESP_HF_AT_RESPONSE_CODE_OK

    acknowledges execution of a command line

  enumerator ESP_HF_AT_RESPONSE_CODE_ERR

    command not accepted

  enumerator ESP_HF_AT_RESPONSE_CODE_NO_CARRIER

    connection terminated

  enumerator ESP_HF_AT_RESPONSE_CODE_BUSY

    busy signal detected

  enumerator ESP_HF_AT_RESPONSE_CODE_NO_ANSWER

    connection completion timeout

  enumerator ESP_HF_AT_RESPONSE_CODE_DELAYED

    delayed

  enumerator ESP_HF_AT_RESPONSE_CODE_BLACKLISTED

    blacklisted

  enumerator ESP_HF_AT_RESPONSE_CODE_CME

    CME error

enum esp_hf_at_response_t

  Values:

  enumerator ESP_HF_AT_RESPONSE_ERROR

    error in the AT command response

  enumerator ESP_HF_AT_RESPONSE_OK

    successful AT command response

enum esp_hf_cme_err_t

  Extended Audio Gateway Error Result Code Response.

  Values:

  enumerator ESP_HF_CME_AG_FAILURE

    ag failure

  enumerator ESP_HF_CME_NO_CONNECTION_TO_PHONE

    no connection to phone

  enumerator ESP_HF_CME_OPERATION_NOT_ALLOWED

    operation not allowed

  enumerator ESP_HF_CME_OPERATION_NOT_SUPPORTED

    operation not supported

  enumerator ESP_HF_CME_PH_SIM_PIN_REQUIRED

    PH-SIM PIN Required

  enumerator ESP_HF_CME_SIM_NOT_INSERTED

    SIM not inserted

  enumerator ESP_HF_CME_SIM_PIN_REQUIRED

    SIM PIN required

  enumerator ESP_HF_CME_SIM_PUK_REQUIRED

    SIM PUK required

  enumerator ESP_HF_CME_SIM_FAILURE

    SIM failure

  enumerator ESP_HF_CME_SIM_BUSY

    SIM busy

  enumerator ESP_HF_CME_INCORRECT_PASSWORD

    incorrect password

  enumerator ESP_HF_CME_SIM_PIN2_REQUIRED

    SIM PIN2 required

  enumerator ESP_HF_CME_SIM_PUK2_REQUIRED

    SIM PUK2 required

  enumerator ESP_HF_CME_MEMORY_FULL

    memory full

  enumerator ESP_HF_CME_INVALID_INDEX

    invalid index

  enumerator ESP_HF_CME_MEMORY_FAILURE

    memory failure

  enumerator ESP_HF_CME_TEXT_STRING_TOO_LONG

    text string too long

  enumerator ESP_HF_CME_INVALID_CHARACTERS_IN_TEXT_STRING

    invalid characters in text string

  enumerator ESP_HF_CME_DIAL_STRING_TOO_LONG

    dial string too long

  enumerator ESP_HF_CME_INVALID_CHARACTERS_IN_DIAL_STRING

    invalid characters in dial string

  enumerator ESP_HF_CME_NO_NETWORK_SERVICE

    no network service

  enumerator ESP_HF_CME_NETWORK_TIMEOUT

    network timeout

  enumerator ESP_HF_CME_NETWORK_NOT_ALLOWED

    network not allowed –emergency calls only

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.