michaelh/zephyr
1
0
Fork 0
Code Releases Activity

Bluetooth: Update documentation of GATT API

Browse source 
This makes use of new guidelines to document the GATT API.

Change-Id: I5544f449e11dd72c68b0efb15bd06db44ec30279
Signed-off-by: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>
This commit is contained in:
Luiz Augusto von Dentz 2015-06-10 14:51:21 +03:00 • committed by Anas Nashif
commit 537e65b05b
1 changed files with 205 additions and 83 deletions
Download patch file Download diff file Expand all files Collapse all files

288
include/bluetooth/gatt.h
View file

@ -1,4 +1,6 @@
/* gatt.h - Generic Attribute Profile handling */ /*! @file
* @bried Generic Attribute Profile handling
*/
/* /*
* Copyright (c) 2015 Intel Corporation * Copyright (c) 2015 Intel Corporation
@ -35,56 +37,141 @@
#include <misc/util.h> #include <misc/util.h>
/* GATT attribute permission bitfield values */ /* GATT attribute permission bitfield values */
/*! @def BT_GATT_PERM_READ
* @brief Attribute read permission.
*/
#define BT_GATT_PERM_READ 0x01 #define BT_GATT_PERM_READ 0x01
/*! @def BT_GATT_PERM_WRITE
* @brief Attribute write permission.
*/
#define BT_GATT_PERM_WRITE 0x02 #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 #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 #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 #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 #define BT_GATT_PERM_WRITE_AUTHEN 0x20
/*! @def BT_GATT_PERM_AUTHOR
* @brief Attribute authorization permission.
*/
#define BT_GATT_PERM_AUTHOR 0x40 #define BT_GATT_PERM_AUTHOR 0x40
/* GATT Attribute structure */ /*! @brief GATT Attribute structure. */
struct bt_gatt_attr { struct bt_gatt_attr {
/*! Attribute handle */
uint16_t handle; uint16_t handle;
/*! Attribute UUID */
const struct bt_uuid *uuid; const struct bt_uuid *uuid;
/*! Attribute permissions */
uint8_t perm; uint8_t perm;
/*! Attribute read callback */
int (*read)(const bt_addr_le_t *peer, int (*read)(const bt_addr_le_t *peer,
const struct bt_gatt_attr *attr, const struct bt_gatt_attr *attr,
void *buf, uint8_t len, void *buf, uint8_t len,
uint16_t offset); uint16_t offset);
/*! Attribute write callback */
int (*write)(const bt_addr_le_t *peer, int (*write)(const bt_addr_le_t *peer,
const struct bt_gatt_attr *attr, const struct bt_gatt_attr *attr,
const void *buf, uint8_t len, const void *buf, uint8_t len,
uint16_t offset); uint16_t offset);
/*! Attribute user data */
void *user_data; void *user_data;
}; };
/* Service Attribute Value */ /*! @brief Service Attribute Value. */
struct bt_gatt_service { struct bt_gatt_service {
/*! Service UUID. */
const struct bt_uuid *uuid; const struct bt_uuid *uuid;
}; };
/* Include Attribute Value */ /*! @brief Include Attribute Value. */
struct bt_gatt_include { struct bt_gatt_include {
/*! Service start handle. */
uint16_t start_handle; uint16_t start_handle;
/*! Service end handle. */
uint16_t end_handle; uint16_t end_handle;
/*! Service UUID. */
const struct bt_uuid *uuid; const struct bt_uuid *uuid;
}; };
/* Characteristic Properties Bitfield values */ /* 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 #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 #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 #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 #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 #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 #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 #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 #define BT_GATT_CHRC_EXT_PROP 0x80
/* Characteristic Attribute Value */ /*! @brief Characteristic Attribute Value. */
struct bt_gatt_chrc { struct bt_gatt_chrc {
/*! Characteristic properties. */
uint8_t properties; uint8_t properties;
/*! Characteristic value handle. */
uint16_t value_handle; uint16_t value_handle;
/*! Characteristic UUID. */
const struct bt_uuid *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_RELIABLE_WRITE 0x01
#define BT_GATT_CEP_WRITABLE_AUX 0x02 #define BT_GATT_CEP_WRITABLE_AUX 0x02
/* Characteristic Extended Properties Attribute Value */ /*! @brief Characteristic Extended Properties Attribute Value. */
struct bt_gatt_cep { struct bt_gatt_cep {
/*! Characteristic Extended properties. */
uint8_t properties; uint8_t properties;
}; };
/* Characteristic User Description Attribute Value */ /* @brief Characteristic User Description Attribute Value. */
struct bt_gatt_cud { struct bt_gatt_cud {
/*! Characteristic User Description string. */
char *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 #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 #define BT_GATT_CCC_INDICATE 0x0002
/* Client Characteristic Configuration Attribute Value */ /* Client Characteristic Configuration Attribute Value */
struct bt_gatt_ccc { struct bt_gatt_ccc {
/*! Client Characteristic Configuration flags */
uint16_t flags; uint16_t flags;
}; };
/* Server API */ /* Server API */
/** @brief Register attribute database /*! @brief Register attribute database.
* *
* Register GATT attribute database table. Applications can make use of * Register GATT attribute database table. Applications can make use of
* macros such as BT_GATT_PRIMARY_SERVICE, BT_GATT_CHARACTERISTIC, * macros such as BT_GATT_PRIMARY_SERVICE, BT_GATT_CHARACTERISTIC,
* BT_GATT_DESCRIPTOR, etc. * BT_GATT_DESCRIPTOR, etc.
* *
* @param attrs dabase table containing the available attributes * @param attrs dabase table containing the available attributes.
* @param count size of database table * @param count size of database table.
*/ */
void bt_gatt_register(const struct bt_gatt_attr *attrs, size_t count); void bt_gatt_register(const struct bt_gatt_attr *attrs, size_t count);
@ -129,10 +229,10 @@ enum {
BT_GATT_ITER_CONTINUE, BT_GATT_ITER_CONTINUE,
}; };
/** @brief Attribute iterator callback /*! @brief Attribute iterator callback.
* *
* @param attr attribute found * @param attr attribute found.
* @param user_data data given * @param user_data data given.
* *
* @return BT_GATT_ITER_CONTINUE if should continue to the next attribute * @return BT_GATT_ITER_CONTINUE if should continue to the next attribute
* or BT_GATT_ITER_STOP to stop. * 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, typedef uint8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr,
void *user_data); void *user_data);
/** @brief Attribute iterator /*! @brief Attribute iterator.
* *
* Iterate attributes in the given range. * Iterate attributes in the given range.
* *
* @param start_handle uint16_t start handle * @param start_handle start handle.
* @param end_handle uint16_t end handle * @param end_handle end handle.
* @param func bt_gatt_attr_func_t callback function * @param func callback function.
* @param user_data void * data to pass to the callback * @param user_data data to pass to the callback.
*/ */
void bt_gatt_foreach_attr(uint16_t start_handle, uint16_t end_handle, void bt_gatt_foreach_attr(uint16_t start_handle, uint16_t end_handle,
bt_gatt_attr_func_t func, void *user_data); 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. * Read attribute value storing the result into buffer.
* *
* @param peer remote address * @param peer remote address.
* @param attr attribute to read * @param attr attribute to read.
* @param buf buffer to store the value * @param buf buffer to store the value.
* @param buf_len buffer length * @param buf_len buffer length.
* @param offset start offset * @param offset start offset.
* @param value attribute value * @param value attribute value.
* @param value_len length of the attribute value * @param value_len length of the attribute value.
* *
* @return int number of bytes read in case of success or negative values in * @return int number of bytes read in case of success or negative values in
* case of error. * 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, void *buf, uint8_t buf_len, uint16_t offset,
const void *value, uint8_t value_len); 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 * Read service attribute value storing the result into buffer after
* enconding it. * enconding it.
* NOTE: Only use this with attributes which user_data is a bt_uuid. * NOTE: Only use this with attributes which user_data is a bt_uuid.
* *
* @param peer remote address * @param peer remote address.
* @param attr attribute to read * @param attr attribute to read.
* @param buf buffer to store the value read * @param buf buffer to store the value read.
* @param len buffer length * @param len buffer length.
* @param offset start offset * @param offset start offset.
* *
* @return int number of bytes read in case of success or negative values in * @return int number of bytes read in case of success or negative values in
* case of error. * 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, const struct bt_gatt_attr *attr,
void *buf, uint8_t len, uint16_t offset); 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. * Helper macro to declare a service attribute.
* *
* @param _handle service attribute handle * @param _handle service attribute handle.
* @param _uuid service attribute type * @param _uuid service attribute type.
* @param _data service attribute value * @param _data service attribute value.
*/ */
#define BT_GATT_SERVICE(_handle, _uuid, _service) \ #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, \ .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. * Helper macro to declare a primary service attribute.
* *
* @param _handle service attribute handle * @param _handle service attribute handle.
* @param _service service attribute value * @param _service service attribute value.
*/ */
#define BT_GATT_PRIMARY_SERVICE(_handle, _service) \ #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, \ .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. * Helper macro to declare a secondary service attribute.
* *
* @param _handle service attribute handle * @param _handle service attribute handle.
* @param _service service attribute value * @param _service service attribute value.
*/ */
#define BT_GATT_SECONDARY_SERVICE(_handle, _service) \ #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, \ .user_data = _service, \
} }
/** @brief Read Include Attribute helper /*! @brief Read Include Attribute helper.
* *
* Read include service attribute value storing the result into buffer after * Read include service attribute value storing the result into buffer after
* enconding it. * enconding it.
* NOTE: Only use this with attributes which user_data is a bt_gatt_include. * NOTE: Only use this with attributes which user_data is a bt_gatt_include.
* *
* @param peer remote address * @param peer remote address.
* @param attr attribute to read * @param attr attribute to read.
* @param buf buffer to store the value read * @param buf buffer to store the value read.
* @param len buffer length * @param len buffer length.
* @param offset start offset * @param offset start offset.
* *
* @return int number of bytes read in case of success or negative values in * @return int number of bytes read in case of success or negative values in
* case of error. * 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, const struct bt_gatt_attr *attr,
void *buf, uint8_t len, uint16_t offset); 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) \ #define BT_GATT_INCLUDE_SERVICE(_handle, _service) \
{ \ { \
.handle = _handle, \ .handle = _handle, \
@ -271,17 +381,17 @@ int bt_gatt_attr_read_included(const bt_addr_le_t *peer,
.user_data = _service, \ .user_data = _service, \
} }
/** @brief Read Characteristic Attribute helper /*! @brief Read Characteristic Attribute helper.
* *
* Read characteristic attribute value storing the result into buffer after * Read characteristic attribute value storing the result into buffer after
* enconding it. * enconding it.
* NOTE: Only use this with attributes which user_data is a bt_gatt_chrc. * NOTE: Only use this with attributes which user_data is a bt_gatt_chrc.
* *
* @param peer remote address * @param peer remote address.
* @param attr attribute to read * @param attr attribute to read.
* @param buf buffer to store the value read * @param buf buffer to store the value read.
* @param len buffer length * @param len buffer length.
* @param offset start offset * @param offset start offset.
* *
* @return number of bytes read in case of success or negative values in * @return number of bytes read in case of success or negative values in
* case of error. * 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, const struct bt_gatt_attr *attr, void *buf,
uint8_t len, uint16_t offset); 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. * Helper macro to declare a characteristic attribute.
* *
* @param _handle characteristic attribute handle * @param _handle characteristic attribute handle.
* @param _value characteristic attribute value * @param _value characteristic attribute value.
*/ */
#define BT_GATT_CHARACTERISTIC(_handle, _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, \ .user_data = _value, \
} }
/*! @brief GATT CCC configuration entry. */
struct bt_gatt_ccc_cfg { struct bt_gatt_ccc_cfg {
/*! Config peer address. */
bt_addr_le_t peer; bt_addr_le_t peer;
/*! Config peer value. */
uint16_t value; uint16_t value;
/*! Config valid flag. */
uint8_t valid; uint8_t valid;
}; };
/* Internal representation of CCC value */
struct _bt_gatt_ccc { struct _bt_gatt_ccc {
struct bt_gatt_ccc_cfg *cfg; struct bt_gatt_ccc_cfg *cfg;
size_t cfg_len; size_t cfg_len;
@ -321,17 +437,17 @@ struct _bt_gatt_ccc {
void (*cfg_changed)(uint16_t value); 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 * Read CCC attribute value storing the result into buffer after
* enconding it. * enconding it.
* NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc. * NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc.
* *
* @param peer remote address * @param peer remote address.
* @param attr attribute to read * @param attr attribute to read.
* @param buf buffer to store the value read * @param buf buffer to store the value read.
* @param len buffer length * @param len buffer length.
* @param offset start offset * @param offset start offset.
* *
* @return number of bytes read in case of success or negative values in * @return number of bytes read in case of success or negative values in
* case of error. * 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, const struct bt_gatt_attr *attr, void *buf,
uint8_t len, uint16_t offset); 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. * Write value in the buffer into CCC attribute.
* NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc. * NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc.
* *
* @param peer remote address * @param peer remote address.
* @param attr attribute to read * @param attr attribute to read.
* @param buf buffer to store the value read * @param buf buffer to store the value read.
* @param len buffer length * @param len buffer length.
* @param offset start offset * @param offset start offset.
* *
* @return number of bytes written in case of success or negative values in * @return number of bytes written in case of success or negative values in
* case of error. * 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, const struct bt_gatt_attr *attr, const void *buf,
uint8_t len, uint16_t offset); 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. * Helper macro to declare a CCC attribute.
* *
* @param _handle descriptor attribute handle * @param _handle descriptor attribute handle.
* @param _value_handle characteristic attribute value handle * @param _value_handle characteristic attribute value handle.
* @param _cfg initial configuration * @param _cfg initial configuration.
* @param _cfg_changed configuration changed callback * @param _cfg_changed configuration changed callback.
*/ */
#define BT_GATT_CCC(_handle, _value_handle, _cfg, _cfg_changed) \ #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, }),\ .cfg_changed = _cfg_changed, }),\
} }
/** @brief Descriptor Declaration Macro /*! @def BT_GATT_DESCRIPTOR
* @brief Descriptor Declaration Macro.
* *
* Helper macro to declare a descriptor attribute. * Helper macro to declare a descriptor attribute.
* *
* @param _handle descriptor attribute handle * @param _handle descriptor attribute handle.
* @param _value descriptor attribute value * @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) \ #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, \ .user_data = _value, \
} }
/** @brief Notify attribute value change /*! @brief Notify attribute value change.
* *
* Send notification of attribute value change. * Send notification of attribute value change.
* Note: This function should only be called if CCC is declared with * Note: This function should only be called if CCC is declared with
* BT_GATT_CCC otherwise it cannot find a valid peer configuration. * BT_GATT_CCC otherwise it cannot find a valid peer configuration.
* *
* @param handle attribute handle * @param handle attribute handle.
* @param value attribute value * @param value attribute value.
* @param len attribute value length * @param len attribute value length.
*/ */
void bt_gatt_notify(uint16_t handle, const void *data, size_t len); void bt_gatt_notify(uint16_t handle, const void *data, size_t len);