# GATT Server API

[中文]

## Application Examples

- bluetooth/bluedroid/ble/gatt_server_service_table demonstrates how to create a GATT service using an attribute table, releasing the user from adding attributes individually.

- bluetooth/bluedroid/ble/gatt_server demonstrates how to create a GATT service by adding attributes individually and then starts advertising so that a GATT client can connect and exchange data.

## API Reference

### Header File

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

- This header file can be included with:

  >     #include "esp_gatts_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_gatts_register_callback(esp_gatts_cb_t callback)

  Register GATT Server application callbacks.

  Note

  Do NOT perform time-consuming operations in the callback. Time-consuming operations include: taking semaphores that may block for a long time (e.g. xSemaphoreTake with long timeout or portMAX_DELAY), blocking delays (e.g. vTaskDelay), and flash read/write/erase. Such operations may block the Bluetooth stack and lead to instability or deadlock. Defer heavy work to a separate task if needed.

  Parameters:

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

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_gatts_cb_t esp_ble_gatts_get_callback(void)

  Get the current GATT Server application callback.

  Returns:

    - esp_gatts_cb_t: Current callback

esp_err_t esp_ble_gatts_app_register(uint16_t app_id)

  Register GATT Server application.

  Note

  1. This function triggers `ESP_GATTS_REG_EVT`.

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

  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_gatts_app_unregister(esp_gatt_if_t gatts_if)

  Unregister an GATT Server application.

  Note

  1. This function triggers `ESP_GATTS_UNREG_EVT`.

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

  Parameters:

    gatts_if -- [in] GATT Server access interface.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gatts_create_service(esp_gatt_if_t gatts_if, esp_gatt_srvc_id_t *service_id, uint16_t num_handle)

  Create a GATT Server service.

  Note

  1. This function triggers `ESP_GATTS_CREATE_EVT`.

  2. `num_handle` should not be greater than CONFIG_BT_GATT_MAX_SR_ATTRIBUTES.

  Parameters:

    - gatts_if -- [in] GATT Server access interface

    - service_id -- [in] The pointer to the Service ID

    - num_handle -- [in] The number of handles requested for this service.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gatts_create_attr_tab(const esp_gatts_attr_db_t *gatts_attr_db, esp_gatt_if_t gatts_if, uint16_t max_nb_attr, uint8_t srvc_inst_id)

  Create a service attribute table.

  Note

  1. This function triggers `ESP_GATTS_CREAT_ATTR_TAB_EVT`.

  2. `max_nb_attr` should not be greater than CONFIG_BT_GATT_MAX_SR_ATTRIBUTES.

  Parameters:

    - gatts_attr_db -- [in] The pointer to the service attribute table

    - gatts_if -- [in] GATT Server access interface

    - max_nb_attr -- [in] The number of attributes to be added to the service database

    - srvc_inst_id -- [in] The instance ID of the service

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_ARG: Invalid `max_nb_attr`

    - ESP_FAIL: Failure

esp_err_t esp_ble_gatts_add_included_service(uint16_t service_handle, uint16_t included_service_handle)

  Add an included service.

  Note

  1. This function triggers `ESP_GATTS_ADD_INCL_SRVC_EVT`.

  2. This function has to be called between `esp_ble_gatts_create_service` and `esp_ble_gatts_add_char`.

  Parameters:

    - service_handle -- [in] Target service handle to add

    - included_service_handle -- [in] The handle of included service to be added

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gatts_add_char(uint16_t service_handle, esp_bt_uuid_t *char_uuid, esp_gatt_perm_t perm, esp_gatt_char_prop_t property, esp_attr_value_t *char_val, esp_attr_control_t *control)

  Add a characteristic into a service.

  Note

  1. This function triggers `ESP_GATTS_ADD_CHAR_EVT`.

  2. `control->auto_rsp` should be set to `ESP_GATT_AUTO_RSP` or `ESP_GATT_RSP_BY_APP`.

  3. For stack respond attribute (`ESP_GATT_AUTO_RSP`), `char_val` should not be NULL and `char_val->attr_max_len` must be greater than 0.

  Parameters:

    - service_handle -- [in] Target service handle to add the characteristic

    - char_uuid -- [in] The pointer to the characteristic UUID

    - perm -- [in] Characteristic value declaration attribute permission

    - property -- [in] Characteristic Properties

    - char_val -- [in] The pointer to the characteristic value

    - control -- [in] The pointer to the attribute response control byte

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_ARG: Invalid arguments

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gatts_add_char_descr(uint16_t service_handle, esp_bt_uuid_t *descr_uuid, esp_gatt_perm_t perm, esp_attr_value_t *char_descr_val, esp_attr_control_t *control)

  Add a characteristic descriptor.

  Note

  1. This function triggers `ESP_GATTS_ADD_CHAR_DESCR_EVT`.

  2. `control->auto_rsp` should be set to `ESP_GATT_AUTO_RSP` or `ESP_GATT_RSP_BY_APP`.

  3. For stack respond attribute (`ESP_GATT_AUTO_RSP`), `char_val` should not be NULL and `char_val->attr_max_len` must be greater than 0.

  Parameters:

    - service_handle -- [in] Target service handle to add the characteristic descriptor

    - descr_uuid -- [in] The pointer to the descriptor UUID

    - perm -- [in] Descriptor access permission

    - char_descr_val -- [in] The pointer to the characteristic descriptor value

    - control -- [in] The pointer to the attribute response control byte

  Returns:

    - ESP_OK: Success

    - ESP_ERR_INVALID_ARG: Invalid arguments

    - ESP_FAIL: Failure due to other reasons

esp_err_t esp_ble_gatts_delete_service(uint16_t service_handle)

  Delete a service.

  Note

  This function triggers `ESP_GATTS_DELETE_EVT`.

  Parameters:

    service_handle -- [in] Target service handle to delete

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gatts_start_service(uint16_t service_handle)

  Start a service.

  Note

  This function triggers `ESP_GATTS_START_EVT`.

  Parameters:

    service_handle -- [in] Target service handle to start

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gatts_stop_service(uint16_t service_handle)

  Stop a service.

  Note

  This function triggers `ESP_GATTS_STOP_EVT`.

  Parameters:

    service_handle -- [in] Target service handle to stop

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gatts_send_indicate(esp_gatt_if_t gatts_if, uint16_t conn_id, uint16_t attr_handle, uint16_t value_len, uint8_t *value, bool need_confirm)

  Send indication or notification to a GATT Client.

  Note

  1. This function triggers `ESP_GATTS_CONF_EVT`.

  2. The size of indication or notification data must be less than or equal to MTU size, see `esp_ble_gattc_send_mtu_req`.

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

  Parameters:

    - gatts_if -- [in] GATT Server access interface

    - conn_id -- [in] Connection ID

    - attr_handle -- [in] Attribute handle to indicate

    - value_len -- [in] Indication value length in bytes

    - value -- [in] Value to indicate

    - need_confirm -- [in] True if a confirmation is required, which is a GATT indication; false if the confirmation is not required, which is a GATT notification.

  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_gatts_send_response(esp_gatt_if_t gatts_if, uint16_t conn_id, uint32_t trans_id, esp_gatt_status_t status, esp_gatt_rsp_t *rsp)

  Send a response to a request.

  Note

  1. This function triggers `ESP_GATTS_RESPONSE_EVT`.

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

  Parameters:

    - gatts_if -- [in] GATT Server access interface

    - conn_id -- [in] Connection ID

    - trans_id -- [in] Transfer ID

    - status -- [in] Response status

    - rsp -- [in] The pointer to the response data

  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_gatts_set_attr_value(uint16_t attr_handle, uint16_t length, const uint8_t *value)

  Set the attribute value.

  Note

  This function triggers `ESP_GATTS_SET_ATTR_VAL_EVT`.

  Parameters:

    - attr_handle -- [in] Target attribute handle to set the value

    - length -- [in] The value length in bytes

    - value -- [in] The pointer to the attribute value

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_gatt_status_t esp_ble_gatts_get_attr_value(uint16_t attr_handle, uint16_t *length, const uint8_t **value)

  Retrieve attribute value.

  Note

  1. This function does not trigger any event.

  2. `attr_handle` must be greater than 0.

  Parameters:

    - attr_handle -- [in] Attribute handle

    - length -- [out] The pointer to the attribute value length in bytes

    - value -- [out] The pointer to attribute value payload. This value cannot be modified by user.

  Returns:

    - ESP_GATT_OK: Success

    - ESP_GATT_WRONG_STATE: Bluedroid stack is not enabled

    - ESP_GATT_INVALID_PDU: NULL pointer to `length` or `value`

    - ESP_GATT_INVALID_HANDLE: Invalid `attr_handle`

    - Other `esp_gatt_status_t` values: Failure due to other reasons

esp_err_t esp_ble_gatts_open(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda, 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_GATTS_CONNECT_EVT` and `ESP_GATTS_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 Server. If the ACL connection already exists, it will create a virtual connection only.

  Parameters:

    - gatts_if -- [in] GATT Server access interface

    - remote_bda -- [in] Remote device address

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

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gatts_close(esp_gatt_if_t gatts_if, uint16_t conn_id)

  Close a connection with a remote device.

  Note

  1. This function triggers `ESP_GATTS_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 trigger `ESP_GATTS_DISCONNECT_EVT`. Then there is no need to call `esp_ble_gap_disconnect` anymore.

  Parameters:

    - gatts_if -- [in] GATT Server access interface

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

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gatts_send_service_change_indication(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda)

  Send service change indication.

  Note

  This function triggers `ESP_GATTS_SEND_SERVICE_CHANGE_EVT`.

  Parameters:

    - gatts_if -- [in] GATT Server access interface

    - remote_bda -- [in] Remote device address. If remote_bda is NULL then it will send service change indication to all the connected devices and if not then to a specific device.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

esp_err_t esp_ble_gatts_show_local_database(void)

  Display the Server's local attribute database.

  This API prints the local attribute database of the BLE server, including details of all services, characteristics, and descriptors.

  Note

  1. This function does not trigger any event.

  2. It is primarily intended for debugging purposes to verify the server's current configuration.

  Returns:

    - ESP_OK: Success

    - ESP_FAIL: Failure

### Unions

union esp_ble_gatts_cb_param_t
  #include <esp_gatts_api.h>

  GATT Server callback parameters.

  Public Members

  struct esp_ble_gatts_cb_param_t::gatts_reg_evt_param reg

    Callback parameter for the event `ESP_GATTS_REG_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_read_evt_param read

    Callback parameter for the event `ESP_GATTS_READ_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_write_evt_param write

    Callback parameter for the event `ESP_GATTS_WRITE_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_exec_write_evt_param exec_write

    Callback parameter for the event `ESP_GATTS_EXEC_WRITE_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_mtu_evt_param mtu

    Callback parameter for the event `ESP_GATTS_MTU_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_conf_evt_param conf

    Callback parameter for the event `ESP_GATTS_CONF_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_create_evt_param create

    Callback parameter for the event `ESP_GATTS_CREATE_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt_param add_incl_srvc

    Callback parameter for the event `ESP_GATTS_ADD_INCL_SRVC_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_add_char_evt_param add_char

    Callback parameter for the event `ESP_GATTS_ADD_CHAR_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_add_char_descr_evt_param add_char_descr

    Callback parameter for the event `ESP_GATTS_ADD_CHAR_DESCR_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_delete_evt_param del

    Callback parameter for the event `ESP_GATTS_DELETE_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_start_evt_param start

    Callback parameter for the event `ESP_GATTS_START_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_stop_evt_param stop

    Callback parameter for the event `ESP_GATTS_STOP_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_connect_evt_param connect

    Callback parameter for the event `ESP_GATTS_CONNECT_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_disconnect_evt_param disconnect

    Callback parameter for the event `ESP_GATTS_DISCONNECT_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_open_evt_param open

    Callback parameter for the event `ESP_GATTS_OPEN_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_cancel_open_evt_param cancel_open

    Callback parameter for the event `ESP_GATTS_CANCEL_OPEN_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_close_evt_param close

    Callback parameter for the event `ESP_GATTS_CLOSE_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_congest_evt_param congest

    Callback parameter for the event `ESP_GATTS_CONGEST_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_rsp_evt_param rsp

    Callback parameter for the event `ESP_GATTS_RESPONSE_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_param add_attr_tab

    Callback parameter for the event `ESP_GATTS_CREAT_ATTR_TAB_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_set_attr_val_evt_param set_attr_val

    Callback parameter for the event `ESP_GATTS_SET_ATTR_VAL_EVT`

  struct esp_ble_gatts_cb_param_t::gatts_send_service_change_evt_param service_change

    Callback parameter for the event `ESP_GATTS_SEND_SERVICE_CHANGE_EVT`

  struct gatts_add_attr_tab_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_CREAT_ATTR_TAB_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    esp_bt_uuid_t svc_uuid

      Service UUID type

    uint8_t svc_inst_id

      Service ID

    uint16_t num_handle

      The number of the attribute handles which have been added to the GATT Service table

    uint16_t *handles

      The handles which have been added to the table

  struct gatts_add_char_descr_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_ADD_CHAR_DESCR_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t attr_handle

      Descriptor attribute handle

    uint16_t service_handle

      Service attribute handle

    esp_bt_uuid_t descr_uuid

      Characteristic descriptor UUID

  struct gatts_add_char_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_ADD_CHAR_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t attr_handle

      Characteristic attribute handle

    uint16_t service_handle

      Service attribute handle

    esp_bt_uuid_t char_uuid

      Characteristic UUID

  struct gatts_add_incl_srvc_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_ADD_INCL_SRVC_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t attr_handle

      Included service attribute handle

    uint16_t service_handle

      Service attribute handle

  struct gatts_cancel_open_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_CANCEL_OPEN_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

  struct gatts_close_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_CLOSE_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

  struct gatts_conf_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_CONF_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

    uint16_t handle

      Attribute handle

    uint16_t len

      The length of indication or notification value in bytes. The length is invalid if the notification or indication failed.

    uint8_t *value

      The indication or notification value. The value is invalid if the notification or indication failed.

  struct gatts_congest_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_CONGEST_EVT`

    Public Members

    uint16_t conn_id

      Connection ID

    bool congested

      True indicates the connection is congested; false otherwise.

  struct gatts_connect_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_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 gatts_create_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_CREATE_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t service_handle

      Service attribute handle

    esp_gatt_srvc_id_t service_id

      Service ID, including service UUID and other information

  struct gatts_delete_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_DELETE_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t service_handle

      Service attribute handle

  struct gatts_disconnect_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_DISCONNECT_EVT`

    Public Members

    uint16_t conn_id

      Connection ID

    esp_bd_addr_t remote_bda

      Remote device address

    esp_gatt_conn_reason_t reason

      The reason of disconnection

  struct gatts_exec_write_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_EXEC_WRITE_EVT`

    Public Members

    uint16_t conn_id

      Connection ID

    uint32_t trans_id

      Transfer ID

    esp_bd_addr_t bda

      The bluetooth device address to write

    uint8_t exec_write_flag

      Execute write flag: `ESP_GATT_PREP_WRITE_CANCEL` or `ESP_GATT_PREP_WRITE_EXEC`

  struct gatts_mtu_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_MTU_EVT`

    Public Members

    uint16_t conn_id

      Connection ID

    uint16_t mtu

      MTU size

  struct gatts_open_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_OPEN_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

  struct gatts_read_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_READ_EVT`

    Public Members

    uint16_t conn_id

      Connection ID

    uint32_t trans_id

      Transfer ID

    esp_bd_addr_t bda

      The device address to read

    uint16_t handle

      The attribute handle

    uint16_t offset

      The position offset to read. If the length of value is less than or equal to the MTU size, this value is 0.

    bool is_long

      True indicates that the length of value is greater than the MTU size; false otherwise.

    bool need_rsp

      True indicates that the `esp_ble_gatts_send_response` is required in the following step; false otherwise.

  struct gatts_reg_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_REG_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t app_id

      Application ID

  struct gatts_rsp_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_RESPONSE_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t conn_id

      Connection ID

    uint16_t handle

      Attribute handle which sends the response

  struct gatts_send_service_change_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_SEND_SERVICE_CHANGE_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

  struct gatts_set_attr_val_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_SET_ATTR_VAL_EVT`

    Public Members

    uint16_t srvc_handle

      The service handle

    uint16_t attr_handle

      The attribute handle

    esp_gatt_status_t status

      Operation status

  struct gatts_start_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_START_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t service_handle

      Service attribute handle

  struct gatts_stop_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_STOP_EVT`

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t service_handle

      Service attribute handle

  struct gatts_write_evt_param
    #include <esp_gatts_api.h>

    Callback parameter for the event `ESP_GATTS_WRITE_EVT`

    Public Members

    uint16_t conn_id

      Connection ID

    uint32_t trans_id

      Transfer ID

    esp_bd_addr_t bda

      The device address to write

    uint16_t handle

      The attribute handle

    uint16_t offset

      The position offset to write. If the length of value is less than or equal to the MTU size, this value is 0.

    bool need_rsp

      True indicates that the `esp_ble_gatts_send_response` is required in the following step; false otherwise.

    bool is_prep

      True indicates the write operation is a prepared write operation

    uint16_t len

      The length of the write attribute value in bytes

    uint8_t *value

      The write attribute value

### Macros

ESP_GATT_PREP_WRITE_CANCEL

  Flag to indicate the cancellation of a prepare write operation

ESP_GATT_PREP_WRITE_EXEC

  Flag to indicate the execution of a prepare write operation

### Type Definitions

typedef void (*esp_gatts_cb_t)(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if, esp_ble_gatts_cb_param_t *param)

  GATT Server callback function type.

  Param event:

    [in] Event type

  Param gatts_if:

    [in] GATT Server access interface. Typically, different `gatts_if` values correspond to different profiles.

  Param param:

    [in] The pointer to the callback parameter, which is of a union type.

### Enumerations

enum esp_gatts_cb_event_t

  GATT Server callback function events.

  Values:

  enumerator ESP_GATTS_REG_EVT

    This event is triggered when a GATT Server application is registered using `esp_ble_gatts_app_register`.

  enumerator ESP_GATTS_READ_EVT

    This event is triggered when the read request from the Client is received.

  enumerator ESP_GATTS_WRITE_EVT

    This event is triggered when the write request from the Client is received.

  enumerator ESP_GATTS_EXEC_WRITE_EVT

    This event is triggered when the write execution request from the Client is received.

  enumerator ESP_GATTS_MTU_EVT

    This event is triggered when the MTU configuration request from the Client is received.

  enumerator ESP_GATTS_CONF_EVT

    This event is triggered when the confirmation from the Client is received.

  enumerator ESP_GATTS_UNREG_EVT

    This event is triggered when a GATT Server application is unregistered using `esp_ble_gatts_app_unregister`.

  enumerator ESP_GATTS_CREATE_EVT

    This event is triggered when a GATT Server service is created using `esp_ble_gatts_create_service`.

  enumerator ESP_GATTS_ADD_INCL_SRVC_EVT

    This event is triggered when an included service is added using `esp_ble_gatts_add_included_service`.

  enumerator ESP_GATTS_ADD_CHAR_EVT

    This event is triggered when a characteristic is added to the service using `esp_ble_gatts_add_char`.

  enumerator ESP_GATTS_ADD_CHAR_DESCR_EVT

    This event is triggered when a characteristic descriptor is added to the service using `esp_ble_gatts_add_char_descr`.

  enumerator ESP_GATTS_DELETE_EVT

    This event is triggered when the service is deleted using `esp_ble_gatts_delete_service`.

  enumerator ESP_GATTS_START_EVT

    This event is triggered when the service is started using `esp_ble_gatts_start_service`.

  enumerator ESP_GATTS_STOP_EVT

    This event is triggered when the service is stopped using `esp_ble_gatts_stop_service`.

  enumerator ESP_GATTS_CONNECT_EVT

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

  enumerator ESP_GATTS_DISCONNECT_EVT

    This event is triggered when a physical connection is terminated.

  enumerator ESP_GATTS_OPEN_EVT

    This event is triggered when a virtual connection is created using `esp_ble_gatts_open`.

  enumerator ESP_GATTS_CANCEL_OPEN_EVT

    Deprecated.

  enumerator ESP_GATTS_CLOSE_EVT

    This event is triggered when a virtual connection is closed using `esp_ble_gatts_close`.

  enumerator ESP_GATTS_LISTEN_EVT

    Deprecated.

  enumerator ESP_GATTS_CONGEST_EVT

    This event is triggered when the GATT connection is congested.

  enumerator ESP_GATTS_RESPONSE_EVT

    This event is triggered when a response is sent to the request using `esp_ble_gatts_send_response`.

  enumerator ESP_GATTS_CREAT_ATTR_TAB_EVT

    This event is triggered when a service attribute table is created using `esp_ble_gatts_create_attr_tab`.

  enumerator ESP_GATTS_SET_ATTR_VAL_EVT

    This event is triggered when an attribute value is set using `esp_ble_gatts_set_attr_value`.

  enumerator ESP_GATTS_SEND_SERVICE_CHANGE_EVT

    This event is triggered when a service change indication is sent using `esp_ble_gatts_send_service_change_indication`.

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.