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@1053:ec4a5b9b254e, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:32 2016 +0000
Revision:
1053:ec4a5b9b254e
Parent:
1052:b55e1ad3e1b3
Child:
1056:ce2fb3d09929
Synchronized with git rev 13bf70b6

Author: Rohit Grover

Release 2.1.5

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



A minor release to separate the concept of minlen and len in

GattCharacteristic. Also contains some improvements to documentation.

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 {
vcoubard 1048:efb29faf12fc 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:
vcoubard 1048:efb29faf12fc 50 operator uint8_t() const; /* Disallow implicit conversion into an integer. */
vcoubard 1048:efb29faf12fc 51 operator unsigned() const; /* Disallow implicit conversion into an integer. */
rgrover1 716:11b41f651697 52 };
rgrover1 716:11b41f651697 53
rgrover1 716:11b41f651697 54 /**
vcoubard 1053:ec4a5b9b254e 55 * Structure for holding information about the service and the characteristics
vcoubard 1053:ec4a5b9b254e 56 * found during the discovery process.
vcoubard 1053:ec4a5b9b254e 57 */
vcoubard 1053:ec4a5b9b254e 58 struct DiscoveredDescriptor {
vcoubard 1053:ec4a5b9b254e 59 GattAttribute::Handle_t handle; /**< Descriptor Handle. */
vcoubard 1053:ec4a5b9b254e 60 UUID uuid; /**< Descriptor UUID. */
vcoubard 1053:ec4a5b9b254e 61 };
vcoubard 1053:ec4a5b9b254e 62
vcoubard 1053:ec4a5b9b254e 63 /**
vcoubard 1053:ec4a5b9b254e 64 * Callback type for when a characteristic descriptor is found during descriptor-
vcoubard 1053:ec4a5b9b254e 65 * discovery. The receiving function is passed in a pointer to a
vcoubard 1053:ec4a5b9b254e 66 * DiscoveredDescriptor object which will remain valid for the lifetime
vcoubard 1053:ec4a5b9b254e 67 * of the callback. Memory for this object is owned by the BLE_API eventing
vcoubard 1053:ec4a5b9b254e 68 * framework. The application can safely make a persistent shallow-copy of
vcoubard 1053:ec4a5b9b254e 69 * this object in order to work with the characteristic beyond the callback.
vcoubard 1053:ec4a5b9b254e 70 */
vcoubard 1053:ec4a5b9b254e 71 typedef void (*DescriptorCallback_t)(const DiscoveredDescriptor *);
vcoubard 1053:ec4a5b9b254e 72
vcoubard 1053:ec4a5b9b254e 73 /**
rgrover1 716:11b41f651697 74 * Initiate (or continue) a read for the value attribute, optionally at a
vcoubard 1048:efb29faf12fc 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 *
vcoubard 1048:efb29faf12fc 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
vcoubard 1048:efb29faf12fc 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
vcoubard 1052:b55e1ad3e1b3 86 ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const;
vcoubard 1052:b55e1ad3e1b3 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 *
vcoubard 1048:efb29faf12fc 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
vcoubard 1048:efb29faf12fc 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 *
vcoubard 1053:ec4a5b9b254e 113 * @param callback
vcoubard 1053:ec4a5b9b254e 114 * @param matchingUUID
vcoubard 1053:ec4a5b9b254e 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 */
vcoubard 1053:ec4a5b9b254e 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 *
vcoubard 1048:efb29faf12fc 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
vcoubard 1048:efb29faf12fc 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
vcoubard 1052:b55e1ad3e1b3 140 /**
vcoubard 1052:b55e1ad3e1b3 141 * Same as above but register the callback wich will be called once the data has been written
vcoubard 1052:b55e1ad3e1b3 142 */
vcoubard 1052:b55e1ad3e1b3 143 ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onRead) const;
vcoubard 1052:b55e1ad3e1b3 144
vcoubard 1042:21a86ac7f5b1 145 void setupLongUUID(UUID::LongUUIDBytes_t longUUID) {
vcoubard 1042:21a86ac7f5b1 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
vcoubard 1053:ec4a5b9b254e 158 const GattAttribute::Handle_t& getDeclHandle(void) const {
rgrover1 716:11b41f651697 159 return declHandle;
rgrover1 716:11b41f651697 160 }
vcoubard 1053:ec4a5b9b254e 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),
vcoubard 1053:ec4a5b9b254e 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__*/