MT2523 API Reference  LinkIt SDK v4
GATT Client

This section introduces the GATT Client driver APIs including terms and acronyms, supported features, details on how to use this driver, GATT Client function groups, enums, GATT Client request and response structures and functions, API prototypes to discover primary services, included services, characteristics and descriptors and to read or write characteristics or descriptors. More...

Overview

This section introduces the GATT Client driver APIs including terms and acronyms, supported features, details on how to use this driver, GATT Client function groups, enums, GATT Client request and response structures and functions, API prototypes to discover primary services, included services, characteristics and descriptors and to read or write characteristics or descriptors.

Terms and Acronyms

Terms Details
GATTC GATT Client is the device that initiates commands and requests to the server.
MTU Maximum Transmission Unit, specifies the maximum size of a packet to send.
ATT Attribute Protocol. For more information, please refer to Wikipedia.

How to use this module

Each GATTC operation starts with sending a request to the server, then processing the corresponding response from the server in the callback function bt_app_event_callback().

Functions

bt_status_t bt_gattc_exchange_mtu (bt_handle_t connection_handle, const bt_gattc_exchange_mtu_req_t *req)
 This function sends an exchange MTU request to the GATT Server. More...
 
uint32_t bt_gattc_get_mtu (bt_handle_t connection_handle)
 This function gets the MTU of this connection. More...
 
bt_status_t bt_gattc_discover_primary_service (bt_handle_t connection_handle, const bt_gattc_discover_primary_service_req_t *req)
 This function discovers the primary service of the GATT Server. More...
 
bt_status_t bt_gattc_discover_primary_service_by_uuid (bt_handle_t connection_handle, const bt_gattc_discover_primary_service_by_uuid_req_t *req)
 This function discovers the primary service of the GATT Server by the UUID. More...
 
bt_status_t bt_gattc_find_included_services (bt_handle_t connection_handle, const bt_gattc_find_included_services_req_t *req)
 This function finds the included service on the GATT Server. More...
 
bt_status_t bt_gattc_discover_charc (bt_handle_t connection_handle, const bt_gattc_discover_charc_req_t *req)
 This function discovers all characteristics or a specific characteristic by UUID of the GATT Server. More...
 
bt_status_t bt_gattc_discover_charc_descriptor (bt_handle_t connection_handle, const bt_gattc_discover_charc_descriptor_req_t *req)
 This function discovers characteristic descriptors. More...
 
bt_status_t bt_gattc_read_charc (bt_handle_t connection_handle, const bt_gattc_read_charc_req_t *req)
 This function reads the value or the descriptor of a characteristic of the GATT Server. More...
 
bt_status_t bt_gattc_read_long_charc (bt_handle_t connection_handle, const bt_gattc_read_long_charc_value_req_t *req)
 This function reads a long characteristic value or a descriptor of the GATT Server. More...
 
bt_status_t bt_gattc_read_using_charc_uuid (bt_handle_t connection_handle, const bt_gattc_read_using_charc_uuid_req_t *req)
 This function reads the characteristics of the GATT Server by UUID. More...
 
bt_status_t bt_gattc_read_multi_charc_values (bt_handle_t connection_handle, const bt_gattc_read_multi_charc_values_req_t *req)
 This function reads multiple characteristic values from the GATT Server. More...
 
bt_status_t bt_gattc_write_without_rsp (bt_handle_t connection_handle, uint8_t is_signed, const bt_gattc_write_without_rsp_req_t *req)
 This function writes characteristic values without a response from the GATT Server. More...
 
bt_status_t bt_gattc_write_charc (bt_handle_t connection_handle, const bt_gattc_write_charc_req_t *req)
 This function writes values or descriptors of a characteristic on the GATT Server. More...
 
bt_status_t bt_gattc_prepare_write_charc (bt_handle_t connection_handle, uint8_t is_reliable, uint16_t offset, const bt_gattc_prepare_write_charc_req_t *req)
 This function prepares to write characteristic values to the GATT Server. More...
 
bt_status_t bt_gattc_send_execute_write_req (bt_handle_t connection_handle, const bt_gattc_execute_write_req_t *req)
 This function sends an execute write request to the GATT Server. More...
 

Modules

 Define
 This section defines macros for the GATT Client.
 
 Struct
 Basic data structures for the GATT Client.
 

Function Documentation

bt_status_t bt_gattc_discover_charc ( bt_handle_t  connection_handle,
const bt_gattc_discover_charc_req_t req 
)

This function discovers all characteristics or a specific characteristic by UUID of the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the discover characteristic request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_discover_charc_descriptor ( bt_handle_t  connection_handle,
const bt_gattc_discover_charc_descriptor_req_t req 
)

This function discovers characteristic descriptors.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the discover characteristic descriptors request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_discover_primary_service ( bt_handle_t  connection_handle,
const bt_gattc_discover_primary_service_req_t req 
)

This function discovers the primary service of the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]reqis the pointer to the GATT discover primary service request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_discover_primary_service_by_uuid ( bt_handle_t  connection_handle,
const bt_gattc_discover_primary_service_by_uuid_req_t req 
)

This function discovers the primary service of the GATT Server by the UUID.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the GATT discover primary service by UUID request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_exchange_mtu ( bt_handle_t  connection_handle,
const bt_gattc_exchange_mtu_req_t req 
)

This function sends an exchange MTU request to the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the GATT exchange MTU request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_find_included_services ( bt_handle_t  connection_handle,
const bt_gattc_find_included_services_req_t req 
)

This function finds the included service on the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the GATT find included service request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
uint32_t bt_gattc_get_mtu ( bt_handle_t  connection_handle)

This function gets the MTU of this connection.

Parameters
[in]connection_handleThe connection handle.
Returns
MTU of this connection if connection exists, otherwise return the default MTU.
bt_status_t bt_gattc_prepare_write_charc ( bt_handle_t  connection_handle,
uint8_t  is_reliable,
uint16_t  offset,
const bt_gattc_prepare_write_charc_req_t req 
)

This function prepares to write characteristic values to the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]is_reliableis a flag to decide whether it is a reliable prepare write request.
[in]offsetis the offset to write.
[in]reqis a pointer to the prepare write request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_read_charc ( bt_handle_t  connection_handle,
const bt_gattc_read_charc_req_t req 
)

This function reads the value or the descriptor of a characteristic of the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the read characteristic request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_read_long_charc ( bt_handle_t  connection_handle,
const bt_gattc_read_long_charc_value_req_t req 
)

This function reads a long characteristic value or a descriptor of the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the read long characteristic request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_read_multi_charc_values ( bt_handle_t  connection_handle,
const bt_gattc_read_multi_charc_values_req_t req 
)

This function reads multiple characteristic values from the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the read multiple characteristic values request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_read_using_charc_uuid ( bt_handle_t  connection_handle,
const bt_gattc_read_using_charc_uuid_req_t req 
)

This function reads the characteristics of the GATT Server by UUID.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the read using characteristic UUID request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_send_execute_write_req ( bt_handle_t  connection_handle,
const bt_gattc_execute_write_req_t req 
)

This function sends an execute write request to the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the execute write request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_write_charc ( bt_handle_t  connection_handle,
const bt_gattc_write_charc_req_t req 
)

This function writes values or descriptors of a characteristic on the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]reqis a pointer to the write characteristic request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.
bt_status_t bt_gattc_write_without_rsp ( bt_handle_t  connection_handle,
uint8_t  is_signed,
const bt_gattc_write_without_rsp_req_t req 
)

This function writes characteristic values without a response from the GATT Server.

Parameters
[in]connection_handleis the connection handle.
[in]is_signedis a flag to decide whether to use signed write. True , use signed write, False , use unsigned write.
[in]reqis a pointer to the write without response request structure.
Returns
BT_STATUS_SUCCESS, the operation completed successfully. BT_STATUS_FAIL, the operation has failed. BT_STATUS_OUT_OF_MEMORY, out of memory. BT_STATUS_CONNECTION_IN_USE, an ongoing request.