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__ */