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 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, or
00080      *         BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
00081      *         BLE_STACK_BUSY if some client procedure is 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     ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t & onRead) const;
00087 
00088     /**
00089      * Perform a write without response procedure.
00090      *
00091      * @param  length
00092      *           The amount of data being written.
00093      * @param  value
00094      *           The bytes being written.
00095      *
00096      * @note   It is important to note that a write without response will generate
00097      *         an onDataSent() callback when the packet has been transmitted. There
00098      *         will be a BLE-stack specific limit to the number of pending
00099      *         writeWoResponse operations; the user may want to use the onDataSent()
00100      *         callback for flow-control.
00101      *
00102      * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
00103      *         BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
00104      *         BLE_STACK_BUSY if some client procedure is already in progress, or
00105      *         BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
00106      *         BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
00107      */
00108     ble_error_t writeWoResponse(uint16_t length, const uint8_t *value) const;
00109 
00110     /**
00111      * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic.
00112      *
00113      * @param  callback
00114      * @param  matchingUUID
00115      *           Filter for descriptors. Defaults to wildcard which will discover all descriptors.
00116      *
00117      * @return  BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
00118      */
00119     ble_error_t discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) const;
00120 
00121     /**
00122      * Perform a write procedure.
00123      *
00124      * @param  length
00125      *           The amount of data being written.
00126      * @param  value
00127      *           The bytes being written.
00128      *
00129      * @note   It is important to note that a write will generate
00130      *         an onDataWritten() callback when the peer acknowledges the request.
00131      *
00132      * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
00133      *         BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
00134      *         BLE_STACK_BUSY if some client procedure is already in progress, or
00135      *         BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
00136      *         BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
00137      */
00138     ble_error_t write(uint16_t length, const uint8_t *value) const;
00139 
00140     /**
00141      * Same as above but register the callback wich will be called once the data has been written
00142      */
00143     ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t & onRead) const;
00144 
00145     void setupLongUUID(UUID::LongUUIDBytes_t longUUID, UUID::ByteOrder_t order = UUID::MSB) {
00146         uuid.setupLong(longUUID, order);
00147     }
00148 
00149 public:
00150     const UUID& getUUID(void) const {
00151         return uuid;
00152     }
00153 
00154     const Properties_t& getProperties(void) const {
00155         return props;
00156     }
00157 
00158     const GattAttribute::Handle_t& getDeclHandle(void) const {
00159         return declHandle;
00160     }
00161     const GattAttribute::Handle_t& getValueHandle(void) const {
00162         return valueHandle;
00163     }
00164 
00165 public:
00166     DiscoveredCharacteristic() : gattc(NULL),
00167                                  uuid(UUID::ShortUUIDBytes_t(0)),
00168                                  props(),
00169                                  declHandle(GattAttribute::INVALID_HANDLE),
00170                                  valueHandle(GattAttribute::INVALID_HANDLE) {
00171         /* empty */
00172     }
00173 
00174 protected:
00175     GattClient              *gattc;
00176 
00177 protected:
00178     UUID                     uuid;
00179     Properties_t             props;
00180     GattAttribute::Handle_t  declHandle;
00181     GattAttribute::Handle_t  valueHandle;
00182 
00183     Gap::Handle_t            connHandle;
00184 };
00185 
00186 #endif /*__DISCOVERED_CHARACTERISTIC_H__*/