diff --git a/include/bluetooth/gatt.h b/include/bluetooth/gatt.h index bee4eacfe17..58d30fde825 100644 --- a/include/bluetooth/gatt.h +++ b/include/bluetooth/gatt.h @@ -1,4 +1,6 @@ -/* gatt.h - Generic Attribute Profile handling */ +/*! @file + * @bried Generic Attribute Profile handling + */ /* * Copyright (c) 2015 Intel Corporation @@ -35,56 +37,141 @@ #include /* GATT attribute permission bitfield values */ +/*! @def BT_GATT_PERM_READ + * @brief Attribute read permission. + */ #define BT_GATT_PERM_READ 0x01 +/*! @def BT_GATT_PERM_WRITE + * @brief Attribute write permission. + */ #define BT_GATT_PERM_WRITE 0x02 +/*! @def BT_GATT_PERM_READ_ENCRYPT + * @brief Attribute read permission with encryption. + * + * If set, requires encryption for read access. + */ #define BT_GATT_PERM_READ_ENCRYPT 0x04 +/*! @def BT_GATT_PERM_WRITE_ENCRYPT + * @brief Attribute write permission with encryption. + * + * If set, requires encryption for write access. + */ #define BT_GATT_PERM_WRITE_ENCRYPT 0x08 +/*! @def BT_GATT_PERM_READ_AUTHEN + * @brief Attribute read permission with authentication. + * + * If set, requires encryption using authenticated link-key for read access. + */ #define BT_GATT_PERM_READ_AUTHEN 0x10 +/*! @def BT_GATT_PERM_WRITE_AUTHEN + * @brief Attribute write permission with authentication. + * + * If set, requires encryption using authenticated link-key for write access. + */ #define BT_GATT_PERM_WRITE_AUTHEN 0x20 +/*! @def BT_GATT_PERM_AUTHOR + * @brief Attribute authorization permission. + */ #define BT_GATT_PERM_AUTHOR 0x40 -/* GATT Attribute structure */ +/*! @brief GATT Attribute structure. */ struct bt_gatt_attr { + /*! Attribute handle */ uint16_t handle; + /*! Attribute UUID */ const struct bt_uuid *uuid; + /*! Attribute permissions */ uint8_t perm; + /*! Attribute read callback */ int (*read)(const bt_addr_le_t *peer, const struct bt_gatt_attr *attr, void *buf, uint8_t len, uint16_t offset); + /*! Attribute write callback */ int (*write)(const bt_addr_le_t *peer, const struct bt_gatt_attr *attr, const void *buf, uint8_t len, uint16_t offset); + /*! Attribute user data */ void *user_data; }; -/* Service Attribute Value */ +/*! @brief Service Attribute Value. */ struct bt_gatt_service { + /*! Service UUID. */ const struct bt_uuid *uuid; }; -/* Include Attribute Value */ +/*! @brief Include Attribute Value. */ struct bt_gatt_include { + /*! Service start handle. */ uint16_t start_handle; + /*! Service end handle. */ uint16_t end_handle; + /*! Service UUID. */ const struct bt_uuid *uuid; }; /* Characteristic Properties Bitfield values */ +/*! @def BT_GATT_CHRC_BROADCAST + * @brief Characteristic broadcast property. + * + * If set, permits broadcasts of the Characteristic Value using Server + * Characteristic Configuration Descriptor. + */ #define BT_GATT_CHRC_BROADCAST 0x01 +/*! @def BT_GATT_CHRC_READ + * @brief Characteristic read property. + * + * If set, permits reads of the Characteristic Value. + */ #define BT_GATT_CHRC_READ 0x02 +/*! @def BT_GATT_CHRC_WRITE_WITHOUT_RESP + * @brief Characteristic write without response property. + * + * If set, permits write of the Characteristic Value without response. + */ #define BT_GATT_CHRC_WRITE_WITHOUT_RESP 0x04 +/*! @def BT_GATT_CHRC_WRITE + * @brief Characteristic write with response property. + * + * If set, permits write of the Characteristic Value with response. + */ #define BT_GATT_CHRC_WRITE 0x08 +/*! @def BT_GATT_CHRC_NOTIFY + * @brief Characteristic notify property. + * + * If set, permits notifications of a Characteristic Value without + * acknowledgement. + */ #define BT_GATT_CHRC_NOTIFY 0x10 +/*! @def BT_GATT_CHRC_INDICATE + * @brief Characteristic indicate property. + * + * If set, permits indications of a Characteristic Value with acknowledgement. + */ #define BT_GATT_CHRC_INDICATE 0x20 +/*! @def BT_GATT_CHRC_AUTH + * @brief Characteristic Authenticated Signed Writes property. + * + * If set, permits signed writes to the Characteristic Value + */ #define BT_GATT_CHRC_AUTH 0x40 +/*! @def BT_GATT_CHRC_EXT_PROP + * @brief Characteristic Extended Properties property. + * + * If set, additional characteristic properties are defined in the + * Characteristic Extended Properties Descriptor. + */ #define BT_GATT_CHRC_EXT_PROP 0x80 -/* Characteristic Attribute Value */ +/*! @brief Characteristic Attribute Value. */ struct bt_gatt_chrc { + /*! Characteristic properties. */ uint8_t properties; + /*! Characteristic value handle. */ uint16_t value_handle; + /*! Characteristic UUID. */ const struct bt_uuid *uuid; }; @@ -92,35 +179,48 @@ struct bt_gatt_chrc { #define BT_GATT_CEP_RELIABLE_WRITE 0x01 #define BT_GATT_CEP_WRITABLE_AUX 0x02 -/* Characteristic Extended Properties Attribute Value */ +/*! @brief Characteristic Extended Properties Attribute Value. */ struct bt_gatt_cep { + /*! Characteristic Extended properties. */ uint8_t properties; }; -/* Characteristic User Description Attribute Value */ +/* @brief Characteristic User Description Attribute Value. */ struct bt_gatt_cud { + /*! Characteristic User Description string. */ char *string; }; -/* Client Characteristic Configuration.user_datas */ +/* Client Characteristic Configuration Values*/ +/* @def BT_GATT_CCC_NOTIFY + * @brief Client Characteristic Configuration Notification. + * + * If set, changes to Characteristic Value shall be notified. + */ #define BT_GATT_CCC_NOTIFY 0x0001 +/* @def BT_GATT_CCC_INDICATE + * @brief Client Characteristic Configuration Indication. + * + * If set, changes to Characteristic Value shall be indicated. + */ #define BT_GATT_CCC_INDICATE 0x0002 /* Client Characteristic Configuration Attribute Value */ struct bt_gatt_ccc { + /*! Client Characteristic Configuration flags */ uint16_t flags; }; /* Server API */ -/** @brief Register attribute database +/*! @brief Register attribute database. * * Register GATT attribute database table. Applications can make use of * macros such as BT_GATT_PRIMARY_SERVICE, BT_GATT_CHARACTERISTIC, * BT_GATT_DESCRIPTOR, etc. * - * @param attrs dabase table containing the available attributes - * @param count size of database table + * @param attrs dabase table containing the available attributes. + * @param count size of database table. */ void bt_gatt_register(const struct bt_gatt_attr *attrs, size_t count); @@ -129,10 +229,10 @@ enum { BT_GATT_ITER_CONTINUE, }; -/** @brief Attribute iterator callback +/*! @brief Attribute iterator callback. * - * @param attr attribute found - * @param user_data data given + * @param attr attribute found. + * @param user_data data given. * * @return BT_GATT_ITER_CONTINUE if should continue to the next attribute * or BT_GATT_ITER_STOP to stop. @@ -140,29 +240,29 @@ enum { typedef uint8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr, void *user_data); -/** @brief Attribute iterator +/*! @brief Attribute iterator. * * Iterate attributes in the given range. * - * @param start_handle uint16_t start handle - * @param end_handle uint16_t end handle - * @param func bt_gatt_attr_func_t callback function - * @param user_data void * data to pass to the callback + * @param start_handle start handle. + * @param end_handle end handle. + * @param func callback function. + * @param user_data data to pass to the callback. */ void bt_gatt_foreach_attr(uint16_t start_handle, uint16_t end_handle, bt_gatt_attr_func_t func, void *user_data); -/** @brief Generic Read Attribute value helper +/*! @brief Generic Read Attribute value helper. * * Read attribute value storing the result into buffer. * - * @param peer remote address - * @param attr attribute to read - * @param buf buffer to store the value - * @param buf_len buffer length - * @param offset start offset - * @param value attribute value - * @param value_len length of the attribute value + * @param peer remote address. + * @param attr attribute to read. + * @param buf buffer to store the value. + * @param buf_len buffer length. + * @param offset start offset. + * @param value attribute value. + * @param value_len length of the attribute value. * * @return int number of bytes read in case of success or negative values in * case of error. @@ -171,17 +271,17 @@ int bt_gatt_attr_read(const bt_addr_le_t *peer, const struct bt_gatt_attr *attr, void *buf, uint8_t buf_len, uint16_t offset, const void *value, uint8_t value_len); -/** @brief Read Service Attribute helper +/*! @brief Read Service Attribute helper. * * Read service attribute value storing the result into buffer after * enconding it. * NOTE: Only use this with attributes which user_data is a bt_uuid. * - * @param peer remote address - * @param attr attribute to read - * @param buf buffer to store the value read - * @param len buffer length - * @param offset start offset + * @param peer remote address. + * @param attr attribute to read. + * @param buf buffer to store the value read. + * @param len buffer length. + * @param offset start offset. * * @return int number of bytes read in case of success or negative values in * case of error. @@ -190,13 +290,14 @@ int bt_gatt_attr_read_service(const bt_addr_le_t *peer, const struct bt_gatt_attr *attr, void *buf, uint8_t len, uint16_t offset); -/** @brief Generic Service Declaration Macro +/*! @def BT_GATT_SERVICE + * @brief Generic Service Declaration Macro. * * Helper macro to declare a service attribute. * - * @param _handle service attribute handle - * @param _uuid service attribute type - * @param _data service attribute value + * @param _handle service attribute handle. + * @param _uuid service attribute type. + * @param _data service attribute value. */ #define BT_GATT_SERVICE(_handle, _uuid, _service) \ { \ @@ -207,12 +308,13 @@ int bt_gatt_attr_read_service(const bt_addr_le_t *peer, .user_data = _service, \ } -/** @brief Primary Service Declaration Macro +/*! @def BT_GATT_PRIMARY_SERVICE + * @brief Primary Service Declaration Macro. * * Helper macro to declare a primary service attribute. * - * @param _handle service attribute handle - * @param _service service attribute value + * @param _handle service attribute handle. + * @param _service service attribute value. */ #define BT_GATT_PRIMARY_SERVICE(_handle, _service) \ { \ @@ -224,12 +326,13 @@ int bt_gatt_attr_read_service(const bt_addr_le_t *peer, .user_data = _service, \ } -/** @brief Secondary Service Declaration Macro +/*! @def BT_GATT_SECONDARY_SERVICE + * @brief Secondary Service Declaration Macro. * * Helper macro to declare a secondary service attribute. * - * @param _handle service attribute handle - * @param _service service attribute value + * @param _handle service attribute handle. + * @param _service service attribute value. */ #define BT_GATT_SECONDARY_SERVICE(_handle, _service) \ { \ @@ -241,17 +344,17 @@ int bt_gatt_attr_read_service(const bt_addr_le_t *peer, .user_data = _service, \ } -/** @brief Read Include Attribute helper +/*! @brief Read Include Attribute helper. * * Read include service attribute value storing the result into buffer after * enconding it. * NOTE: Only use this with attributes which user_data is a bt_gatt_include. * - * @param peer remote address - * @param attr attribute to read - * @param buf buffer to store the value read - * @param len buffer length - * @param offset start offset + * @param peer remote address. + * @param attr attribute to read. + * @param buf buffer to store the value read. + * @param len buffer length. + * @param offset start offset. * * @return int number of bytes read in case of success or negative values in * case of error. @@ -260,7 +363,14 @@ int bt_gatt_attr_read_included(const bt_addr_le_t *peer, const struct bt_gatt_attr *attr, void *buf, uint8_t len, uint16_t offset); -/* Include Service Declaration */ +/*! @def BT_GATT_INCLUDE_SERVICE + * @brief Include Service Declaration Macro. + * + * Helper macro to declare a include service attribute. + * + * @param _handle service attribute handle. + * @param _service service attribute value. + */ #define BT_GATT_INCLUDE_SERVICE(_handle, _service) \ { \ .handle = _handle, \ @@ -271,17 +381,17 @@ int bt_gatt_attr_read_included(const bt_addr_le_t *peer, .user_data = _service, \ } -/** @brief Read Characteristic Attribute helper +/*! @brief Read Characteristic Attribute helper. * * Read characteristic attribute value storing the result into buffer after * enconding it. * NOTE: Only use this with attributes which user_data is a bt_gatt_chrc. * - * @param peer remote address - * @param attr attribute to read - * @param buf buffer to store the value read - * @param len buffer length - * @param offset start offset + * @param peer remote address. + * @param attr attribute to read. + * @param buf buffer to store the value read. + * @param len buffer length. + * @param offset start offset. * * @return number of bytes read in case of success or negative values in * case of error. @@ -290,12 +400,13 @@ int bt_gatt_attr_read_chrc(const bt_addr_le_t *peer, const struct bt_gatt_attr *attr, void *buf, uint8_t len, uint16_t offset); -/** @brief Characteristic Declaration Macro +/*! @def BT_GATT_CHARACTERISTIC + * @brief Characteristic Declaration Macro. * * Helper macro to declare a characteristic attribute. * - * @param _handle characteristic attribute handle - * @param _value characteristic attribute value + * @param _handle characteristic attribute handle. + * @param _value characteristic attribute value. */ #define BT_GATT_CHARACTERISTIC(_handle, _value) \ { \ @@ -307,12 +418,17 @@ int bt_gatt_attr_read_chrc(const bt_addr_le_t *peer, .user_data = _value, \ } +/*! @brief GATT CCC configuration entry. */ struct bt_gatt_ccc_cfg { + /*! Config peer address. */ bt_addr_le_t peer; + /*! Config peer value. */ uint16_t value; + /*! Config valid flag. */ uint8_t valid; }; +/* Internal representation of CCC value */ struct _bt_gatt_ccc { struct bt_gatt_ccc_cfg *cfg; size_t cfg_len; @@ -321,17 +437,17 @@ struct _bt_gatt_ccc { void (*cfg_changed)(uint16_t value); }; -/** @brief Read Client Characteristic Configuration Attribute helper +/*! @brief Read Client Characteristic Configuration Attribute helper. * * Read CCC attribute value storing the result into buffer after * enconding it. * NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc. * - * @param peer remote address - * @param attr attribute to read - * @param buf buffer to store the value read - * @param len buffer length - * @param offset start offset + * @param peer remote address. + * @param attr attribute to read. + * @param buf buffer to store the value read. + * @param len buffer length. + * @param offset start offset. * * @return number of bytes read in case of success or negative values in * case of error. @@ -340,16 +456,16 @@ int bt_gatt_attr_read_ccc(const bt_addr_le_t *peer, const struct bt_gatt_attr *attr, void *buf, uint8_t len, uint16_t offset); -/** @brief Write Client Characteristic Configuration Attribute helper +/*! @brief Write Client Characteristic Configuration Attribute helper. * * Write value in the buffer into CCC attribute. * NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc. * - * @param peer remote address - * @param attr attribute to read - * @param buf buffer to store the value read - * @param len buffer length - * @param offset start offset + * @param peer remote address. + * @param attr attribute to read. + * @param buf buffer to store the value read. + * @param len buffer length. + * @param offset start offset. * * @return number of bytes written in case of success or negative values in * case of error. @@ -358,14 +474,15 @@ int bt_gatt_attr_write_ccc(const bt_addr_le_t *peer, const struct bt_gatt_attr *attr, const void *buf, uint8_t len, uint16_t offset); -/** @brief Client Characteristic Configuration Declaration Macro +/*! @def BT_GATT_CCC + * @brief Client Characteristic Configuration Declaration Macro. * * Helper macro to declare a CCC attribute. * - * @param _handle descriptor attribute handle - * @param _value_handle characteristic attribute value handle - * @param _cfg initial configuration - * @param _cfg_changed configuration changed callback + * @param _handle descriptor attribute handle. + * @param _value_handle characteristic attribute value handle. + * @param _cfg initial configuration. + * @param _cfg_changed configuration changed callback. */ #define BT_GATT_CCC(_handle, _value_handle, _cfg, _cfg_changed) \ { \ @@ -381,12 +498,17 @@ int bt_gatt_attr_write_ccc(const bt_addr_le_t *peer, .cfg_changed = _cfg_changed, }),\ } -/** @brief Descriptor Declaration Macro +/*! @def BT_GATT_DESCRIPTOR + * @brief Descriptor Declaration Macro. * * Helper macro to declare a descriptor attribute. * - * @param _handle descriptor attribute handle - * @param _value descriptor attribute value + * @param _handle descriptor attribute handle. + * @param _value descriptor attribute value. + * @param _perm descriptor attribute access permissions. + * @param _read descriptor attribute read callback. + * @param _write descriptor attribute write callback. + * @param _value descriptor attribute value. */ #define BT_GATT_DESCRIPTOR(_handle, _uuid, _perm, _read, _write, _value) \ { \ @@ -398,15 +520,15 @@ int bt_gatt_attr_write_ccc(const bt_addr_le_t *peer, .user_data = _value, \ } -/** @brief Notify attribute value change +/*! @brief Notify attribute value change. * * Send notification of attribute value change. * Note: This function should only be called if CCC is declared with * BT_GATT_CCC otherwise it cannot find a valid peer configuration. * - * @param handle attribute handle - * @param value attribute value - * @param len attribute value length + * @param handle attribute handle. + * @param value attribute value. + * @param len attribute value length. */ void bt_gatt_notify(uint16_t handle, const void *data, size_t len);