Alex Cordonnier / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Fork of BLE_API by Bluetooth Low Energy

ble/DiscoveredCharacteristic.h@1131:692ddf04fc42, 2016-04-06 (annotated)

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