Lancaster University / BLE_API

Lancaster University's fork of the mbed BLE API. Lives on github, https://github.com/lancaster-university/BLE_API

Dependents:   microbit-dal microbit-dal microbit-ble-open microbit-dal ... more

Fork of BLE_API by Bluetooth Low Energy

ble/DiscoveredCharacteristic.h@993:4d62b7967c11, 2015-12-02 (annotated)

Committer:
rgrover1
Date:
Wed Dec 02 10:29:44 2015 +0000
Revision:
993:4d62b7967c11
Parent:
992:ca834f7ae8ed
Child:
1035:d8ba3cb5a39a
Synchronized with git rev 12e27cd4

Author: Rohit Grover

Release 2.1.3

=============



* Improvements to CallChainOfFunctionPointerswithContext:

  - add a `detach` function to be able to remove callbacks.

  - detach function now return true if a function has been detached and

    false otherwise.

  - add a function call operator.

  - use safe-bool idiom. see : http://www.artima.com/cppsource/safebool.html



* Add SafeBool class which allow to easily declare a safe bool operator in

  c++03.



* Improvements to FunctionPointerWithContext:

  - fix call propagation

  - use safe bool idiom



* Add config file for generating Doxygen.



* Setup for onRadioNotification callback does not call initRadioNotification

  anymore.



* GapAdvertisementData now handles replacement and appending of data fields

  based on type. Some fields can be replaced with new values, and others

  require the payload to be appended.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 716:11b41f651697 1 /* mbed Microcontroller Library
rgrover1 716:11b41f651697 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 716:11b41f651697 3 *
rgrover1 716:11b41f651697 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 716:11b41f651697 5 * you may not use this file except in compliance with the License.
rgrover1 716:11b41f651697 6 * You may obtain a copy of the License at
rgrover1 716:11b41f651697 7 *
rgrover1 716:11b41f651697 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 716:11b41f651697 9 *
rgrover1 716:11b41f651697 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 716:11b41f651697 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 716:11b41f651697 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 716:11b41f651697 13 * See the License for the specific language governing permissions and
rgrover1 716:11b41f651697 14 * limitations under the License.
rgrover1 716:11b41f651697 15 */
rgrover1 716:11b41f651697 16
rgrover1 716:11b41f651697 17 #ifndef __DISCOVERED_CHARACTERISTIC_H__
rgrover1 716:11b41f651697 18 #define __DISCOVERED_CHARACTERISTIC_H__
rgrover1 716:11b41f651697 19
rgrover1 716:11b41f651697 20 #include "UUID.h"
rgrover1 716:11b41f651697 21 #include "Gap.h"
rgrover1 716:11b41f651697 22 #include "GattAttribute.h"
rgrover1 716:11b41f651697 23 #include "GattClient.h"
rgrover1 716:11b41f651697 24
rgrover1 716:11b41f651697 25 /**
rgrover1 716:11b41f651697 26 * Structure for holding information about the service and the characteristics
rgrover1 716:11b41f651697 27 * found during the discovery process.
rgrover1 716:11b41f651697 28 */
rgrover1 716:11b41f651697 29 class DiscoveredCharacteristic {
rgrover1 716:11b41f651697 30 public:
rgrover1 716:11b41f651697 31 struct Properties_t {
rgrover1 993:4d62b7967c11 32 uint8_t _broadcast :1; /**< Broadcasting the value permitted. */
rgrover1 716:11b41f651697 33 uint8_t _read :1; /**< Reading the value permitted. */
rgrover1 716:11b41f651697 34 uint8_t _writeWoResp :1; /**< Writing the value with Write Command permitted. */
rgrover1 716:11b41f651697 35 uint8_t _write :1; /**< Writing the value with Write Request permitted. */
rgrover1 716:11b41f651697 36 uint8_t _notify :1; /**< Notications of the value permitted. */
rgrover1 716:11b41f651697 37 uint8_t _indicate :1; /**< Indications of the value permitted. */
rgrover1 716:11b41f651697 38 uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
rgrover1 716:11b41f651697 39
rgrover1 716:11b41f651697 40 public:
rgrover1 716:11b41f651697 41 bool broadcast(void) const {return _broadcast; }
rgrover1 716:11b41f651697 42 bool read(void) const {return _read; }
rgrover1 716:11b41f651697 43 bool writeWoResp(void) const {return _writeWoResp; }
rgrover1 716:11b41f651697 44 bool write(void) const {return _write; }
rgrover1 716:11b41f651697 45 bool notify(void) const {return _notify; }
rgrover1 716:11b41f651697 46 bool indicate(void) const {return _indicate; }
rgrover1 716:11b41f651697 47 bool authSignedWrite(void) const {return _authSignedWrite;}
rgrover1 716:11b41f651697 48
rgrover1 716:11b41f651697 49 private:
rgrover1 993:4d62b7967c11 50 operator uint8_t() const; /* Disallow implicit conversion into an integer. */
rgrover1 993:4d62b7967c11 51 operator unsigned() const; /* Disallow implicit conversion into an integer. */
rgrover1 716:11b41f651697 52 };
rgrover1 716:11b41f651697 53
rgrover1 716:11b41f651697 54 /**
rgrover1 716:11b41f651697 55 * Structure for holding information about the service and the characteristics
rgrover1 716:11b41f651697 56 * found during the discovery process.
rgrover1 716:11b41f651697 57 */
rgrover1 716:11b41f651697 58 struct DiscoveredDescriptor {
rgrover1 716:11b41f651697 59 GattAttribute::Handle_t handle; /**< Descriptor Handle. */
rgrover1 716:11b41f651697 60 UUID uuid; /**< Descriptor UUID. */
rgrover1 716:11b41f651697 61 };
rgrover1 716:11b41f651697 62
rgrover1 716:11b41f651697 63 /**
rgrover1 716:11b41f651697 64 * Callback type for when a characteristic descriptor is found during descriptor-
rgrover1 716:11b41f651697 65 * discovery. The receiving function is passed in a pointer to a
rgrover1 716:11b41f651697 66 * DiscoveredDescriptor object which will remain valid for the lifetime
rgrover1 716:11b41f651697 67 * of the callback. Memory for this object is owned by the BLE_API eventing
rgrover1 716:11b41f651697 68 * framework. The application can safely make a persistent shallow-copy of
rgrover1 716:11b41f651697 69 * this object in order to work with the characteristic beyond the callback.
rgrover1 716:11b41f651697 70 */
rgrover1 716:11b41f651697 71 typedef void (*DescriptorCallback_t)(const DiscoveredDescriptor *);
rgrover1 716:11b41f651697 72
rgrover1 716:11b41f651697 73 /**
rgrover1 716:11b41f651697 74 * Initiate (or continue) a read for the value attribute, optionally at a
rgrover1 993:4d62b7967c11 75 * given offset. If the characteristic or descriptor to be read is longer
rgrover1 716:11b41f651697 76 * than ATT_MTU - 1, this function must be called multiple times with
rgrover1 716:11b41f651697 77 * appropriate offset to read the complete value.
rgrover1 716:11b41f651697 78 *
rgrover1 993:4d62b7967c11 79 * @return BLE_ERROR_NONE if a read has been initiated, or
rgrover1 716:11b41f651697 80 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
rgrover1 993:4d62b7967c11 81 * BLE_STACK_BUSY if some client procedure is already in progress, or
rgrover1 716:11b41f651697 82 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 83 */
rgrover1 716:11b41f651697 84 ble_error_t read(uint16_t offset = 0) const;
rgrover1 716:11b41f651697 85
rgrover1 993:4d62b7967c11 86 ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const;
rgrover1 993:4d62b7967c11 87
rgrover1 716:11b41f651697 88 /**
rgrover1 716:11b41f651697 89 * Perform a write without response procedure.
rgrover1 716:11b41f651697 90 *
rgrover1 716:11b41f651697 91 * @param length
rgrover1 716:11b41f651697 92 * The amount of data being written.
rgrover1 716:11b41f651697 93 * @param value
rgrover1 716:11b41f651697 94 * The bytes being written.
rgrover1 716:11b41f651697 95 *
rgrover1 716:11b41f651697 96 * @note It is important to note that a write without response will generate
rgrover1 716:11b41f651697 97 * an onDataSent() callback when the packet has been transmitted. There
rgrover1 716:11b41f651697 98 * will be a BLE-stack specific limit to the number of pending
rgrover1 716:11b41f651697 99 * writeWoResponse operations; the user may want to use the onDataSent()
rgrover1 716:11b41f651697 100 * callback for flow-control.
rgrover1 716:11b41f651697 101 *
rgrover1 993:4d62b7967c11 102 * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
rgrover1 716:11b41f651697 103 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
rgrover1 993:4d62b7967c11 104 * BLE_STACK_BUSY if some client procedure is already in progress, or
rgrover1 716:11b41f651697 105 * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
rgrover1 716:11b41f651697 106 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 107 */
rgrover1 716:11b41f651697 108 ble_error_t writeWoResponse(uint16_t length, const uint8_t *value) const;
rgrover1 716:11b41f651697 109
rgrover1 716:11b41f651697 110 /**
rgrover1 716:11b41f651697 111 * Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic.
rgrover1 716:11b41f651697 112 *
rgrover1 716:11b41f651697 113 * @param callback
rgrover1 716:11b41f651697 114 * @param matchingUUID
rgrover1 993:4d62b7967c11 115 * Filter for descriptors. Defaults to wildcard which will discover all descriptors.
rgrover1 716:11b41f651697 116 *
rgrover1 716:11b41f651697 117 * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
rgrover1 716:11b41f651697 118 */
rgrover1 716:11b41f651697 119 ble_error_t discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) const;
rgrover1 716:11b41f651697 120
rgrover1 716:11b41f651697 121 /**
rgrover1 716:11b41f651697 122 * Perform a write procedure.
rgrover1 716:11b41f651697 123 *
rgrover1 716:11b41f651697 124 * @param length
rgrover1 716:11b41f651697 125 * The amount of data being written.
rgrover1 716:11b41f651697 126 * @param value
rgrover1 716:11b41f651697 127 * The bytes being written.
rgrover1 716:11b41f651697 128 *
rgrover1 716:11b41f651697 129 * @note It is important to note that a write will generate
rgrover1 716:11b41f651697 130 * an onDataWritten() callback when the peer acknowledges the request.
rgrover1 716:11b41f651697 131 *
rgrover1 993:4d62b7967c11 132 * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
rgrover1 716:11b41f651697 133 * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
rgrover1 993:4d62b7967c11 134 * BLE_STACK_BUSY if some client procedure is already in progress, or
rgrover1 716:11b41f651697 135 * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
rgrover1 716:11b41f651697 136 * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
rgrover1 716:11b41f651697 137 */
rgrover1 716:11b41f651697 138 ble_error_t write(uint16_t length, const uint8_t *value) const;
rgrover1 716:11b41f651697 139
rgrover1 993:4d62b7967c11 140 /**
rgrover1 993:4d62b7967c11 141 * Same as above but register the callback wich will be called once the data has been written
rgrover1 993:4d62b7967c11 142 */
rgrover1 993:4d62b7967c11 143 ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onRead) const;
rgrover1 993:4d62b7967c11 144
rgrover1 716:11b41f651697 145 void setupLongUUID(UUID::LongUUIDBytes_t longUUID) {
rgrover1 716:11b41f651697 146 uuid.setupLong(longUUID);
rgrover1 716:11b41f651697 147 }
rgrover1 716:11b41f651697 148
rgrover1 716:11b41f651697 149 public:
rgrover1 741:d6dceefb844e 150 const UUID& getUUID(void) const {
rgrover1 741:d6dceefb844e 151 return uuid;
rgrover1 716:11b41f651697 152 }
rgrover1 716:11b41f651697 153
rgrover1 716:11b41f651697 154 const Properties_t& getProperties(void) const {
rgrover1 716:11b41f651697 155 return props;
rgrover1 716:11b41f651697 156 }
rgrover1 716:11b41f651697 157
rgrover1 716:11b41f651697 158 const GattAttribute::Handle_t& getDeclHandle(void) const {
rgrover1 716:11b41f651697 159 return declHandle;
rgrover1 716:11b41f651697 160 }
rgrover1 716:11b41f651697 161 const GattAttribute::Handle_t& getValueHandle(void) const {
rgrover1 716:11b41f651697 162 return valueHandle;
rgrover1 716:11b41f651697 163 }
rgrover1 716:11b41f651697 164
rgrover1 716:11b41f651697 165 public:
rgrover1 716:11b41f651697 166 DiscoveredCharacteristic() : gattc(NULL),
rgrover1 716:11b41f651697 167 uuid(UUID::ShortUUIDBytes_t(0)),
rgrover1 716:11b41f651697 168 props(),
rgrover1 716:11b41f651697 169 declHandle(GattAttribute::INVALID_HANDLE),
rgrover1 716:11b41f651697 170 valueHandle(GattAttribute::INVALID_HANDLE) {
rgrover1 716:11b41f651697 171 /* empty */
rgrover1 716:11b41f651697 172 }
rgrover1 716:11b41f651697 173
rgrover1 716:11b41f651697 174 protected:
rgrover1 716:11b41f651697 175 GattClient *gattc;
rgrover1 716:11b41f651697 176
rgrover1 716:11b41f651697 177 protected:
rgrover1 716:11b41f651697 178 UUID uuid;
rgrover1 716:11b41f651697 179 Properties_t props;
rgrover1 716:11b41f651697 180 GattAttribute::Handle_t declHandle;
rgrover1 716:11b41f651697 181 GattAttribute::Handle_t valueHandle;
rgrover1 716:11b41f651697 182
rgrover1 716:11b41f651697 183 Gap::Handle_t connHandle;
rgrover1 716:11b41f651697 184 };
rgrover1 716:11b41f651697 185
rgrover1 716:11b41f651697 186 #endif /*__DISCOVERED_CHARACTERISTIC_H__*/