DiscoveredCharacteristic.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 __DISCOVERED_CHARACTERISTIC_H__
00018 #define __DISCOVERED_CHARACTERISTIC_H__
00019 
00020 #include "UUID.h"
00021 #include "Gap.h"
00022 #include "GattAttribute.h"
00023 #include "GattClient.h"
00024 
00025 /**
00026  * Structure for holding information about the service and the characteristics
00027  * found during the discovery process.
00028  */
00029 class DiscoveredCharacteristic {
00030 public:
00031     struct Properties_t {
00032         uint8_t _broadcast       :1; /**< Broadcasting of the value permitted. */
00033         uint8_t _read            :1; /**< Reading the value permitted. */
00034         uint8_t _writeWoResp     :1; /**< Writing the value with Write Command permitted. */
00035         uint8_t _write           :1; /**< Writing the value with Write Request permitted. */
00036         uint8_t _notify          :1; /**< Notications of the value permitted. */
00037         uint8_t _indicate        :1; /**< Indications of the value permitted. */
00038         uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
00039 
00040     public:
00041         bool broadcast(void)       const {return _broadcast;      }
00042         bool read(void)            const {return _read;           }
00043         bool writeWoResp(void)     const {return _writeWoResp;    }
00044         bool write(void)           const {return _write;          }
00045         bool notify(void)          const {return _notify;         }
00046         bool indicate(void)        const {return _indicate;       }
00047         bool authSignedWrite(void) const {return _authSignedWrite;}
00048 
00049     private:
00050         operator uint8_t()  const; /* disallow implicit conversion into an integer */
00051         operator unsigned() const; /* disallow implicit conversion into an integer */
00052     };
00053 
00054     /**
00055      * Structure for holding information about the service and the characteristics
00056      * found during the discovery process.
00057      */
00058     struct DiscoveredDescriptor {
00059         GattAttribute::Handle_t handle; /**< Descriptor Handle. */
00060         UUID                    uuid;   /**< Descriptor UUID. */
00061     };
00062 
00063     /**
00064      * Callback type for when a characteristic descriptor is found during descriptor-
00065      * discovery. The receiving function is passed in a pointer to a
00066      * DiscoveredDescriptor object which will remain valid for the lifetime
00067      * of the callback. Memory for this object is owned by the BLE_API eventing
00068      * framework. The application can safely make a persistent shallow-copy of
00069      * this object in order to work with the characteristic beyond the callback.
00070      */
00071     typedef void (*DescriptorCallback_t)(const DiscoveredDescriptor *);
00072 
00073     /**
00074      * Initiate (or continue) a read for the value attribute, optionally at a
00075      * given offset. If the Characteristic or Descriptor to be read is longer
00076      * than ATT_MTU - 1, this function must be called multiple times with
00077      * appropriate offset to read the complete value.
00078      *
00079      * @return BLE_ERROR_NONE if a read has been initiated, else
00080      *         BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
00081      *         BLE_STACK_BUSY if some client procedure already in progress, or
00082      *         BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
00083      */
00084     ble_error_t read(uint16_t offset = 0) const;
00085 
00086     /**
00087      * Perform a write without response procedure.
00088      *
00089      * @param  length
00090      *           The amount of data being written.
00091      * @param  value
00092      *           The bytes being written.
00093      *
00094      * @note   It is important to note that a write without response will generate
00095      *         an onDataSent() callback when the packet has been transmitted. There
00096      *         will be a BLE-stack specific limit to the number of pending
00097      *         writeWoResponse operations; the user may want to use the onDataSent()
00098      *         callback for flow-control.
00099      *
00100      * @retval BLE_ERROR_NONE Successfully started the Write procedure, else
00101      *         BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
00102      *         BLE_STACK_BUSY if some client procedure already in progress, or
00103      *         BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
00104      *         BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
00105      */
00106     ble_error_t writeWoResponse(uint16_t length, const uint8_t *value) const;
00107 
00108     /**
00109      * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic.
00110      *
00111      * @param  callback
00112      * @param  matchingUUID
00113      *           filter for descriptors. Defaults to wildcard which will discover all descriptors.
00114      *
00115      * @return  BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
00116      */
00117     ble_error_t discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) const;
00118 
00119     /**
00120      * Perform a write procedure.
00121      *
00122      * @param  length
00123      *           The amount of data being written.
00124      * @param  value
00125      *           The bytes being written.
00126      *
00127      * @note   It is important to note that a write will generate
00128      *         an onDataWritten() callback when the peer acknowledges the request.
00129      *
00130      * @retval BLE_ERROR_NONE Successfully started the Write procedure, else
00131      *         BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
00132      *         BLE_STACK_BUSY if some client procedure already in progress, or
00133      *         BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
00134      *         BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
00135      */
00136     ble_error_t write(uint16_t length, const uint8_t *value) const;
00137 
00138     void setupLongUUID(UUID::LongUUIDBytes_t longUUID) {
00139         uuid.setupLong(longUUID);
00140     }
00141 
00142 public:
00143     const UUID& getUUID(void) const {
00144         return uuid;
00145     }
00146 
00147     const Properties_t& getProperties(void) const {
00148         return props;
00149     }
00150 
00151     const GattAttribute::Handle_t& getDeclHandle(void) const {
00152         return declHandle;
00153     }
00154     const GattAttribute::Handle_t& getValueHandle(void) const {
00155         return valueHandle;
00156     }
00157 
00158 public:
00159     DiscoveredCharacteristic() : gattc(NULL),
00160                                  uuid(UUID::ShortUUIDBytes_t(0)),
00161                                  props(),
00162                                  declHandle(GattAttribute::INVALID_HANDLE),
00163                                  valueHandle(GattAttribute::INVALID_HANDLE) {
00164         /* empty */
00165     }
00166 
00167 protected:
00168     GattClient              *gattc;
00169 
00170 protected:
00171     UUID                     uuid;
00172     Properties_t             props;
00173     GattAttribute::Handle_t  declHandle;
00174     GattAttribute::Handle_t  valueHandle;
00175 
00176     Gap::Handle_t            connHandle;
00177 };
00178 
00179 #endif /*__DISCOVERED_CHARACTERISTIC_H__*/