ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

BLE: Update GattAttribute documentation.

pull/5549/head
Vincent Coubard 2017-11-17 14:39:39 +00:00
parent b025ea16d6
commit c4351d31d8
1 changed files with 114 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
features/FEATURE_BLE/ble/GattAttribute.h
View File

@ -14,8 +14,8 @@
* limitations under the License. * limitations under the License.
*/ */
#ifndef __GATT_ATTRIBUTE_H__ #ifndef MBED_GATT_ATTRIBUTE_H__
#define __GATT_ATTRIBUTE_H__ #define MBED_GATT_ATTRIBUTE_H__
#include "UUID.h" #include "UUID.h"
#include "BLETypes.h" #include "BLETypes.h"
@ -30,67 +30,116 @@
*/ */
/** /**
* Instances of this class encapsulate the data that belongs to a Bluetooth Low * Representation of a GattServer attribute.
* Energy attribute. *
* Attributes are the building block of GATT servers: services are attributes,
* characteristics are groups of attributes and characteristic descriptors are
* attributes too.
*
* @par Typed values
*
* Attributes are typed values composed of a type and its associated value. The
* attribute type identifies the attribute purpose and is modelled by a UUID
* read by the client during the discovery of the gatt server. The value of the
* attribute is an array of bytes; its length may be fixed or variable.
*
* As an example a primary service is declared by an attribute with the type
* 0x2800 and the value of the attribute is the UUID of the service.
*
* @par Attribute Access
*
* The GATT server is an array of attributes were each of the attributes is
* identified within the array by a unique index. That index is called the
* attribute handle and clients use it to access to attributes within the server.
*
* @note Attributes do not contain information related to their permissions,
* grouping or semantic. Higher level specifications define these concepts.
*/ */
class GattAttribute { class GattAttribute {
public: public:
/** /**
* Type for the handle or ID of the attribute in the ATT table. These are * Representation of an attribute handle.
* unique, and the underlying BLE stack usually generates them. *
* Each attribute in a GattServer have a unique handle that can be used by
* clients to identify the attribute. The underlying BLE stack usually
* generates and assign handles to attributes.
*/ */
typedef ble::attribute_handle_t Handle_t; typedef ble::attribute_handle_t Handle_t;
/** /**
* Define the value of an invalid attribute handle. * Invalid attribute handle.
*/ */
static const Handle_t INVALID_HANDLE = 0x0000; static const Handle_t INVALID_HANDLE = 0x0000;
public: public:
/** /**
* @brief Creates a new GattAttribute using the specified * Construct an attribute.
* UUID, value length, and inital value.
* *
* @param[in] uuid * Application code use attributes to model characteristic descriptors and
* The UUID to use for this attribute. * characteristics values.
* @param[in] valuePtr
* The memory holding the initial value.
* @param[in] len
* The length in bytes of this attribute's value.
* @param[in] maxLen
* The max length in bytes of this attribute's value.
* @param[in] hasVariableLen
* Whether the attribute's value length changes over time.
* *
* @section EXAMPLE * @param[in] uuid The type of the attribute.
* @param[in] valuePtr Pointer to the memory buffer which contains the
* initial value of the attribute. The constructor does not make a copy of
* the attribute buffer; as a consequence the memory buffer must remain
* valid during the lifetime of the attribute.
* @param[in] len The length in bytes of this attribute's value.
* @param[in] maxLen The length in bytes of the memory buffer containing the
* attribute value. It must be greater than or equal to @p len.
* @param[in] hasVariableLen Flag that indicate if the attribute's value
* length can changes over time.
* *
* @code * @par Example
* *
* // UUID = 0x2A19, Min length 2, Max len = 2 * @code
* GattAttribute attr = GattAttribute(0x2A19, &someValue, 2, 2); * // declare a value of 2 bytes within a 10 bytes buffer
* * const uint8_t attribute_value[10] = { 10, 50 };
* @endcode * GattAttribute attr = GattAttribute(
* 0x2A19, // attribute type
* attribute_value,
* 2, // length of the current value
* sizeof(attribute_value), // length of the buffer containing the value
* true // variable length
* );
* @endcode
*/ */
GattAttribute(const UUID &uuid, uint8_t *valuePtr = NULL, uint16_t len = 0, uint16_t maxLen = 0, bool hasVariableLen = true) : GattAttribute(
_uuid(uuid), _valuePtr(valuePtr), _lenMax(maxLen), _len(len), _hasVariableLen(hasVariableLen), _handle() { const UUID &uuid,
/* Empty */ uint8_t *valuePtr = NULL,
uint16_t len = 0,
uint16_t maxLen = 0,
bool hasVariableLen = true
) : _uuid(uuid),
_valuePtr(valuePtr),
_lenMax(maxLen),
_len(len),
_hasVariableLen(hasVariableLen),
_handle() {
} }
public: public:
/** /**
* Get the attribute's handle in the ATT table. * Get the attribute's handle in the ATT table.
* *
* @note The attribute's handle is set by the GattServer when services are
* inserted.
*
* @return The attribute's handle. * @return The attribute's handle.
*/ */
Handle_t getHandle(void) const { Handle_t getHandle(void) const
{
return _handle; return _handle;
} }
/** /**
* The UUID of the characteristic that this attribute belongs to. * Get the UUID of the attribute.
* *
* @return The characteristic's UUID. * The UUID identifies the type of the attribute.
*
* @return The attribute.
*/ */
const UUID &getUUID(void) const { const UUID &getUUID(void) const
{
return _uuid; return _uuid;
} }
@ -99,7 +148,8 @@ public:
* *
* @return The current length of the attribute value. * @return The current length of the attribute value.
*/ */
uint16_t getLength(void) const { uint16_t getLength(void) const
{
return _len; return _len;
} }
@ -108,26 +158,33 @@ public:
* *
* The maximum length of the attribute value. * The maximum length of the attribute value.
*/ */
uint16_t getMaxLength(void) const { uint16_t getMaxLength(void) const
{
return _lenMax; return _lenMax;
} }
/** /**
* Get a pointer to the current length of the attribute value. * Get a pointer to the current length of the attribute value.
* *
* @important note Do not use this function.
*
* @return A pointer to the current length of the attribute value. * @return A pointer to the current length of the attribute value.
*/ */
uint16_t *getLengthPtr(void) { uint16_t *getLengthPtr(void)
{
return &_len; return &_len;
} }
/** /**
* Set the attribute handle. * Set the attribute handle.
* *
* @param[in] id * @important This function is used internally by the GattServer and must
* The new attribute handle. * not be used by application code.
*
* @param[in] id The new attribute handle.
*/ */
void setHandle(Handle_t id) { void setHandle(Handle_t id)
{
_handle = id; _handle = id;
} }
@ -136,16 +193,19 @@ public:
* *
* @return A pointer to the attribute value. * @return A pointer to the attribute value.
*/ */
uint8_t *getValuePtr(void) { uint8_t *getValuePtr(void)
{
return _valuePtr; return _valuePtr;
} }
/** /**
* Check whether the length of the attribute's value can change over time. * Check whether the length of the attribute's value can change over time.
* *
* @return true if the attribute has variable length, false otherwise. * @return true if the attribute value has a variable length and false
* otherwise.
*/ */
bool hasVariableLength(void) const { bool hasVariableLength(void) const
{
return _hasVariableLen; return _hasVariableLen;
} }
@ -153,27 +213,32 @@ private:
/** /**
* Characteristic's UUID. * Characteristic's UUID.
*/ */
UUID _uuid; UUID _uuid;
/** /**
* Pointer to the attribute's value. * Pointer to the attribute's value.
*/ */
uint8_t *_valuePtr; uint8_t *_valuePtr;
/** /**
* Maximum length of the value pointed to by GattAttribute::_valuePtr. * Length in byte of the buffer containing the attribute value.
*/ */
uint16_t _lenMax; uint16_t _lenMax;
/** /**
* Current length of the value pointed to by GattAttribute::_valuePtr. * Current length of the value pointed to by GattAttribute::_valuePtr.
*/ */
uint16_t _len; uint16_t _len;
/** /**
* Whether the length of the value can change over time. * Whether the length of the value can change over time.
*/ */
bool _hasVariableLen; bool _hasVariableLen;
/** /**
* The attribute's handle in the ATT table. * The attribute's handle in the ATT table.
*/ */
Handle_t _handle; Handle_t _handle;
private: private:
/* Disallow copy and assignment. */ /* Disallow copy and assignment. */
@ -187,4 +252,4 @@ private:
* @} * @}
*/ */
#endif /* ifndef __GATT_ATTRIBUTE_H__ */ #endif /* ifndef MBED_GATT_ATTRIBUTE_H__ */