Marco Zecchini / Mbed OS Example_RTOS

Rtos API example

mbed-os/features/FEATURE_BLE/ble/GattAttribute.h@0:9fca2b23d0ba, 2019-02-23 (annotated)

Committer:
marcozecchini
Date:
Sat Feb 23 12:13:36 2019 +0000
Revision:
0:9fca2b23d0ba
final commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
marcozecchini 0:9fca2b23d0ba 1 /* mbed Microcontroller Library
marcozecchini 0:9fca2b23d0ba 2 * Copyright (c) 2006-2013 ARM Limited
marcozecchini 0:9fca2b23d0ba 3 *
marcozecchini 0:9fca2b23d0ba 4 * Licensed under the Apache License, Version 2.0 (the "License");
marcozecchini 0:9fca2b23d0ba 5 * you may not use this file except in compliance with the License.
marcozecchini 0:9fca2b23d0ba 6 * You may obtain a copy of the License at
marcozecchini 0:9fca2b23d0ba 7 *
marcozecchini 0:9fca2b23d0ba 8 * http://www.apache.org/licenses/LICENSE-2.0
marcozecchini 0:9fca2b23d0ba 9 *
marcozecchini 0:9fca2b23d0ba 10 * Unless required by applicable law or agreed to in writing, software
marcozecchini 0:9fca2b23d0ba 11 * distributed under the License is distributed on an "AS IS" BASIS,
marcozecchini 0:9fca2b23d0ba 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
marcozecchini 0:9fca2b23d0ba 13 * See the License for the specific language governing permissions and
marcozecchini 0:9fca2b23d0ba 14 * limitations under the License.
marcozecchini 0:9fca2b23d0ba 15 */
marcozecchini 0:9fca2b23d0ba 16
marcozecchini 0:9fca2b23d0ba 17 #ifndef MBED_GATT_ATTRIBUTE_H__
marcozecchini 0:9fca2b23d0ba 18 #define MBED_GATT_ATTRIBUTE_H__
marcozecchini 0:9fca2b23d0ba 19
marcozecchini 0:9fca2b23d0ba 20 #include "UUID.h"
marcozecchini 0:9fca2b23d0ba 21 #include "BLETypes.h"
marcozecchini 0:9fca2b23d0ba 22
marcozecchini 0:9fca2b23d0ba 23 /**
marcozecchini 0:9fca2b23d0ba 24 * @addtogroup ble
marcozecchini 0:9fca2b23d0ba 25 * @{
marcozecchini 0:9fca2b23d0ba 26 * @addtogroup gatt
marcozecchini 0:9fca2b23d0ba 27 * @{
marcozecchini 0:9fca2b23d0ba 28 * @addtogroup server
marcozecchini 0:9fca2b23d0ba 29 * @{
marcozecchini 0:9fca2b23d0ba 30 */
marcozecchini 0:9fca2b23d0ba 31
marcozecchini 0:9fca2b23d0ba 32 /**
marcozecchini 0:9fca2b23d0ba 33 * Representation of a GattServer attribute.
marcozecchini 0:9fca2b23d0ba 34 *
marcozecchini 0:9fca2b23d0ba 35 * Attributes are the building block of GATT servers: services are attributes,
marcozecchini 0:9fca2b23d0ba 36 * characteristics are groups of attributes and characteristic descriptors are
marcozecchini 0:9fca2b23d0ba 37 * attributes, too.
marcozecchini 0:9fca2b23d0ba 38 *
marcozecchini 0:9fca2b23d0ba 39 * @par Typed values
marcozecchini 0:9fca2b23d0ba 40 *
marcozecchini 0:9fca2b23d0ba 41 * Attributes are typed values composed of a type and its associated value. The
marcozecchini 0:9fca2b23d0ba 42 * attribute type identifies the attribute purpose. A UUID read by the client
marcozecchini 0:9fca2b23d0ba 43 * during the discovery of the GATT server models the attribute type. The value of the
marcozecchini 0:9fca2b23d0ba 44 * attribute is an array of bytes; its length may be fixed or variable.
marcozecchini 0:9fca2b23d0ba 45 *
marcozecchini 0:9fca2b23d0ba 46 * As an example, a primary service is declared by an attribute with the type
marcozecchini 0:9fca2b23d0ba 47 * 0x2800, and the value of the attribute is the UUID of the service.
marcozecchini 0:9fca2b23d0ba 48 *
marcozecchini 0:9fca2b23d0ba 49 * @par Attribute Access
marcozecchini 0:9fca2b23d0ba 50 *
marcozecchini 0:9fca2b23d0ba 51 * The GATT server is an array of attributes in which a unique index identifies
marcozecchini 0:9fca2b23d0ba 52 * each of the attributes within the array. That index is called the attribute
marcozecchini 0:9fca2b23d0ba 53 * handle, and clients use it to access to attributes within the server.
marcozecchini 0:9fca2b23d0ba 54 *
marcozecchini 0:9fca2b23d0ba 55 * @note Attributes do not contain information related to their permissions,
marcozecchini 0:9fca2b23d0ba 56 * grouping or semantic. Higher level specifications define these concepts.
marcozecchini 0:9fca2b23d0ba 57 */
marcozecchini 0:9fca2b23d0ba 58 class GattAttribute {
marcozecchini 0:9fca2b23d0ba 59 public:
marcozecchini 0:9fca2b23d0ba 60 /**
marcozecchini 0:9fca2b23d0ba 61 * Representation of an attribute handle.
marcozecchini 0:9fca2b23d0ba 62 *
marcozecchini 0:9fca2b23d0ba 63 * Each attribute in a GattServer has a unique handle that clients can use
marcozecchini 0:9fca2b23d0ba 64 * to identify the attribute. The underlying BLE stack usually
marcozecchini 0:9fca2b23d0ba 65 * generates and assigns handles to attributes.
marcozecchini 0:9fca2b23d0ba 66 */
marcozecchini 0:9fca2b23d0ba 67 typedef ble::attribute_handle_t Handle_t;
marcozecchini 0:9fca2b23d0ba 68
marcozecchini 0:9fca2b23d0ba 69 /**
marcozecchini 0:9fca2b23d0ba 70 * Invalid attribute handle.
marcozecchini 0:9fca2b23d0ba 71 */
marcozecchini 0:9fca2b23d0ba 72 static const Handle_t INVALID_HANDLE = 0x0000;
marcozecchini 0:9fca2b23d0ba 73
marcozecchini 0:9fca2b23d0ba 74 public:
marcozecchini 0:9fca2b23d0ba 75 /**
marcozecchini 0:9fca2b23d0ba 76 * Construct an attribute.
marcozecchini 0:9fca2b23d0ba 77 *
marcozecchini 0:9fca2b23d0ba 78 * Application code uses attributes to model characteristic descriptors and
marcozecchini 0:9fca2b23d0ba 79 * characteristics values.
marcozecchini 0:9fca2b23d0ba 80 *
marcozecchini 0:9fca2b23d0ba 81 * @param[in] uuid The type of the attribute.
marcozecchini 0:9fca2b23d0ba 82 * @param[in] valuePtr Pointer to the memory buffer, which contains the
marcozecchini 0:9fca2b23d0ba 83 * initial value of the attribute. The constructor does not make a copy of
marcozecchini 0:9fca2b23d0ba 84 * the attribute buffer; as a consequence, the memory buffer must remain
marcozecchini 0:9fca2b23d0ba 85 * valid during the lifetime of the attribute.
marcozecchini 0:9fca2b23d0ba 86 * @param[in] len The length in bytes of this attribute's value.
marcozecchini 0:9fca2b23d0ba 87 * @param[in] maxLen The length in bytes of the memory buffer containing the
marcozecchini 0:9fca2b23d0ba 88 * attribute value. It must be greater than or equal to @p len.
marcozecchini 0:9fca2b23d0ba 89 * @param[in] hasVariableLen Flag that indicates whether the attribute's value
marcozecchini 0:9fca2b23d0ba 90 * length can change throughout time.
marcozecchini 0:9fca2b23d0ba 91 *
marcozecchini 0:9fca2b23d0ba 92 * @par Example
marcozecchini 0:9fca2b23d0ba 93 *
marcozecchini 0:9fca2b23d0ba 94 * @code
marcozecchini 0:9fca2b23d0ba 95 * // declare a value of 2 bytes within a 10 bytes buffer
marcozecchini 0:9fca2b23d0ba 96 * const uint8_t attribute_value[10] = { 10, 50 };
marcozecchini 0:9fca2b23d0ba 97 * GattAttribute attr = GattAttribute(
marcozecchini 0:9fca2b23d0ba 98 * 0x2A19, // attribute type
marcozecchini 0:9fca2b23d0ba 99 * attribute_value,
marcozecchini 0:9fca2b23d0ba 100 * 2, // length of the current value
marcozecchini 0:9fca2b23d0ba 101 * sizeof(attribute_value), // length of the buffer containing the value
marcozecchini 0:9fca2b23d0ba 102 * true // variable length
marcozecchini 0:9fca2b23d0ba 103 * );
marcozecchini 0:9fca2b23d0ba 104 * @endcode
marcozecchini 0:9fca2b23d0ba 105 */
marcozecchini 0:9fca2b23d0ba 106 GattAttribute(
marcozecchini 0:9fca2b23d0ba 107 const UUID &uuid,
marcozecchini 0:9fca2b23d0ba 108 uint8_t *valuePtr = NULL,
marcozecchini 0:9fca2b23d0ba 109 uint16_t len = 0,
marcozecchini 0:9fca2b23d0ba 110 uint16_t maxLen = 0,
marcozecchini 0:9fca2b23d0ba 111 bool hasVariableLen = true
marcozecchini 0:9fca2b23d0ba 112 ) : _uuid(uuid),
marcozecchini 0:9fca2b23d0ba 113 _valuePtr(valuePtr),
marcozecchini 0:9fca2b23d0ba 114 _lenMax(maxLen),
marcozecchini 0:9fca2b23d0ba 115 _len(len),
marcozecchini 0:9fca2b23d0ba 116 _hasVariableLen(hasVariableLen),
marcozecchini 0:9fca2b23d0ba 117 _handle() {
marcozecchini 0:9fca2b23d0ba 118 }
marcozecchini 0:9fca2b23d0ba 119
marcozecchini 0:9fca2b23d0ba 120 public:
marcozecchini 0:9fca2b23d0ba 121 /**
marcozecchini 0:9fca2b23d0ba 122 * Get the attribute's handle in the ATT table.
marcozecchini 0:9fca2b23d0ba 123 *
marcozecchini 0:9fca2b23d0ba 124 * @note The GattServer sets the attribute's handle when services are
marcozecchini 0:9fca2b23d0ba 125 * inserted.
marcozecchini 0:9fca2b23d0ba 126 *
marcozecchini 0:9fca2b23d0ba 127 * @return The attribute's handle.
marcozecchini 0:9fca2b23d0ba 128 */
marcozecchini 0:9fca2b23d0ba 129 Handle_t getHandle(void) const
marcozecchini 0:9fca2b23d0ba 130 {
marcozecchini 0:9fca2b23d0ba 131 return _handle;
marcozecchini 0:9fca2b23d0ba 132 }
marcozecchini 0:9fca2b23d0ba 133
marcozecchini 0:9fca2b23d0ba 134 /**
marcozecchini 0:9fca2b23d0ba 135 * Get the UUID of the attribute.
marcozecchini 0:9fca2b23d0ba 136 *
marcozecchini 0:9fca2b23d0ba 137 * The UUID identifies the type of the attribute.
marcozecchini 0:9fca2b23d0ba 138 *
marcozecchini 0:9fca2b23d0ba 139 * @return The attribute.
marcozecchini 0:9fca2b23d0ba 140 */
marcozecchini 0:9fca2b23d0ba 141 const UUID &getUUID(void) const
marcozecchini 0:9fca2b23d0ba 142 {
marcozecchini 0:9fca2b23d0ba 143 return _uuid;
marcozecchini 0:9fca2b23d0ba 144 }
marcozecchini 0:9fca2b23d0ba 145
marcozecchini 0:9fca2b23d0ba 146 /**
marcozecchini 0:9fca2b23d0ba 147 * Get the current length of the attribute value.
marcozecchini 0:9fca2b23d0ba 148 *
marcozecchini 0:9fca2b23d0ba 149 * @return The current length of the attribute value.
marcozecchini 0:9fca2b23d0ba 150 */
marcozecchini 0:9fca2b23d0ba 151 uint16_t getLength(void) const
marcozecchini 0:9fca2b23d0ba 152 {
marcozecchini 0:9fca2b23d0ba 153 return _len;
marcozecchini 0:9fca2b23d0ba 154 }
marcozecchini 0:9fca2b23d0ba 155
marcozecchini 0:9fca2b23d0ba 156 /**
marcozecchini 0:9fca2b23d0ba 157 * Get the maximum length of the attribute value.
marcozecchini 0:9fca2b23d0ba 158 *
marcozecchini 0:9fca2b23d0ba 159 * The maximum length of the attribute value.
marcozecchini 0:9fca2b23d0ba 160 */
marcozecchini 0:9fca2b23d0ba 161 uint16_t getMaxLength(void) const
marcozecchini 0:9fca2b23d0ba 162 {
marcozecchini 0:9fca2b23d0ba 163 return _lenMax;
marcozecchini 0:9fca2b23d0ba 164 }
marcozecchini 0:9fca2b23d0ba 165
marcozecchini 0:9fca2b23d0ba 166 /**
marcozecchini 0:9fca2b23d0ba 167 * Get a pointer to the current length of the attribute value.
marcozecchini 0:9fca2b23d0ba 168 *
marcozecchini 0:9fca2b23d0ba 169 * @important note Do not use this function.
marcozecchini 0:9fca2b23d0ba 170 *
marcozecchini 0:9fca2b23d0ba 171 * @return A pointer to the current length of the attribute value.
marcozecchini 0:9fca2b23d0ba 172 */
marcozecchini 0:9fca2b23d0ba 173 uint16_t *getLengthPtr(void)
marcozecchini 0:9fca2b23d0ba 174 {
marcozecchini 0:9fca2b23d0ba 175 return &_len;
marcozecchini 0:9fca2b23d0ba 176 }
marcozecchini 0:9fca2b23d0ba 177
marcozecchini 0:9fca2b23d0ba 178 /**
marcozecchini 0:9fca2b23d0ba 179 * Set the attribute handle.
marcozecchini 0:9fca2b23d0ba 180 *
marcozecchini 0:9fca2b23d0ba 181 * @important The GattServer uses this function internally.
marcozecchini 0:9fca2b23d0ba 182 * Application code must not use it.
marcozecchini 0:9fca2b23d0ba 183 *
marcozecchini 0:9fca2b23d0ba 184 * @param[in] id The new attribute handle.
marcozecchini 0:9fca2b23d0ba 185 */
marcozecchini 0:9fca2b23d0ba 186 void setHandle(Handle_t id)
marcozecchini 0:9fca2b23d0ba 187 {
marcozecchini 0:9fca2b23d0ba 188 _handle = id;
marcozecchini 0:9fca2b23d0ba 189 }
marcozecchini 0:9fca2b23d0ba 190
marcozecchini 0:9fca2b23d0ba 191 /**
marcozecchini 0:9fca2b23d0ba 192 * Get a pointer to the attribute value.
marcozecchini 0:9fca2b23d0ba 193 *
marcozecchini 0:9fca2b23d0ba 194 * @return A pointer to the attribute value.
marcozecchini 0:9fca2b23d0ba 195 */
marcozecchini 0:9fca2b23d0ba 196 uint8_t *getValuePtr(void)
marcozecchini 0:9fca2b23d0ba 197 {
marcozecchini 0:9fca2b23d0ba 198 return _valuePtr;
marcozecchini 0:9fca2b23d0ba 199 }
marcozecchini 0:9fca2b23d0ba 200
marcozecchini 0:9fca2b23d0ba 201 /**
marcozecchini 0:9fca2b23d0ba 202 * Check whether the length of the attribute's value can change throughout time.
marcozecchini 0:9fca2b23d0ba 203 *
marcozecchini 0:9fca2b23d0ba 204 * @return true if the attribute value has a variable length and false
marcozecchini 0:9fca2b23d0ba 205 * otherwise.
marcozecchini 0:9fca2b23d0ba 206 */
marcozecchini 0:9fca2b23d0ba 207 bool hasVariableLength(void) const
marcozecchini 0:9fca2b23d0ba 208 {
marcozecchini 0:9fca2b23d0ba 209 return _hasVariableLen;
marcozecchini 0:9fca2b23d0ba 210 }
marcozecchini 0:9fca2b23d0ba 211
marcozecchini 0:9fca2b23d0ba 212 private:
marcozecchini 0:9fca2b23d0ba 213 /**
marcozecchini 0:9fca2b23d0ba 214 * Characteristic's UUID.
marcozecchini 0:9fca2b23d0ba 215 */
marcozecchini 0:9fca2b23d0ba 216 UUID _uuid;
marcozecchini 0:9fca2b23d0ba 217
marcozecchini 0:9fca2b23d0ba 218 /**
marcozecchini 0:9fca2b23d0ba 219 * Pointer to the attribute's value.
marcozecchini 0:9fca2b23d0ba 220 */
marcozecchini 0:9fca2b23d0ba 221 uint8_t *_valuePtr;
marcozecchini 0:9fca2b23d0ba 222
marcozecchini 0:9fca2b23d0ba 223 /**
marcozecchini 0:9fca2b23d0ba 224 * Length in byte of the buffer containing the attribute value.
marcozecchini 0:9fca2b23d0ba 225 */
marcozecchini 0:9fca2b23d0ba 226 uint16_t _lenMax;
marcozecchini 0:9fca2b23d0ba 227
marcozecchini 0:9fca2b23d0ba 228 /**
marcozecchini 0:9fca2b23d0ba 229 * Current length of the value pointed to by GattAttribute::_valuePtr.
marcozecchini 0:9fca2b23d0ba 230 */
marcozecchini 0:9fca2b23d0ba 231 uint16_t _len;
marcozecchini 0:9fca2b23d0ba 232
marcozecchini 0:9fca2b23d0ba 233 /**
marcozecchini 0:9fca2b23d0ba 234 * Whether the length of the value can change throughout time.
marcozecchini 0:9fca2b23d0ba 235 */
marcozecchini 0:9fca2b23d0ba 236 bool _hasVariableLen;
marcozecchini 0:9fca2b23d0ba 237
marcozecchini 0:9fca2b23d0ba 238 /**
marcozecchini 0:9fca2b23d0ba 239 * The attribute's handle in the ATT table.
marcozecchini 0:9fca2b23d0ba 240 */
marcozecchini 0:9fca2b23d0ba 241 Handle_t _handle;
marcozecchini 0:9fca2b23d0ba 242
marcozecchini 0:9fca2b23d0ba 243 private:
marcozecchini 0:9fca2b23d0ba 244 /* Disallow copy and assignment. */
marcozecchini 0:9fca2b23d0ba 245 GattAttribute(const GattAttribute &);
marcozecchini 0:9fca2b23d0ba 246 GattAttribute& operator=(const GattAttribute &);
marcozecchini 0:9fca2b23d0ba 247 };
marcozecchini 0:9fca2b23d0ba 248
marcozecchini 0:9fca2b23d0ba 249 /**
marcozecchini 0:9fca2b23d0ba 250 * @}
marcozecchini 0:9fca2b23d0ba 251 * @}
marcozecchini 0:9fca2b23d0ba 252 * @}
marcozecchini 0:9fca2b23d0ba 253 */
marcozecchini 0:9fca2b23d0ba 254
marcozecchini 0:9fca2b23d0ba 255 #endif /* ifndef MBED_GATT_ATTRIBUTE_H__ */