xushaoxiang
321 lines
16 KiB
C
321 lines
16 KiB
C
/**
|
|
****************************************************************************************
|
|
* @file xc_gatt_client_api.h
|
|
* @brief GATT client API.
|
|
* Copyright (c) 2022 - 2025, XinChip
|
|
* All rights reserved.
|
|
****************************************************************************************
|
|
*/
|
|
|
|
#ifndef __XC_GATT_CLIENT_API_H__
|
|
#define __XC_GATT_CLIENT_API_H__
|
|
|
|
#include "gatt_db.h" // GATT Database access
|
|
#include "gatt.h"
|
|
#include "co_buf.h"
|
|
#include "rwble_hl_error.h"
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used to register a GATT user. This must be done prior to any GATT
|
|
* procedure execution.
|
|
*
|
|
* A GATT client user can initiate any client procedure, and shall be able to
|
|
* handle all client initiated message events
|
|
*
|
|
* Same module can register multiple GATT users.
|
|
*
|
|
* @param[in] pref_mtu Preferred MTU for attribute exchange.
|
|
* @param[in] prio_level User attribute priority level
|
|
* @param[in] p_cb Pointer to set of callback functions to be used for communication
|
|
* with the GATT server user
|
|
* @param[out] p_user_lid Pointer where GATT user local identifier will be set
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_user_cli_register(uint16_t pref_mtu, uint8_t prio_level, const gatt_cli_cb_t* p_cb, uint8_t* p_user_lid);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used to unregister a GATT user (client or server).
|
|
*
|
|
* @param[in] user_lid GATT User Local identifier
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_user_unregister(uint8_t user_lid);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used by a GATT client user to discover primary or secondary services,
|
|
* exposed by peer device in its attribute database.
|
|
*
|
|
* All services can be discovered or filtering services having a specific UUID.
|
|
* The discovery is done between start handle and end handle range.
|
|
* For a complete discovery start handle must be set to 0x0001 and end handle to
|
|
* 0xFFFF.
|
|
*
|
|
* Wait for @see cb_discover_cmp execution before starting a new procedure
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] dummy Dummy parameter whose meaning is upper layer dependent and
|
|
* which is returned in command complete.
|
|
* @param[in] disc_type GATT Service discovery type (@see enum gatt_svc_discovery_type)
|
|
* @param[in] full Perform discovery of all information present in the service
|
|
* (True: enable, False: disable)
|
|
* @param[in] start_hdl Search start handle
|
|
* @param[in] end_hdl Search end handle
|
|
* @param[in] uuid_type UUID Type (@see enum gatt_uuid_type)
|
|
* @param[in] p_uuid Pointer to searched Service UUID (meaningful only for
|
|
* discovery by UUID)
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
* Consider status only if an error occurs; else wait for execution completion
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_discover_svc(uint8_t conidx, uint8_t user_lid, uint16_t dummy, uint8_t disc_type, bool full,
|
|
uint16_t start_hdl, uint16_t end_hdl, uint8_t uuid_type, const uint8_t* p_uuid);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used by a GATT client user to discover included services, exposed
|
|
* by peer device in its attribute database.
|
|
*
|
|
* The discovery is done between start handle and end handle range.
|
|
* For a complete discovery start handle must be set to 0x0001 and end handle to
|
|
* 0xFFFF.
|
|
*
|
|
* Wait for @see cb_discover_cmp execution before starting a new procedure
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] dummy Dummy parameter whose meaning is upper layer dependent and
|
|
* which is returned in command complete.
|
|
* @param[in] start_hdl Search start handle
|
|
* @param[in] end_hdl Search end handle
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
* Consider status only if an error occurs; else wait for execution completion
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_discover_inc_svc(uint8_t conidx, uint8_t user_lid, uint16_t dummy,
|
|
uint16_t start_hdl, uint16_t end_hdl);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used by a GATT client user to discover all or according to a specific
|
|
* UUID characteristics exposed by peer device in its attribute database.
|
|
*
|
|
* The discovery is done between start handle and end handle range.
|
|
* For a complete discovery start handle must be set to 0x0001 and end handle to
|
|
* 0xFFFF.
|
|
*
|
|
* Wait for @see cb_discover_cmp execution before starting a new procedure
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] dummy Dummy parameter whose meaning is upper layer dependent and
|
|
* which is returned in command complete.
|
|
* @param[in] disc_type GATT characteristic discovery type (@see enum gatt_char_discovery_type)
|
|
* @param[in] start_hdl Search start handle
|
|
* @param[in] end_hdl Search end handle
|
|
* @param[in] uuid_type UUID Type (@see enum gatt_uuid_type)
|
|
* @param[in] p_uuid Pointer to searched Attribute Value UUID (meaningful only
|
|
* for discovery by UUID)
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
* Consider status only if an error occurs; else wait for execution completion
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_discover_char(uint8_t conidx, uint8_t user_lid, uint16_t dummy, uint8_t disc_type,
|
|
uint16_t start_hdl, uint16_t end_hdl, uint8_t uuid_type, const uint8_t* p_uuid);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used by a GATT client user to discover characteristic descriptor
|
|
* exposed by peer device in its attribute database.
|
|
*
|
|
* The discovery is done between start handle and end handle range.
|
|
* For a complete discovery start handle must be set to 0x0001 and end handle to
|
|
* 0xFFFF.
|
|
*
|
|
* Wait for @see cb_discover_cmp execution before starting a new procedure
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] dummy Dummy parameter whose meaning is upper layer dependent and
|
|
* which is returned in command complete.
|
|
* @param[in] start_hdl Search start handle
|
|
* @param[in] end_hdl Search end handle
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
* Consider status only if an error occurs; else wait for execution completion
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_discover_desc(uint8_t conidx, uint8_t user_lid, uint16_t dummy, uint16_t start_hdl, uint16_t end_hdl);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used by a GATT client user to cancel an on-going discovery procedure.
|
|
* The dummy parameter in the request must be equals to dummy parameter used for
|
|
* service discovery command.
|
|
*
|
|
* The discovery is aborted as soon as on-going discovery attribute transaction
|
|
* is over.
|
|
*
|
|
* Wait for @see cb_discover_cmp execution before starting a new procedure
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] dummy Dummy parameter whose meaning is upper layer dependent and
|
|
* which is returned in command complete.
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
* Consider status only if an error occurs; else wait for execution completion
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_discover_cancel(uint8_t conidx, uint8_t user_lid, uint16_t dummy);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used by a GATT client user to read value of an attribute (identified
|
|
* by its handle) present in peer database.
|
|
*
|
|
* Wait for @see cb_read_cmp execution before starting a new procedure
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] dummy Dummy parameter whose meaning is upper layer dependent and
|
|
* which is returned in command complete.
|
|
* @param[in] hdl Attribute handle
|
|
* @param[in] offset Value offset
|
|
* @param[in] length Value length to read (0 = read all)
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
* Consider status only if an error occurs; else wait for execution completion
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_read(uint8_t conidx, uint8_t user_lid, uint16_t dummy,
|
|
uint16_t hdl, uint16_t offset, uint16_t length);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used by a GATT client user to read value of an attribute with a given
|
|
* UUID in peer database.
|
|
*
|
|
* Wait for @see cb_read_cmp execution before starting a new procedure
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] dummy Dummy parameter whose meaning is upper layer dependent and
|
|
* which is returned in command complete.
|
|
* @param[in] start_hdl Search start handle
|
|
* @param[in] end_hdl Search end handle
|
|
* @param[in] uuid_type UUID Type (@see enum gatt_uuid_type)
|
|
* @param[in] p_uuid Pointer to searched attribute UUID (LSB First)
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
* Consider status only if an error occurs; else wait for execution completion
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_read_by_uuid(uint8_t conidx, uint8_t user_lid, uint16_t dummy,
|
|
uint16_t start_hdl, uint16_t end_hdl, uint8_t uuid_type, const uint8_t* p_uuid);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used by a GATT client user to request to write value of an attribute
|
|
* in peer database.
|
|
*
|
|
* Since user is not aware of MTU size of the bearer used for attribute
|
|
* transmission it cannot be considered reliable.
|
|
*
|
|
* For a GATT_WRITE_NO_RESP if attribute bearer max transmission size isn't sufficient,
|
|
* a GATT_WRITE (with response) procedure will be used.
|
|
*
|
|
* For a GATT_WRITE_SIGNED, if attribute bearer max transmission size isn't sufficient,
|
|
* the procedure is aborted with L2CAP_ERR_INVALID_MTU error code.
|
|
*
|
|
* Wait for @see cb_write_cmp execution before starting a new procedure
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] dummy Dummy parameter whose meaning is upper layer dependent and
|
|
* which is returned in command complete.
|
|
* @param[in] write_type GATT write type (@see enum gatt_write_type)
|
|
* @param[in] hdl Attribute handle
|
|
* @param[in] length Value length
|
|
* @param[in] p_data Pointer to data value
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
* Consider status only if an error occurs; else wait for execution completion
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_write(uint8_t conidx, uint8_t user_lid, uint16_t dummy, uint8_t write_type,
|
|
uint16_t hdl, uint16_t length, const uint8_t* p_data);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used by a GATT client user to register for reception of events
|
|
* (notification / indication) for a given handle range.
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] start_hdl Attribute start handle
|
|
* @param[in] end_hdl Attribute end handle
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_event_register(uint8_t conidx, uint8_t user_lid, uint16_t start_hdl, uint16_t end_hdl);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Command used by a GATT client user to stop reception of events (notification /
|
|
* indication) onto a specific handle range.
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] start_hdl Attribute start handle
|
|
* @param[in] end_hdl Attribute end handle
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_event_unregister(uint8_t conidx, uint8_t user_lid, uint16_t start_hdl, uint16_t end_hdl);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Request a MTU exchange on legacy attribute bearer.
|
|
* There is no callback executed when the procedure is over.
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_mtu_exch(uint8_t conidx, uint8_t user_lid);
|
|
|
|
/**
|
|
****************************************************************************************
|
|
* @brief Upper layer provide status of attribute event handled by GATT client user.
|
|
* confirmation of indicate by GATT client.
|
|
*
|
|
* @param[in] conidx Connection index
|
|
* @param[in] user_lid GATT User Local identifier
|
|
* @param[in] token Procedure token provided in corresponding callback
|
|
*
|
|
* @return Status of the function execution (@see enum hl_err)
|
|
****************************************************************************************
|
|
*/
|
|
uint16_t xc_ble_gatt_cli_indicate_cfm(uint8_t conidx, uint8_t user_lid, uint16_t token);
|
|
|
|
|
|
|
|
#endif // __XC_GATT_CLIENT_API_H__
|
|
|
|
|
|
|