Bluetooth: Update documentation of GATT API

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

View file

@ -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 <misc/util.h>
/* 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);