Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
GattAttribute.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2013 ARM Limited 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef MBED_GATT_ATTRIBUTE_H__ 00018 #define MBED_GATT_ATTRIBUTE_H__ 00019 00020 #include "UUID.h " 00021 #include "BLETypes.h" 00022 00023 /** 00024 * @addtogroup ble 00025 * @{ 00026 * @addtogroup gatt 00027 * @{ 00028 * @addtogroup server 00029 * @{ 00030 */ 00031 00032 /** 00033 * Representation of a GattServer attribute. 00034 * 00035 * Attributes are the building block of GATT servers: services are attributes, 00036 * characteristics are groups of attributes and characteristic descriptors are 00037 * attributes, too. 00038 * 00039 * @par Typed values 00040 * 00041 * Attributes are typed values composed of a type and its associated value. The 00042 * attribute type identifies the attribute purpose. A UUID read by the client 00043 * during the discovery of the GATT server models the attribute type. The value of the 00044 * attribute is an array of bytes; its length may be fixed or variable. 00045 * 00046 * As an example, a primary service is declared by an attribute with the type 00047 * 0x2800, and the value of the attribute is the UUID of the service. 00048 * 00049 * @par Attribute Access 00050 * 00051 * The GATT server is an array of attributes in which a unique index identifies 00052 * each of the attributes within the array. That index is called the attribute 00053 * handle, and clients use it to access to attributes within the server. 00054 * 00055 * @note Attributes do not contain information related to their permissions, 00056 * grouping or semantic. Higher level specifications define these concepts. 00057 */ 00058 class GattAttribute { 00059 public: 00060 /** 00061 * Representation of an attribute handle. 00062 * 00063 * Each attribute in a GattServer has a unique handle that clients can use 00064 * to identify the attribute. The underlying BLE stack usually 00065 * generates and assigns handles to attributes. 00066 */ 00067 typedef ble::attribute_handle_t Handle_t; 00068 00069 /** 00070 * Invalid attribute handle. 00071 */ 00072 static const Handle_t INVALID_HANDLE = 0x0000; 00073 00074 public: 00075 00076 typedef ble::att_security_requirement_t Security_t; 00077 00078 /** 00079 * Construct an attribute. 00080 * 00081 * Application code uses attributes to model characteristic descriptors and 00082 * characteristics values. 00083 * 00084 * @param[in] uuid The type of the attribute. 00085 * @param[in] valuePtr Pointer to the memory buffer, which contains the 00086 * initial value of the attribute. The constructor does not make a copy of 00087 * the attribute buffer; as a consequence, the memory buffer must remain 00088 * valid during the lifetime of the attribute. 00089 * @param[in] len The length in bytes of this attribute's value. 00090 * @param[in] maxLen The length in bytes of the memory buffer containing the 00091 * attribute value. It must be greater than or equal to @p len. 00092 * @param[in] hasVariableLen Flag that indicates whether the attribute's value 00093 * length can change throughout time. 00094 * 00095 * @par Example 00096 * 00097 * @code 00098 * // declare a value of 2 bytes within a 10 bytes buffer 00099 * const uint8_t attribute_value[10] = { 10, 50 }; 00100 * GattAttribute attr = GattAttribute( 00101 * 0x2A19, // attribute type 00102 * attribute_value, 00103 * 2, // length of the current value 00104 * sizeof(attribute_value), // length of the buffer containing the value 00105 * true // variable length 00106 * ); 00107 * @endcode 00108 * 00109 * @note By default, read and write operations are allowed and does not 00110 * require any security. 00111 */ 00112 GattAttribute( 00113 const UUID &uuid, 00114 uint8_t *valuePtr = NULL, 00115 uint16_t len = 0, 00116 uint16_t maxLen = 0, 00117 bool hasVariableLen = true 00118 ) : _uuid(uuid), 00119 _valuePtr(valuePtr), 00120 _lenMax(maxLen), 00121 _len(len), 00122 _handle(), 00123 _hasVariableLen(hasVariableLen), 00124 _read_allowed(true), 00125 _read_security(Security_t::NONE), 00126 _write_allowed(true), 00127 _write_security(Security_t::NONE) { 00128 } 00129 00130 public: 00131 /** 00132 * Get the attribute's handle in the ATT table. 00133 * 00134 * @note The GattServer sets the attribute's handle when services are 00135 * inserted. 00136 * 00137 * @return The attribute's handle. 00138 */ 00139 Handle_t getHandle(void) const 00140 { 00141 return _handle; 00142 } 00143 00144 /** 00145 * Get the UUID of the attribute. 00146 * 00147 * The UUID identifies the type of the attribute. 00148 * 00149 * @return The attribute. 00150 */ 00151 const UUID &getUUID(void) const 00152 { 00153 return _uuid; 00154 } 00155 00156 /** 00157 * Get the current length of the attribute value. 00158 * 00159 * @return The current length of the attribute value. 00160 */ 00161 uint16_t getLength(void) const 00162 { 00163 return _len; 00164 } 00165 00166 /** 00167 * Get the maximum length of the attribute value. 00168 * 00169 * The maximum length of the attribute value. 00170 */ 00171 uint16_t getMaxLength(void) const 00172 { 00173 return _lenMax; 00174 } 00175 00176 /** 00177 * Get a pointer to the current length of the attribute value. 00178 * 00179 * @attention note Do not use this function. 00180 * 00181 * @return A pointer to the current length of the attribute value. 00182 */ 00183 uint16_t *getLengthPtr(void) 00184 { 00185 return &_len; 00186 } 00187 00188 /** 00189 * Set the attribute handle. 00190 * 00191 * @attention The GattServer uses this function internally. 00192 * Application code must not use it. 00193 * 00194 * @param[in] id The new attribute handle. 00195 */ 00196 void setHandle(Handle_t id) 00197 { 00198 _handle = id; 00199 } 00200 00201 /** 00202 * Get a pointer to the attribute value. 00203 * 00204 * @return A pointer to the attribute value. 00205 */ 00206 uint8_t *getValuePtr(void) 00207 { 00208 return _valuePtr; 00209 } 00210 00211 /** 00212 * Check whether the length of the attribute's value can change throughout time. 00213 * 00214 * @return true if the attribute value has a variable length and false 00215 * otherwise. 00216 */ 00217 bool hasVariableLength(void) const 00218 { 00219 return _hasVariableLen; 00220 } 00221 00222 /** 00223 * Allow or disallow read operation from a client. 00224 * @param allow_read Read is allowed if true. 00225 */ 00226 void allowRead(bool allow_read) 00227 { 00228 _read_allowed = allow_read; 00229 } 00230 00231 /** 00232 * Indicate if a client is allowed to read the attribute. 00233 * @return true if a client is allowed to read the attribute. 00234 */ 00235 bool isReadAllowed(void) const 00236 { 00237 return _read_allowed; 00238 } 00239 00240 /** 00241 * Set the security requirements of the read operations. 00242 * @param requirement The security level required by the read operations. 00243 */ 00244 void setReadSecurityRequirement(Security_t requirement) 00245 { 00246 _read_security = requirement.value(); 00247 } 00248 00249 /** 00250 * Return the security level required by read operations. 00251 * @return The security level of the read operations. 00252 */ 00253 Security_t getReadSecurityRequirement() const 00254 { 00255 return static_cast<Security_t::type>(_read_security); 00256 } 00257 00258 /** 00259 * Allow or disallow write operation from a client. 00260 * @param allow_write Write is allowed if true. 00261 */ 00262 void allowWrite(bool allow_write) 00263 { 00264 _write_allowed = allow_write; 00265 } 00266 00267 /** 00268 * Indicate if a client is allowed to write the attribute. 00269 * @return true if a client is allowed to write the attribute. 00270 */ 00271 bool isWriteAllowed(void) const 00272 { 00273 return _write_allowed; 00274 } 00275 00276 /** 00277 * Set the security requirements of the write operations. 00278 * @param requirement The security level required by the write operations. 00279 */ 00280 void setWriteSecurityRequirement(Security_t requirement) 00281 { 00282 _write_security = requirement.value(); 00283 } 00284 00285 /** 00286 * Return the security level required by write operations. 00287 * @return The security level of the write operations. 00288 */ 00289 Security_t getWriteSecurityRequirement() const 00290 { 00291 return static_cast<Security_t::type>(_write_security); 00292 } 00293 00294 private: 00295 /** 00296 * Characteristic's UUID. 00297 */ 00298 UUID _uuid; 00299 00300 /** 00301 * Pointer to the attribute's value. 00302 */ 00303 uint8_t *_valuePtr; 00304 00305 /** 00306 * Length in byte of the buffer containing the attribute value. 00307 */ 00308 uint16_t _lenMax; 00309 00310 /** 00311 * Current length of the value pointed to by GattAttribute::_valuePtr. 00312 */ 00313 uint16_t _len; 00314 00315 /** 00316 * The attribute's handle in the ATT table. 00317 */ 00318 Handle_t _handle; 00319 00320 /** 00321 * Whether the length of the value can change throughout time. 00322 */ 00323 bool _hasVariableLen; 00324 00325 /** 00326 * Whether read is allowed or not. 00327 */ 00328 uint8_t _read_allowed:1; 00329 00330 /** 00331 * Security applied to the read operation. 00332 */ 00333 uint8_t _read_security: Security_t::size; 00334 00335 /** 00336 * Whether write is allowed or not. 00337 */ 00338 uint8_t _write_allowed:1; 00339 00340 /** 00341 * Security applied to the write operation. 00342 */ 00343 uint8_t _write_security: Security_t::size; 00344 00345 private: 00346 /* Disallow copy and assignment. */ 00347 GattAttribute(const GattAttribute &); 00348 GattAttribute& operator=(const GattAttribute &); 00349 }; 00350 00351 /** 00352 * @} 00353 * @} 00354 * @} 00355 */ 00356 00357 #endif /* ifndef MBED_GATT_ATTRIBUTE_H__ */
Generated on Tue Aug 9 2022 00:37:08 by
