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@1074:1fedc77d9add, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:42 2016 +0000
Revision:
1074:1fedc77d9add
Parent:
1073:edd717e9f799
Child:
1077:98d37e26903c
Synchronized with git rev cd809e2a

Author: Andres Amaya Garcia

Modify shutdown API and functionality



Modify the shutdown API to remove the static shutdown function in Gap,

SecurityManager, GattClient and GattServer. Futhermore, remove the static

references to Gap, SecurityManager, GattClient and GattServer objects inside

their own classes. The cleanup method is renamed to `reset()` and made public.

Finally, additional functionality is added to the reset implementation in

Gap.

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"
vcoubard 1063:187f9929cb60 24
rgrover1 716:11b41f651697 25 /**
vcoubard 1074:1fedc77d9add 26 * Structure for holding information about the service and the characteristics
vcoubard 1074:1fedc77d9add 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. */
vcoubard 1074:1fedc77d9add 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 1074:1fedc77d9add 55 * Structure for holding information about the service and the characteristics
vcoubard 1074:1fedc77d9add 56 * found during the discovery process.
vcoubard 1074:1fedc77d9add 57 */
vcoubard 1074:1fedc77d9add 58 struct DiscoveredDescriptor {
vcoubard 1074:1fedc77d9add 59 GattAttribute::Handle_t handle; /**< Descriptor Handle. */
vcoubard 1074:1fedc77d9add 60 UUID uuid; /**< Descriptor UUID. */
vcoubard 1074:1fedc77d9add 61 };
vcoubard 1074:1fedc77d9add 62
vcoubard 1074:1fedc77d9add 63 /**
vcoubard 1074:1fedc77d9add 64 * Callback type for when a characteristic descriptor is found during descriptor-
vcoubard 1074:1fedc77d9add 65 * discovery. The receiving function is passed in a pointer to a
vcoubard 1074:1fedc77d9add 66 * DiscoveredDescriptor object which will remain valid for the lifetime
vcoubard 1074:1fedc77d9add 67 * of the callback. Memory for this object is owned by the BLE_API eventing
vcoubard 1074:1fedc77d9add 68 * framework. The application can safely make a persistent shallow-copy of
vcoubard 1074:1fedc77d9add 69 * this object in order to work with the characteristic beyond the callback.
vcoubard 1074:1fedc77d9add 70 */
vcoubard 1074:1fedc77d9add 71 typedef void (*DescriptorCallback_t)(const DiscoveredDescriptor *);
vcoubard 1074:1fedc77d9add 72
vcoubard 1074:1fedc77d9add 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 *
vcoubard 1074:1fedc77d9add 91 * @param length
rgrover1 716:11b41f651697 92 * The amount of data being written.
vcoubard 1074:1fedc77d9add 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 1074:1fedc77d9add 113 * @param callback
vcoubard 1074:1fedc77d9add 114 * @param matchingUUID
vcoubard 1074:1fedc77d9add 115 * Filter for descriptors. Defaults to wildcard which will discover all descriptors.
rgrover1 716:11b41f651697 116 *
vcoubard 1074:1fedc77d9add 117 * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
rgrover1 716:11b41f651697 118 */
vcoubard 1074:1fedc77d9add 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 *
vcoubard 1074:1fedc77d9add 124 * @param length
rgrover1 716:11b41f651697 125 * The amount of data being written.
vcoubard 1074:1fedc77d9add 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 1056:ce2fb3d09929 140 /**
vcoubard 1074:1fedc77d9add 141 * Same as above but register the callback wich will be called once the data has been written
vcoubard 1052:b55e1ad3e1b3 142 */
vcoubard 1074:1fedc77d9add 143 ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onRead) const;
vcoubard 1052:b55e1ad3e1b3 144
vcoubard 1056:ce2fb3d09929 145 void setupLongUUID(UUID::LongUUIDBytes_t longUUID, UUID::ByteOrder_t order = UUID::MSB) {
vcoubard 1056:ce2fb3d09929 146 uuid.setupLong(longUUID, order);
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 1074:1fedc77d9add 158 const GattAttribute::Handle_t& getDeclHandle(void) const {
rgrover1 716:11b41f651697 159 return declHandle;
rgrover1 716:11b41f651697 160 }
vcoubard 1074:1fedc77d9add 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 1074:1fedc77d9add 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__*/