# GATT 服务器 API

[English]

## 应用示例

- bluetooth/bluedroid/ble/gatt_server_service_table 演示如何使用属性表创建 GATT Service，从而无需逐个添加属性。

- bluetooth/bluedroid/ble/gatt_server 演示如何逐个添加属性来创建 GATT Service，并开始广播，以便 GATT Client 进行连接并交换数据。

## API 参考

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

  This function is called to register application callbacks with BTA GATTS module.

  返回

    - ESP_OK : success

    - other : failed

esp_gatts_cb_t esp_ble_gatts_get_callback(void)

  This function is called to get the current application callbacks with BTA GATTS module.

  返回

    - esp_gatts_cb_t : current callback

esp_err_t esp_ble_gatts_app_register(uint16_t app_id)

  This function is called to register application identifier.

  返回

    - ESP_OK : success

    - other : failed

esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatts_if)

  unregister with GATT Server.

  参数

    gatts_if -- [in] GATT server access interface

  返回

    - ESP_OK : success

    - other : failed

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 service. When service creation is done, a callback event ESP_GATTS_CREATE_EVT is called to report status and service ID to the profile. The service ID obtained in the callback function needs to be used when adding included service and characteristics/descriptors into the service.

  参数

    - gatts_if -- [in] GATT server access interface

    - service_id -- [in] service ID.

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

  返回

    - ESP_OK : success

    - other : failed

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

  参数

    - gatts_attr_db -- [in] the pointer to the service attr tab

    - gatts_if -- [in] GATT server access interface

    - max_nb_attr -- [in] the number of attribute to be added to the service database.

    - srvc_inst_id -- [in] the instance id of the service

  返回

    - ESP_OK : success

    - other : failed

esp_err_t esp_ble_gatts_add_included_service(uint16_t service_handle, uint16_t included_service_handle)

  This function is called to add an included service. This function have to be called between 'esp_ble_gatts_create_service' and 'esp_ble_gatts_add_char'. After included service is included, a callback event ESP_GATTS_ADD_INCL_SRVC_EVT is reported the included service ID.

  参数

    - service_handle -- [in] service handle to which this included service is to be added.

    - included_service_handle -- [in] the service ID to be included.

  返回

    - ESP_OK : success

    - other : failed

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)

  This function is called to add a characteristic into a service.

  参数

    - service_handle -- [in] service handle to which this included service is to be added.

    - char_uuid -- [in] : Characteristic UUID.

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

    - property -- [in] : Characteristic Properties

    - char_val -- [in] : Characteristic value

    - control -- [in] : attribute response control byte

  返回

    - ESP_OK : success

    - other : failed

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)

  This function is called to add characteristic descriptor. When it's done, a callback event ESP_GATTS_ADD_DESCR_EVT is called to report the status and an ID number for this descriptor.

  参数

    - service_handle -- [in] service handle to which this characteristic descriptor is to be added.

    - perm -- [in] descriptor access permission.

    - descr_uuid -- [in] descriptor UUID.

    - char_descr_val -- [in] : Characteristic descriptor value

    - control -- [in] : attribute response control byte

  返回

    - ESP_OK : success

    - other : failed

esp_err_t esp_ble_gatts_delete_service(uint16_t service_handle)

  This function is called to delete a service. When this is done, a callback event ESP_GATTS_DELETE_EVT is report with the status.

  参数

    service_handle -- [in] service_handle to be deleted.

  返回

    - ESP_OK : success

    - other : failed

esp_err_t esp_ble_gatts_start_service(uint16_t service_handle)

  This function is called to start a service.

  参数

    service_handle -- [in] the service handle to be started.

  返回

    - ESP_OK : success

    - other : failed

esp_err_t esp_ble_gatts_stop_service(uint16_t service_handle)

  This function is called to stop a service.

  参数

    service_handle -- [in] - service to be topped.

  返回

    - ESP_OK : success

    - other : failed

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 indicate or notify to GATT client. Set param need_confirm as false will send notification, otherwise indication. Note: the size of indicate or notify data need less than MTU size,see "esp_ble_gattc_send_mtu_req".

  参数

    - gatts_if -- [in] GATT server access interface

    - conn_id -- [in] - connection id to indicate.

    - attr_handle -- [in] - attribute handle to indicate.

    - value_len -- [in] - indicate value length.

    - value -- [in] value to indicate.

    - need_confirm -- [in] - Whether a confirmation is required. false sends a GATT notification, true sends a GATT indication.

  返回

    - ESP_OK : success

    - other : failed

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)

  This function is called to send a response to a request.

  参数

    - gatts_if -- [in] GATT server access interface

    - conn_id -- [in] - connection identifier.

    - trans_id -- [in] - transfer id

    - status -- [in] - response status

    - rsp -- [in] - response data.

  返回

    - ESP_OK : success

    - other : failed

esp_err_t esp_ble_gatts_set_attr_value(uint16_t attr_handle, uint16_t length, const uint8_t *value)

  This function is called to set the attribute value by the application.

  参数

    - attr_handle -- [in] the attribute handle which to be set

    - length -- [in] the value length

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

  返回

    - ESP_OK : success

    - other : failed

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

  Retrieve attribute value.

  参数

    - attr_handle -- [in] Attribute handle.

    - length -- [out] pointer to the attribute value length

    - value -- [out] Pointer to attribute value payload, the value cannot be modified by user

  返回

    - ESP_GATT_OK : success

    - other : failed

esp_err_t esp_ble_gatts_open(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda, bool is_direct)

  Open a direct open connection or add a background auto connection.

  参数

    - gatts_if -- [in] GATT server access interface

    - remote_bda -- [in] remote device bluetooth device address.

    - is_direct -- [in] direct connection or background auto connection

  返回

    - ESP_OK : success

    - other : failed

esp_err_t esp_ble_gatts_close(esp_gatt_if_t gatts_if, uint16_t conn_id)

  Close a connection a remote device.

  参数

    - gatts_if -- [in] GATT server access interface

    - conn_id -- [in] connection ID to be closed.

  返回

    - ESP_OK : success

    - other : failed

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.

  参数

    - gatts_if -- [in] GATT server access interface

    - remote_bda -- [in] remote device bluetooth 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

  返回

    - ESP_OK : success

    - other : failed

esp_err_t esp_ble_gatts_show_local_database(void)

  Print local database (GATT service table)

  返回

    - ESP_OK : success

    - other : failed

### Unions

union esp_ble_gatts_cb_param_t
  #include <esp_gatts_api.h>

  Gatt server callback parameters union.

  Public Members

  struct esp_ble_gatts_cb_param_t::gatts_reg_evt_param reg

    Gatt server callback param of ESP_GATTS_REG_EVT

  struct esp_ble_gatts_cb_param_t::gatts_read_evt_param read

    Gatt server callback param of ESP_GATTS_READ_EVT

  struct esp_ble_gatts_cb_param_t::gatts_write_evt_param write

    Gatt server callback param of ESP_GATTS_WRITE_EVT

  struct esp_ble_gatts_cb_param_t::gatts_exec_write_evt_param exec_write

    Gatt server callback param of ESP_GATTS_EXEC_WRITE_EVT

  struct esp_ble_gatts_cb_param_t::gatts_mtu_evt_param mtu

    Gatt server callback param of ESP_GATTS_MTU_EVT

  struct esp_ble_gatts_cb_param_t::gatts_conf_evt_param conf

    Gatt server callback param of ESP_GATTS_CONF_EVT (confirm)

  struct esp_ble_gatts_cb_param_t::gatts_create_evt_param create

    Gatt server callback param of ESP_GATTS_CREATE_EVT

  struct esp_ble_gatts_cb_param_t::gatts_add_incl_srvc_evt_param add_incl_srvc

    Gatt server callback param of ESP_GATTS_ADD_INCL_SRVC_EVT

  struct esp_ble_gatts_cb_param_t::gatts_add_char_evt_param add_char

    Gatt server callback param of ESP_GATTS_ADD_CHAR_EVT

  struct esp_ble_gatts_cb_param_t::gatts_add_char_descr_evt_param add_char_descr

    Gatt server callback param of ESP_GATTS_ADD_CHAR_DESCR_EVT

  struct esp_ble_gatts_cb_param_t::gatts_delete_evt_param del

    Gatt server callback param of ESP_GATTS_DELETE_EVT

  struct esp_ble_gatts_cb_param_t::gatts_start_evt_param start

    Gatt server callback param of ESP_GATTS_START_EVT

  struct esp_ble_gatts_cb_param_t::gatts_stop_evt_param stop

    Gatt server callback param of ESP_GATTS_STOP_EVT

  struct esp_ble_gatts_cb_param_t::gatts_connect_evt_param connect

    Gatt server callback param of ESP_GATTS_CONNECT_EVT

  struct esp_ble_gatts_cb_param_t::gatts_disconnect_evt_param disconnect

    Gatt server callback param of ESP_GATTS_DISCONNECT_EVT

  struct esp_ble_gatts_cb_param_t::gatts_open_evt_param open

    Gatt server callback param of ESP_GATTS_OPEN_EVT

  struct esp_ble_gatts_cb_param_t::gatts_cancel_open_evt_param cancel_open

    Gatt server callback param of ESP_GATTS_CANCEL_OPEN_EVT

  struct esp_ble_gatts_cb_param_t::gatts_close_evt_param close

    Gatt server callback param of ESP_GATTS_CLOSE_EVT

  struct esp_ble_gatts_cb_param_t::gatts_congest_evt_param congest

    Gatt server callback param of ESP_GATTS_CONGEST_EVT

  struct esp_ble_gatts_cb_param_t::gatts_rsp_evt_param rsp

    Gatt server callback param of ESP_GATTS_RESPONSE_EVT

  struct esp_ble_gatts_cb_param_t::gatts_add_attr_tab_evt_param add_attr_tab

    Gatt server callback param of ESP_GATTS_CREAT_ATTR_TAB_EVT

  struct esp_ble_gatts_cb_param_t::gatts_set_attr_val_evt_param set_attr_val

    Gatt server callback param of ESP_GATTS_SET_ATTR_VAL_EVT

  struct esp_ble_gatts_cb_param_t::gatts_send_service_change_evt_param service_change

    Gatt server callback param of ESP_GATTS_SEND_SERVICE_CHANGE_EVT

  struct gatts_add_attr_tab_evt_param
    #include <esp_gatts_api.h>

    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 handle to be added to the gatts database

    uint16_t *handles

      The number to the handles

  struct gatts_add_char_descr_evt_param
    #include <esp_gatts_api.h>

    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>

    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>

    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>

    ESP_GATTS_CANCEL_OPEN_EVT.

    Public Members

    esp_gatt_status_t status

      Operation status

  struct gatts_close_evt_param
    #include <esp_gatts_api.h>

    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>

    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 indication or notification value length, len is valid when send notification or indication failed

    uint8_t *value

      The indication or notification value , value is valid when send notification or indication failed

  struct gatts_congest_evt_param
    #include <esp_gatts_api.h>

    ESP_GATTS_LISTEN_EVT.

    ESP_GATTS_CONGEST_EVT

    Public Members

    uint16_t conn_id

      Connection id

    bool congested

      Congested or not

  struct gatts_connect_evt_param
    #include <esp_gatts_api.h>

    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 bluetooth device address

    esp_gatt_conn_params_t conn_params

      current Connection parameters

    esp_ble_addr_type_t ble_addr_type

      Remote BLE device address type

    uint16_t conn_handle

      HCI connection handle

  struct gatts_create_evt_param
    #include <esp_gatts_api.h>

    ESP_GATTS_UNREG_EVT.

    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, include service uuid and other information

  struct gatts_delete_evt_param
    #include <esp_gatts_api.h>

    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>

    ESP_GATTS_DISCONNECT_EVT.

    Public Members

    uint16_t conn_id

      Connection id

    esp_bd_addr_t remote_bda

      Remote bluetooth device address

    esp_gatt_conn_reason_t reason

      Indicate the reason of disconnection

  struct gatts_exec_write_evt_param
    #include <esp_gatts_api.h>

    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 which been written

    uint8_t exec_write_flag

      Execute write flag

  struct gatts_mtu_evt_param
    #include <esp_gatts_api.h>

    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>

    ESP_GATTS_OPEN_EVT.

    Public Members

    esp_gatt_status_t status

      Operation status

  struct gatts_read_evt_param
    #include <esp_gatts_api.h>

    ESP_GATTS_READ_EVT.

    Public Members

    uint16_t conn_id

      Connection id

    uint32_t trans_id

      Transfer id

    esp_bd_addr_t bda

      The bluetooth device address which been read

    uint16_t handle

      The attribute handle

    uint16_t offset

      Offset of the value, if the value is too long

    bool is_long

      The value is too long or not

    bool need_rsp

      The read operation need to do response

  struct gatts_reg_evt_param
    #include <esp_gatts_api.h>

    ESP_GATTS_REG_EVT.

    Public Members

    esp_gatt_status_t status

      Operation status

    uint16_t app_id

      Application id which input in register API

  struct gatts_rsp_evt_param
    #include <esp_gatts_api.h>

    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 send response

  struct gatts_send_service_change_evt_param
    #include <esp_gatts_api.h>

    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>

    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>

    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>

    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>

    ESP_GATTS_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 which been written

    uint16_t handle

      The attribute handle

    uint16_t offset

      Offset of the value, if the value is too long

    bool need_rsp

      The write operation need to do response

    bool is_prep

      This write operation is prepare write

    uint16_t len

      The write attribute value length

    uint8_t *value

      The write attribute value

### Macros

ESP_GATT_PREP_WRITE_CANCEL

  Prepare write flag to indicate cancel prepare write

ESP_GATT_PREP_WRITE_EXEC

  Prepare write flag to indicate execute prepare write

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

    : Event type

  Param gatts_if

    : GATT server access interface, normally different gatts_if correspond to different profile

  Param param

    : Point to callback parameter, currently is union type

### Enumerations

enum esp_gatts_cb_event_t

  GATT Server callback function events.

  Values:

  enumerator ESP_GATTS_REG_EVT

    When register application id, the event comes

  enumerator ESP_GATTS_READ_EVT

    When gatt client request read operation, the event comes

  enumerator ESP_GATTS_WRITE_EVT

    When gatt client request write operation, the event comes

  enumerator ESP_GATTS_EXEC_WRITE_EVT

    When gatt client request execute write, the event comes

  enumerator ESP_GATTS_MTU_EVT

    When set mtu complete, the event comes

  enumerator ESP_GATTS_CONF_EVT

    When receive confirm, the event comes

  enumerator ESP_GATTS_UNREG_EVT

    When unregister application id, the event comes

  enumerator ESP_GATTS_CREATE_EVT

    When create service complete, the event comes

  enumerator ESP_GATTS_ADD_INCL_SRVC_EVT

    When add included service complete, the event comes

  enumerator ESP_GATTS_ADD_CHAR_EVT

    When add characteristic complete, the event comes

  enumerator ESP_GATTS_ADD_CHAR_DESCR_EVT

    When add descriptor complete, the event comes

  enumerator ESP_GATTS_DELETE_EVT

    When delete service complete, the event comes

  enumerator ESP_GATTS_START_EVT

    When start service complete, the event comes

  enumerator ESP_GATTS_STOP_EVT

    When stop service complete, the event comes

  enumerator ESP_GATTS_CONNECT_EVT

    When gatt client connect, the event comes

  enumerator ESP_GATTS_DISCONNECT_EVT

    When gatt client disconnect, the event comes

  enumerator ESP_GATTS_OPEN_EVT

    When connect to peer, the event comes

  enumerator ESP_GATTS_CANCEL_OPEN_EVT

    When disconnect from peer, the event comes

  enumerator ESP_GATTS_CLOSE_EVT

    When gatt server close, the event comes

  enumerator ESP_GATTS_LISTEN_EVT

    When gatt listen to be connected the event comes

  enumerator ESP_GATTS_CONGEST_EVT

    When congest happen, the event comes

  enumerator ESP_GATTS_RESPONSE_EVT

    When gatt send response complete, the event comes

  enumerator ESP_GATTS_CREAT_ATTR_TAB_EVT

    When gatt create table complete, the event comes

  enumerator ESP_GATTS_SET_ATTR_VAL_EVT

    When gatt set attr value complete, the event comes

  enumerator ESP_GATTS_SEND_SERVICE_CHANGE_EVT

    When gatt send service change indication complete, the event comes

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。