# GATT Client API

## Application Examples

- bluetooth/bluedroid/ble/gatt_client demonstrates how to create a GATT Client that connects to a GATT server, enabling the server's notification function to discover its service.

- bluetooth/bluedroid/ble/gattc_multi_connect demonstrates how to create a GATT Client that connects to multiple GATT servers, enabling their notification functions to discover their services.

- bluetooth/bluedroid/coex/gattc_gatts_coex demonstrates the coexistence of GATT client and GATT server by creating a GATT service, starting ADV, and exchanging data between a GATT client and device.

## API Reference

### Header File

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

- This header file can be included with:

  >     #include "esp_gattc_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_ble_gattc_register_callback(esp_gattc_cb_t callback)

  Register GATT Client application callbacks.

  Note

  Avoid performing time-consuming operations within the callback functions.

  Parameters:

    callback -- [in] The pointer to the application callback function

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_gattc_cb_t esp_ble_gattc_get_callback(void)

  Get the current application callbacks.

  Returns:

    - esp_gattc_cb_t: Current callback

esp_err_t esp_ble_gattc_app_register(uint16_t app_id)

  Register a GATT Client application.

  Note

  1. This function triggers `ESP_GATTC_REG_EVT`.

  2. The maximum number of applications is limited to 4.

  Parameters:

    app_id -- [in] The UUID for different application

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_ARG: The input `app_id` exceeds `ESP_APP_ID_MAX` (0x7fff) defined in esp_bt_defs.h

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if)

  Unregister a GATT Client application.

  Note

  This function triggers `ESP_GATTC_UNREG_EVT`.

  Parameters:

    gattc_if -- [in] GATT Client access interface

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gattc_enh_open(esp_gatt_if_t gattc_if, esp_ble_gatt_creat_conn_params_t *esp_gatt_create_conn)

  Create an ACL connection.

  Note

  1. Do not enable `BT_BLE_42_FEATURES_SUPPORTED` and `BT_BLE_50_FEATURES_SUPPORTED` in the menuconfig simultaneously.

  1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`.

  2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well.

  3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only.

  Parameters:

    - gattc_if -- [in] GATT client access interface.

    - esp_gatt_create_conn -- [in] Pointer to the structure containing connection parameters.

  Returns:

    - ESP_OK: Success

    - others: Operation failed

esp_err_t esp_ble_gattc_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, esp_ble_addr_type_t remote_addr_type, bool is_direct)

  Create an ACL connection when `BT_BLE_42_FEATURES_SUPPORTED` is enabled in the menuconfig.

  Note

  1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`.

  2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well.

  3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - remote_bda -- [in] Remote device address

    - remote_addr_type -- [in] Remote device address type

    - is_direct -- [in] `True` indicates a direct connection, while `False` indicates a background auto connection. By now, background auto connection is not supported, please always pass True to this parameter.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gattc_aux_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, esp_ble_addr_type_t remote_addr_type, bool is_direct)

  Create an ACL connection when `BT_BLE_50_FEATURES_SUPPORTED` is enabled in the menuconfig.

  Note

  1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`.

  2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well.

  3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - remote_bda -- [in] Remote device address

    - remote_addr_type -- [in] Remote device address type

    - is_direct -- [in] `True` indicates a direct connection, while `False` indicates a background auto connection. By now, background auto connection is not supported, please always pass True to this parameter.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gattc_aux_open_with_pawr_synced(esp_gatt_if_t gattc_if, esp_ble_gatt_pawr_conn_params_t *pawr_conn_params)

  Open an auxiliary connection with PAwR synced parameters.

  Note

  1. This function is used to establish a connection with a device that is synchronized to a PAwR advertiser.

  2. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - pawr_conn_params -- [in] PAwR connection parameters

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_ARG: Invalid argument

    - ESP_FAIL: Failure

esp_err_t esp_ble_gattc_close(esp_gatt_if_t gattc_if, uint16_t conn_id)

  Close the virtual GATT Client connection.

  Note

  1. This function triggers `ESP_GATTC_CLOSE_EVT`.

  2. There may be multiple virtual GATT server connections when multiple `app_id` got registered.

  3. This API closes one virtual GATT server connection only, if there exist other virtual GATT server connections. It does not close the physical connection.

  4. The API `esp_ble_gap_disconnect` can be used to disconnect the physical connection directly.

  5. If there is only one virtual GATT connection left, this API will terminate the ACL connection in addition and triggers `ESP_GATTC_DISCONNECT_EVT`. Then there is no need to call `esp_ble_gap_disconnect` anymore.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID to be closed

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gattc_send_mtu_req(esp_gatt_if_t gattc_if, uint16_t conn_id)

  Configure the MTU size in the GATT channel.

  Note

  1. This function triggers `ESP_GATTC_CFG_MTU_EVT`.

  2. You could call `esp_ble_gatt_set_local_mtu` to set the desired MTU size locally before this API. If not set, the GATT channel uses the default MTU size (23 bytes).

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gattc_search_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *filter_uuid)

  Search services from the local GATTC cache.

  Note

  1. This function triggers `ESP_GATTC_SEARCH_RES_EVT` each time a service is retrieved.

  2. This function triggers `ESP_GATTC_SEARCH_CMPL_EVT` when the search is completed.

  3. The 128-bit base UUID will be converted to a 16-bit UUID automatically in the search results. Other types of UUID remain unchanged.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - filter_uuid -- [in] A UUID of the intended service. If NULL is passed, this API will return all services.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_gatt_status_t esp_ble_gattc_get_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *svc_uuid, esp_gattc_service_elem_t *result, uint16_t *count, uint16_t offset)

  Get the service with the given service UUID in the local GATTC cache.

  Note

  1. This API does not trigger any event.

  2. `esp_ble_gattc_cache_refresh` can be used to discover services again.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - svc_uuid -- [in] The pointer to the service UUID. If NULL is passed, the API will retrieve all services.

    - result -- [out] The pointer to the service which has been found in the local GATTC cache

    - count -- [inout] The number of services to retrieve. It will be updated with the actual number of services found.

    - offset -- [in] The position offset to retrieve

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_gatt_status_t esp_ble_gattc_get_all_char(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_gattc_char_elem_t *result, uint16_t *count, uint16_t offset)

  Get all characteristics with the given handle range in the local GATTC cache.

  Note

  1. This API does not trigger any event.

  2. `start_handle` must be greater than 0, and smaller than `end_handle`.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - start_handle -- [in] The attribute start handle

    - end_handle -- [in] The attribute end handle

    - result -- [out] The pointer to the characteristic in the service

    - count -- [inout] The number of characteristics to retrieve. It will be updated with the actual number of characteristics found.

    - offset -- [in] The position offset to retrieve

  Returns:

    - ESP_OK: Success

    - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle` or `end_handle`

    - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0

    - ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_all_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t char_handle, esp_gattc_descr_elem_t *result, uint16_t *count, uint16_t offset)

  Get all descriptors with the given characteristic in the local GATTC cache.

  Note

  1. This API does not trigger any event.

  2. `char_handle` must be greater than 0.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID which identifies the server

    - char_handle -- [in] The given characteristic handle

    - result -- [out] The pointer to the descriptor in the characteristic

    - count -- [inout] The number of descriptors to retrieve. It will be updated with the actual number of descriptors found.

    - offset -- [in] The position offset to retrieve

  Returns:

    - ESP_OK: Success

    - ESP_GATT_INVALID_HANDLE: Invalid GATT `char_handle`

    - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0

    - ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_char_by_uuid(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_bt_uuid_t char_uuid, esp_gattc_char_elem_t *result, uint16_t *count)

  Get the characteristic with the given characteristic UUID in the local GATTC cache.

  Note

  1. This API does not trigger any event.

  2. `start_handle` must be greater than 0, and smaller than `end_handle`.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - start_handle -- [in] The attribute start handle

    - end_handle -- [in] The attribute end handle

    - char_uuid -- [in] The characteristic UUID

    - result -- [out] The pointer to the characteristic in the service

    - count -- [inout] The number of characteristics to retrieve. It will be updated with the actual number of characteristics found.

  Returns:

    - ESP_OK: Success

    - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle` or `end_handle`

    - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0

    - ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_descr_by_uuid(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_bt_uuid_t char_uuid, esp_bt_uuid_t descr_uuid, esp_gattc_descr_elem_t *result, uint16_t *count)

  Get the descriptor with the given characteristic UUID in the local GATTC cache.

  Note

  1. This API does not trigger any event.

  2. `start_handle` must be greater than 0, and smaller than `end_handle`.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - start_handle -- [in] The attribute start handle

    - end_handle -- [in] The attribute end handle

    - char_uuid -- [in] The characteristic UUID

    - descr_uuid -- [in] The descriptor UUID.

    - result -- [out] The pointer to the descriptor in the given characteristic.

    - count -- [inout] The number of descriptors want to retrieve. It will be updated with the actual number of descriptors found.

  Returns:

    - ESP_OK: Success

    - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0

    - ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_descr_by_char_handle(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t char_handle, esp_bt_uuid_t descr_uuid, esp_gattc_descr_elem_t *result, uint16_t *count)

  Get the descriptor with the given characteristic handle in the local GATTC cache.

  Note

  1. This API does not trigger any event.

  2. `char_handle` must be greater than 0.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID which identifies the server

    - char_handle -- [in] The characteristic handle

    - descr_uuid -- [in] The descriptor UUID

    - result -- [out] The pointer to the descriptor in the given characteristic

    - count -- [inout] The number of descriptors want to retrieve. It will be updated with the actual number of descriptors found.

  Returns:

    - ESP_OK: Success

    - ESP_GATT_INVALID_HANDLE: Invalid GATT `char_handle`

    - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0

    - ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_include_service(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_bt_uuid_t *incl_uuid, esp_gattc_incl_svc_elem_t *result, uint16_t *count)

  Get the included services with the given service handle in the local GATTC cache.

  Note

  1. This API does not trigger any event.

  2. `start_handle` must be greater than 0, and smaller than `end_handle`.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID which identifies the server

    - start_handle -- [in] The attribute start handle

    - end_handle -- [in] The attribute end handle

    - incl_uuid -- [in] The included service UUID

    - result -- [out] The pointer to the included service with the given service handle.

    - count -- [inout] The number of included services to retrieve. It will be updated with the actual number of included services found.

  Returns:

    - ESP_OK: Success

    - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0

    - ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_attr_count(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gatt_db_attr_type_t type, uint16_t start_handle, uint16_t end_handle, uint16_t char_handle, uint16_t *count)

  Get the attribute count with the given service or characteristic in the local GATTC cache.

  Note

  1. This API does not trigger any event.

  2. `start_handle` must be greater than 0, and smaller than `end_handle` if the `type` is not `ESP_GATT_DB_DESCRIPTOR`.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - type -- [in] The attribute type

    - start_handle -- [in] The attribute start handle. If the type is `ESP_GATT_DB_DESCRIPTOR`, this parameter will be ignored.

    - end_handle -- [in] The attribute end handle. If the type is `ESP_GATT_DB_DESCRIPTOR`, this parameter will be ignored.

    - char_handle -- [in] The characteristic handle. This parameter is valid only if the type is `ESP_GATT_DB_DESCRIPTOR`.

    - count -- [out] The number of attributes found in the local GATTC cache with the given attribute type

  Returns:

    - ESP_OK: Success

    - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle`, `end_handle`

    - ESP_GATT_INVALID_PDU: NULL pointer to `count`

    - ESP_FAIL: Failure due to other reasons

esp_gatt_status_t esp_ble_gattc_get_db(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_gattc_db_elem_t *db, uint16_t *count)

  Get the GATT database elements.

  Note

  1. This API does not trigger any event.

  2. `start_handle` must be greater than 0, and smaller than `end_handle`.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - start_handle -- [in] The attribute start handle

    - end_handle -- [in] The attribute end handle

    - conn_id -- [in] Connection ID

    - db -- [out] The pointer to GATT database elements

    - count -- [inout] The number of elements in the database to retrieve. It will be updated with the actual number of elements found.

  Returns:

    - ESP_OK: Success

    - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle`, `end_handle`

    - ESP_GATT_INVALID_PDU: NULL pointer to `db` or NULL pointer to `count` or the count value is 0

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_read_char(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, esp_gatt_auth_req_t auth_req)

  Read the characteristics value of the given characteristic handle.

  Note

  1. This function triggers `ESP_GATTC_READ_CHAR_EVT`.

  2. This function should be called only after the connection has been established.

  3. `handle` must be greater than 0.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - handle -- [in] Characteristic handle to read

    - auth_req -- [in] Authenticate request type

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_STATE: The connection has not been established.

    - ESP_GATT_INVALID_HANDLE: Invalid `handle`

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_read_by_type(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_bt_uuid_t *uuid, esp_gatt_auth_req_t auth_req)

  Read the characteristics value of the given characteristic UUID.

  Note

  1. This function triggers `ESP_GATTC_READ_CHAR_EVT`.

  2. This function should be called only after the connection has been established.

  3. `start_handle` must be greater than 0, and smaller than `end_handle`.

  Parameters:

    - gattc_if -- [in] GATT Client access interface.

    - conn_id -- [in] Connection ID

    - start_handle -- [in] The attribute start handle

    - end_handle -- [in] The attribute end handle

    - uuid -- [in] The pointer to UUID of attribute to read

    - auth_req -- [in] Authenticate request type

  Returns:

    - ESP_OK: Success

    - ESP_GATT_ILLEGAL_PARAMETER: NULL pointer to `uuid`

    - ESP_ERR_INVALID_STATE: The connection has not been established

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_read_multiple(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gattc_multi_t *read_multi, esp_gatt_auth_req_t auth_req)

  Read multiple characteristic or descriptor values.

  Note

  1. This function triggers `ESP_GATTC_READ_MULTIPLE_EVT`.

  2. This function should be called only after the connection has been established.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID which specifies the server

    - read_multi -- [in] Pointer to `esp_gattc_multi_t`

    - auth_req -- [in] Authenticate request type

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_STATE: The connection has not been established

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_read_multiple_variable(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gattc_multi_t *read_multi, esp_gatt_auth_req_t auth_req)

  Read multiple variable length characteristic values.

  Note

  1. This function triggers `ESP_GATTC_READ_MULTI_VAR_EVT`.

  2. This function should be called only after the connection has been established.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - read_multi -- [in] The pointer to the `esp_gattc_multi_t`

    - auth_req -- [in] Authenticate request type

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_STATE: The connection has not been established.

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_read_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, esp_gatt_auth_req_t auth_req)

  Read a characteristics descriptor.

  Note

  1. This function triggers `ESP_GATTC_READ_DESCR_EVT`.

  2. This function should be called only after the connection has been established.

  3. `handle` must be greater than 0.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - handle -- [in] Descriptor handle to read

    - auth_req -- [in] Authenticate request type

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_STATE: The connection has not been established.

    - ESP_GATT_INVALID_HANDLE：Invalid `handle`

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_write_char(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t value_len, uint8_t *value, esp_gatt_write_type_t write_type, esp_gatt_auth_req_t auth_req)

  Write the characteristic value of a given characteristic handle.

  Note

  1. This function triggers `ESP_GATTC_WRITE_CHAR_EVT`.

  2. This function should be called only after the connection has been established.

  3. `handle` must be greater than 0.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - handle -- [in] The characteristic handle to write

    - value_len -- [in] The length of the value to write in bytes

    - value -- [in] The value to write

    - write_type -- [in] The type of Attribute write operation

    - auth_req -- [in] Authentication request type

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_STATE: The connection has not been established.

    - ESP_GATT_INVALID_HANDLE：Invalid `handle`

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_write_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t value_len, uint8_t *value, esp_gatt_write_type_t write_type, esp_gatt_auth_req_t auth_req)

  Write Characteristic descriptor value of a given descriptor handle.

  Note

  1. This function triggers `ESP_GATTC_WRITE_DESCR_EVT`.

  2. This function should be called only after the connection has been established.

  3. `handle` must be greater than 0.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - handle -- [in] The descriptor handle to write.

    - value_len -- [in] The length of the value to write in bytes.

    - value -- [in] The value to write

    - write_type -- [in] The type of Attribute write operation

    - auth_req -- [in] Authentication request type

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_STATE: The connection has not been established.

    - ESP_GATT_INVALID_HANDLE：Invalid `handle`

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t offset, uint16_t value_len, uint8_t *value, esp_gatt_auth_req_t auth_req)

  Prepare to write a characteristic value which is longer than the MTU size to a specified characteristic handle.

  Note

  1. This function should be called only after the connection has been established.

  2. After using this API, use `esp_ble_gattc_execute_write` to write.

  3. This function triggers `ESP_GATTC_PREP_WRITE_EVT`.

  4. If `value_len` is less than or equal to MTU size, it is recommended to `esp_ble_gattc_write_char` to write directly.

  5. `handle` must be greater than 0.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - handle -- [in] Characteristic handle to prepare to write

    - offset -- [in] The position offset to write

    - value_len -- [in] The length of the value to write in bytes

    - value -- [in] The value to write

    - auth_req -- [in] Authentication request type

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_STATE: The connection has not been established.

    - ESP_GATT_INVALID_HANDLE：Invalid `handle`

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_prepare_write_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, uint16_t offset, uint16_t value_len, uint8_t *value, esp_gatt_auth_req_t auth_req)

  Prepare to write a characteristic descriptor value at a given handle.

  Note

  1. This function triggers `ESP_GATTC_WRITE_CHAR_EVT`.

  2. This function should be called only after the connection has been established.

  3. `handle` must be greater than 0.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - handle -- [in] Characteristic descriptor handle to prepare to write

    - offset -- [in] The position offset to write

    - value_len -- [in] The length of the value to write in bytes

    - value -- [in] The value to write

    - auth_req -- [in] Authentication request type

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_STATE: The connection has not been established.

    - ESP_GATT_INVALID_HANDLE：Invalid `handle`

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_execute_write(esp_gatt_if_t gattc_if, uint16_t conn_id, bool is_execute)

  Execute a prepared writing sequence.

  Note

  This function triggers `ESP_GATTC_EXEC_EVT`.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - conn_id -- [in] Connection ID

    - is_execute -- [in] True if it is to execute the writing sequence; false if it is to cancel the writing sequence.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gattc_register_for_notify(esp_gatt_if_t gattc_if, esp_bd_addr_t server_bda, uint16_t handle)

  Register to receive notification/indication of a characteristic.

  Note

  1. This function triggers `ESP_GATTC_REG_FOR_NOTIFY_EVT`.

  2. You should call `esp_ble_gattc_write_char_descr()` after this API to write Client Characteristic Configuration (CCC) descriptor to the value of 1 (Enable Notification) or 2 (Enable Indication).

  3. `handle` must be greater than 0.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - server_bda -- [in] Target GATT server device address

    - handle -- [in] Target GATT characteristic handle

  Returns:

    - ESP_OK: Success

    - ESP_GATT_INVALID_HANDLE：Invalid `handle`

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_unregister_for_notify(esp_gatt_if_t gattc_if, esp_bd_addr_t server_bda, uint16_t handle)

  Unregister the notification of a service.

  Note

  1. This function triggers `ESP_GATTC_UNREG_FOR_NOTIFY_EVT`.

  2. You should call `esp_ble_gattc_write_char_descr()` after this API to write Client Characteristic Configuration (CCC) descriptor value to 0.

  3. `handle` must be greater than 0

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - server_bda -- [in] Target GATT server device address

    - handle -- [in] Target GATT characteristic handle

  Returns:

    - ESP_OK: Success

    - ESP_GATT_INVALID_HANDLE：Invalid `handle`

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gattc_cache_refresh(esp_bd_addr_t remote_bda)

  Refresh the cache of the remote device.

  Note

  1. If the device is connected, this API will restart the discovery of service information of the remote device.

  2. This function triggers `ESP_GATTC_DIS_SRVC_CMPL_EVT` only after the ACL connection is established. Otherwise, no events will be triggered.

  Parameters:

    remote_bda -- [in] Remote device address

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gattc_cache_assoc(esp_gatt_if_t gattc_if, esp_bd_addr_t src_addr, esp_bd_addr_t assoc_addr, bool is_assoc)

  Add or remove the association between the address in the local GATTC cache with the source address of the remote device.

  Note

  1. This API is primarily used when the client has a stored server-side database (`assoc_addr`) and needs to connect to another device (`src_addr`) with the same attribute database. By invoking this API, the stored database is utilized as the peer server database, eliminating the need for attribute database search and discovery. This reduces processing time and accelerates the connection process.

  2. The attribute table of a device with `assoc_addr` must be stored in the local GATTC cache first. Then, the attribute table of the device with `src_addr` must be the same as the one with `assoc_addr`.

  3. This function triggers `ESP_GATTC_SET_ASSOC_EVT`.

  Parameters:

    - gattc_if -- [in] GATT Client access interface

    - src_addr -- [in] The source address intended to be associated to the `assoc_addr` which has been stored in the local GATTC cache

    - assoc_addr -- [in] The associated device address intended to share the attribute table with the source address

    - is_assoc -- [in] True if adding the association; false if removing the association.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gattc_cache_get_addr_list(esp_gatt_if_t gattc_if)

  Get the address list stored in the local GATTC cache.

  Note

  This function triggers `ESP_GATTC_GET_ADDR_LIST_EVT`.

  Parameters:

    gattc_if -- [in] GATT Client access interface

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gattc_cache_clean(esp_bd_addr_t remote_bda)

  Clean the service cache of the target device in the local GATTC cache.

  Parameters:

    remote_bda -- [in] Remote device address

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

### Unions

union esp_ble_gattc_cb_param_t
  #include <esp_gattc_api.h>

  GATT Client callback parameters.

  Public Members

  struct esp_ble_gattc_cb_param_t::gattc_reg_evt_param reg

    Callback parameter for the event `ESP_GATTC_REG_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_open_evt_param open

    Callback parameter for the event `ESP_GATTC_OPEN_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_close_evt_param close

    Callback parameter for the event `ESP_GATTC_CLOSE_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_cfg_mtu_evt_param cfg_mtu

    Callback parameter for the event `ESP_GATTC_CFG_MTU_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_search_cmpl_evt_param search_cmpl

    Callback parameter for the event `ESP_GATTC_SEARCH_CMPL_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_search_res_evt_param search_res

    Callback parameter for the event `ESP_GATTC_SEARCH_RES_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_read_char_evt_param read

    Callback parameter for events: `ESP_GATTC_READ_CHAR_EVT`, `ESP_GATTC_READ_DESCR_EVT`, `ESP_GATTC_READ_MULTIPLE_EVT`, `ESP_GATTC_READ_MULTI_VAR_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_write_evt_param write

    Callback parameter for the events: `ESP_GATTC_WRITE_CHAR_EVT`, `ESP_GATTC_PREP_WRITE_EVT`, `ESP_GATTC_WRITE_DESCR_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_exec_cmpl_evt_param exec_cmpl

    Callback parameter for the event `ESP_GATTC_EXEC_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_notify_evt_param notify

    Callback parameter for the event `ESP_GATTC_NOTIFY_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_srvc_chg_evt_param srvc_chg

    Callback parameter for the event `ESP_GATTC_SRVC_CHG_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_congest_evt_param congest

    Callback parameter for the event `ESP_GATTC_CONGEST_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_reg_for_notify_evt_param reg_for_notify

    Callback parameter for the event `ESP_GATTC_REG_FOR_NOTIFY_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_unreg_for_notify_evt_param unreg_for_notify

    Callback parameter for the event `ESP_GATTC_UNREG_FOR_NOTIFY_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_connect_evt_param connect

    Callback parameter for the event `ESP_GATTC_CONNECT_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_disconnect_evt_param disconnect

    Callback parameter for the event `ESP_GATTC_DISCONNECT_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_set_assoc_addr_cmp_evt_param set_assoc_cmp

    Callback parameter for the event `ESP_GATTC_SET_ASSOC_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_get_addr_list_evt_param get_addr_list

    Callback parameter for the event `ESP_GATTC_GET_ADDR_LIST_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_queue_full_evt_param queue_full

    Callback parameter for the event `ESP_GATTC_QUEUE_FULL_EVT`

  struct esp_ble_gattc_cb_param_t::gattc_dis_srvc_cmpl_evt_param dis_srvc_cmpl

    Callback parameter for the event `ESP_GATTC_DIS_SRVC_CMPL_EVT`

  struct gattc_cfg_mtu_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_CFG_MTU_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

    uint16_t mtu

      MTU size

  struct gattc_close_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_CLOSE_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

    esp_bd_addr_t remote_bda

      Remote bluetooth device address

    esp_gatt_conn_reason_t reason

      The reason of GATT connection close

  struct gattc_congest_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_CONGEST_EVT`

    Public Members

    uint16_t conn_id

      Connection ID

    bool congested

      True indicates that the connection is congested, false otherwise

  struct gattc_connect_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_CONNECT_EVT`

    Public Members

    uint16_t conn_id

      Connection ID

    uint8_t link_role

      Link role : master role = 0; slave role = 1

    esp_bd_addr_t remote_bda

      Remote device address

    esp_gatt_conn_params_t conn_params

      Current connection parameters

    esp_ble_addr_type_t ble_addr_type

      Remote device address type

    uint16_t conn_handle

      HCI connection handle

  struct gattc_dis_srvc_cmpl_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_DIS_SRVC_CMPL_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

  struct gattc_disconnect_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_DISCONNECT_EVT`

    Public Members

    esp_gatt_conn_reason_t reason

      Disconnection reason

    uint16_t conn_id

      Connection ID

    esp_bd_addr_t remote_bda

      Remote device address

  struct gattc_exec_cmpl_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_EXEC_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

  struct gattc_get_addr_list_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_GET_ADDR_LIST_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint8_t num_addr

      The number of addresses in the local GATTC cache address list

    esp_bd_addr_t *addr_list

      The pointer to the address list which has been retrieved from the local GATTC cache

  struct gattc_notify_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_NOTIFY_EVT`

    Public Members

    uint16_t conn_id

      Connection ID

    esp_bd_addr_t remote_bda

      Remote Bluetooth device address.

    uint16_t handle

      The characteristic or descriptor handle

    uint16_t value_len

      Notify attribute value length in bytes

    uint8_t *value

      Notify attribute value

    bool is_notify

      True means notification; false means indication

  struct gattc_open_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_OPEN_EVT`.

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

    esp_bd_addr_t remote_bda

      Remote Bluetooth device address

    uint16_t mtu

      MTU size

  struct gattc_queue_full_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_QUEUE_FULL_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

    bool is_full

      True indicates the GATTC command queue is full; false otherwise.

  struct gattc_read_char_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the events: `ESP_GATTC_READ_CHAR_EVT`, `ESP_GATTC_READ_DESCR_EVT`, `ESP_GATTC_READ_MULTIPLE_EVT`, `ESP_GATTC_READ_MULTI_VAR_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

    uint16_t handle

      Characteristic handle

    uint8_t *value

      Characteristic value

    uint16_t value_len

      Characteristic value length

  struct gattc_reg_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_REG_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t app_id

      Application ID

  struct gattc_reg_for_notify_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_REG_FOR_NOTIFY_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t handle

      The characteristic or descriptor handle

  struct gattc_search_cmpl_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_SEARCH_CMPL_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

    esp_service_source_t searched_service_source

      The source of the service information

  struct gattc_search_res_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_SEARCH_RES_EVT`

    Public Members

    uint16_t conn_id

      Connection ID

    uint16_t start_handle

      Service start handle

    uint16_t end_handle

      Service end handle

    esp_gatt_id_t srvc_id

      Service ID, including service UUID and other information

    bool is_primary

      True indicates a primary service, false otherwise

  struct gattc_set_assoc_addr_cmp_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_SET_ASSOC_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

  struct gattc_srvc_chg_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_SRVC_CHG_EVT`

    Public Members

    esp_bd_addr_t remote_bda

      Remote Bluetooth device address

  struct gattc_unreg_for_notify_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the event `ESP_GATTC_UNREG_FOR_NOTIFY_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t handle

      The characteristic or descriptor handle

  struct gattc_write_evt_param
    #include <esp_gattc_api.h>

    Callback parameter for the events: `ESP_GATTC_WRITE_CHAR_EVT`, `ESP_GATTC_PREP_WRITE_EVT`, `ESP_GATTC_WRITE_DESCR_EVT`.

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

    uint16_t handle

      The characteristic or descriptor handle

    uint16_t offset

      The position offset to write. This value is valid only for prepare write operation.

### Type Definitions

typedef void (*esp_gattc_cb_t)(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if, esp_ble_gattc_cb_param_t *param)

  GATT Client callback function type.

  Param event:

    [in] Event type

  Param gattc_if:

    [in] GATT Client access interface

  Param param:

    [in] The pointer to callback parameter

### Enumerations

enum esp_gattc_cb_event_t

  GATT Client callback function events.

  Values:

  enumerator ESP_GATTC_REG_EVT

    This event is triggered when a GATT Client application is registered using `esp_ble_gattc_app_register`.

  enumerator ESP_GATTC_UNREG_EVT

    This event is triggered when a GATT Client application is unregistered using `esp_ble_gattc_app_unregister`.

  enumerator ESP_GATTC_OPEN_EVT

    This event is triggered when a GATT virtual connection is set up using `esp_ble_gattc_open`.

  enumerator ESP_GATTC_READ_CHAR_EVT

    This event is triggered upon the completion of a GATT characteristic read operation using `esp_ble_gattc_read_char`.

  enumerator ESP_GATTC_WRITE_CHAR_EVT

    This event is triggered upon the completion of a GATT characteristic write operation using `esp_ble_gattc_write_char`.

  enumerator ESP_GATTC_CLOSE_EVT

    This event is triggered when a GATT virtual connection is closed via `esp_ble_gattc_close`, or when the physical connection is terminated.

  enumerator ESP_GATTC_SEARCH_CMPL_EVT

    This event is triggered upon the completion of a service discovery using `esp_ble_gattc_search_service`.

  enumerator ESP_GATTC_SEARCH_RES_EVT

    This event is triggered each time a service result is obtained using `esp_ble_gattc_search_service`.

  enumerator ESP_GATTC_READ_DESCR_EVT

    This event is triggered upon the completion of a GATT characteristic descriptor read operation using `esp_ble_gattc_read_char_descr`.

  enumerator ESP_GATTC_WRITE_DESCR_EVT

    This event is triggered upon the completion of a GATT characteristic descriptor write operation using `esp_ble_gattc_write_char_descr`.

  enumerator ESP_GATTC_NOTIFY_EVT

    This event is triggered when a GATT notification or indication is received from the Server.

  enumerator ESP_GATTC_PREP_WRITE_EVT

    This event is triggered upon the completion of a GATT prepare-write operation using `esp_ble_gattc_prepare_write`.

  enumerator ESP_GATTC_EXEC_EVT

    This event is triggered upon the completion of a GATT write execution using `esp_ble_gattc_execute_write` .

  enumerator ESP_GATTC_ACL_EVT

    Deprecated.

  enumerator ESP_GATTC_CANCEL_OPEN_EVT

    Deprecated.

  enumerator ESP_GATTC_SRVC_CHG_EVT

    This event is triggered when a service changed indication is received from the Server, indicating that the attribute database on the Server has been modified (e.g., services have been added, removed).

  enumerator ESP_GATTC_ENC_CMPL_CB_EVT

    Deprecated.

  enumerator ESP_GATTC_CFG_MTU_EVT

    This event is triggered upon the completion of the MTU configuration with `esp_ble_gattc_send_mtu_req`.

  enumerator ESP_GATTC_ADV_DATA_EVT

    Deprecated.

  enumerator ESP_GATTC_MULT_ADV_ENB_EVT

    Deprecated.

  enumerator ESP_GATTC_MULT_ADV_UPD_EVT

    Deprecated.

  enumerator ESP_GATTC_MULT_ADV_DATA_EVT

    Deprecated.

  enumerator ESP_GATTC_MULT_ADV_DIS_EVT

    Deprecated.

  enumerator ESP_GATTC_CONGEST_EVT

    This event is triggered when the GATT connection is congested.

  enumerator ESP_GATTC_BTH_SCAN_ENB_EVT

    Deprecated.

  enumerator ESP_GATTC_BTH_SCAN_CFG_EVT

    Deprecated.

  enumerator ESP_GATTC_BTH_SCAN_RD_EVT

    Deprecated.

  enumerator ESP_GATTC_BTH_SCAN_THR_EVT

    Deprecated.

  enumerator ESP_GATTC_BTH_SCAN_PARAM_EVT

    Deprecated.

  enumerator ESP_GATTC_BTH_SCAN_DIS_EVT

    Deprecated.

  enumerator ESP_GATTC_SCAN_FLT_CFG_EVT

    Deprecated.

  enumerator ESP_GATTC_SCAN_FLT_PARAM_EVT

    Deprecated.

  enumerator ESP_GATTC_SCAN_FLT_STATUS_EVT

    Deprecated.

  enumerator ESP_GATTC_ADV_VSC_EVT

    Deprecated.

  enumerator ESP_GATTC_REG_FOR_NOTIFY_EVT

    This event is triggered upon the completion of a service notification registration using `esp_ble_gattc_register_for_notify`.

  enumerator ESP_GATTC_UNREG_FOR_NOTIFY_EVT

    This event is triggered upon the completion of a service notification unregistration using `esp_ble_gattc_unregister_for_notify`.

  enumerator ESP_GATTC_CONNECT_EVT

    This event is triggered when the physical connection is set up.

  enumerator ESP_GATTC_DISCONNECT_EVT

    This event is triggered when the physical connection is terminated.

  enumerator ESP_GATTC_READ_MULTIPLE_EVT

    This event is triggered when the multiple characteristic or descriptor values are retrieved using `esp_ble_gattc_read_multiple`.

  enumerator ESP_GATTC_QUEUE_FULL_EVT

    This event is triggered when the GATTC command queue is full.

  enumerator ESP_GATTC_SET_ASSOC_EVT

    This event is triggered when the association between the source and the remote address is added or deleted using `esp_ble_gattc_cache_assoc`.

  enumerator ESP_GATTC_GET_ADDR_LIST_EVT

    This event is triggered when retrieving the address list from the GATTC cache is completed using `esp_ble_gattc_cache_get_addr_list`.

  enumerator ESP_GATTC_DIS_SRVC_CMPL_EVT

    This event is triggered when the GATT service discovery is completed.

  enumerator ESP_GATTC_READ_MULTI_VAR_EVT

    This event is triggered when multiple variable length characteristic values are retrieved using `esp_ble_gattc_read_multiple`.

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.