Jörg Küfen / BLE_API

fka mod

Fork of BLE_API by Bluetooth Low Energy

ble/Gap.h@1180:e11b058d005e, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:15:32 2016 +0100
Revision:
1180:e11b058d005e
Parent:
1179:4ab722f8dca0
Child:
1182:b70129080ddf
Synchronized with git rev a990f23a

Author: Andres Amaya Garcia

Add connectionCount and fix Gap state updates



Add a connectionCount member to Gap that keeps track of the total number of

open connections. Also, update the Gap state member when a connection is opened

to set advertising to false. Finally modify the processDisconnection member to

unset the connected state if connectionCount is 0.

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 __GAP_H__
vcoubard 1131:692ddf04fc42 18 #define __GAP_H__
vcoubard 1131:692ddf04fc42 19
vcoubard 1135:22aada733dbd 20 #include "ble/BLEProtocol.h"
vcoubard 1131:692ddf04fc42 21 #include "GapAdvertisingData.h"
vcoubard 1131:692ddf04fc42 22 #include "GapAdvertisingParams.h"
vcoubard 1131:692ddf04fc42 23 #include "GapScanningParams.h"
vcoubard 1131:692ddf04fc42 24 #include "GapEvents.h"
vcoubard 1131:692ddf04fc42 25 #include "CallChainOfFunctionPointersWithContext.h"
vcoubard 1131:692ddf04fc42 26 #include "FunctionPointerWithContext.h"
vcoubard 1135:22aada733dbd 27 #include "deprecate.h"
vcoubard 1131:692ddf04fc42 28
vcoubard 1131:692ddf04fc42 29 /* Forward declarations for classes that will only be used for pointers or references in the following. */
vcoubard 1131:692ddf04fc42 30 class GapAdvertisingParams;
vcoubard 1131:692ddf04fc42 31 class GapScanningParams;
vcoubard 1131:692ddf04fc42 32 class GapAdvertisingData;
vcoubard 1131:692ddf04fc42 33
vcoubard 1131:692ddf04fc42 34 class Gap {
vcoubard 1135:22aada733dbd 35 /*
vcoubard 1135:22aada733dbd 36 * DEPRECATION ALERT: all of the APIs in this `public` block are deprecated.
vcoubard 1135:22aada733dbd 37 * They have been relocated to the class BLEProtocol.
vcoubard 1135:22aada733dbd 38 */
vcoubard 1131:692ddf04fc42 39 public:
vcoubard 1135:22aada733dbd 40 /**
vcoubard 1135:22aada733dbd 41 * Address-type for BLEProtocol addresses.
vcoubard 1135:22aada733dbd 42 *
vcoubard 1179:4ab722f8dca0 43 * @note: deprecated. Use BLEProtocol::AddressType_t instead.
vcoubard 1135:22aada733dbd 44 */
vcoubard 1135:22aada733dbd 45 typedef BLEProtocol::AddressType_t AddressType_t;
vcoubard 1135:22aada733dbd 46
vcoubard 1135:22aada733dbd 47 /**
vcoubard 1135:22aada733dbd 48 * Address-type for BLEProtocol addresses.
vcoubard 1179:4ab722f8dca0 49 * @note: deprecated. Use BLEProtocol::AddressType_t instead.
vcoubard 1135:22aada733dbd 50 */
vcoubard 1135:22aada733dbd 51 typedef BLEProtocol::AddressType_t addr_type_t;
vcoubard 1135:22aada733dbd 52
vcoubard 1135:22aada733dbd 53 /**
vcoubard 1135:22aada733dbd 54 * Address-type for BLEProtocol addresses.
vcoubard 1179:4ab722f8dca0 55 * \deprecated: Use BLEProtocol::AddressType_t instead.
vcoubard 1135:22aada733dbd 56 *
vcoubard 1179:4ab722f8dca0 57 * DEPRECATION ALERT: The following constants have been left in their
vcoubard 1179:4ab722f8dca0 58 * deprecated state to transparenly support existing applications which may
vcoubard 1179:4ab722f8dca0 59 * have used Gap::ADDR_TYPE_*.
vcoubard 1135:22aada733dbd 60 */
vcoubard 1135:22aada733dbd 61 enum DeprecatedAddressType_t {
vcoubard 1135:22aada733dbd 62 ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC,
vcoubard 1135:22aada733dbd 63 ADDR_TYPE_RANDOM_STATIC = BLEProtocol::AddressType::RANDOM_STATIC,
vcoubard 1135:22aada733dbd 64 ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_RESOLVABLE,
vcoubard 1135:22aada733dbd 65 ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE
vcoubard 1131:692ddf04fc42 66 };
vcoubard 1131:692ddf04fc42 67
vcoubard 1179:4ab722f8dca0 68 static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN; /**< Length (in octets) of the BLE MAC address. */
vcoubard 1179:4ab722f8dca0 69 typedef BLEProtocol::AddressBytes_t Address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::AddressBytes_t instead. */
vcoubard 1179:4ab722f8dca0 70 typedef BLEProtocol::AddressBytes_t address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::AddressBytes_t instead. */
vcoubard 1131:692ddf04fc42 71
vcoubard 1135:22aada733dbd 72 public:
vcoubard 1131:692ddf04fc42 73 enum TimeoutSource_t {
vcoubard 1131:692ddf04fc42 74 TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */
vcoubard 1131:692ddf04fc42 75 TIMEOUT_SRC_SECURITY_REQUEST = 0x01, /**< Security request timeout. */
vcoubard 1131:692ddf04fc42 76 TIMEOUT_SRC_SCAN = 0x02, /**< Scanning timeout. */
vcoubard 1131:692ddf04fc42 77 TIMEOUT_SRC_CONN = 0x03, /**< Connection timeout. */
vcoubard 1131:692ddf04fc42 78 };
vcoubard 1131:692ddf04fc42 79
vcoubard 1131:692ddf04fc42 80 /**
vcoubard 1131:692ddf04fc42 81 * Enumeration for disconnection reasons. The values for these reasons are
vcoubard 1131:692ddf04fc42 82 * derived from Nordic's implementation, but the reasons are meant to be
vcoubard 1131:692ddf04fc42 83 * independent of the transport. If you are returned a reason that is not
vcoubard 1131:692ddf04fc42 84 * covered by this enumeration, please refer to the underlying
vcoubard 1131:692ddf04fc42 85 * transport library.
vcoubard 1131:692ddf04fc42 86 */
vcoubard 1131:692ddf04fc42 87 enum DisconnectionReason_t {
vcoubard 1131:692ddf04fc42 88 CONNECTION_TIMEOUT = 0x08,
vcoubard 1131:692ddf04fc42 89 REMOTE_USER_TERMINATED_CONNECTION = 0x13,
vcoubard 1131:692ddf04fc42 90 REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, /**< Remote device terminated connection due to low resources.*/
vcoubard 1131:692ddf04fc42 91 REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /**< Remote device terminated connection due to power off. */
vcoubard 1131:692ddf04fc42 92 LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
vcoubard 1131:692ddf04fc42 93 CONN_INTERVAL_UNACCEPTABLE = 0x3B,
vcoubard 1131:692ddf04fc42 94 };
vcoubard 1131:692ddf04fc42 95
vcoubard 1135:22aada733dbd 96 /**
vcoubard 1135:22aada733dbd 97 * Enumeration for whitelist advertising policy filter modes. The possible
vcoubard 1135:22aada733dbd 98 * filter modes were obtained from the Bluetooth Core Specification
vcoubard 1135:22aada733dbd 99 * 4.2 (Vol. 6), Part B, Section 4.3.2.
vcoubard 1135:22aada733dbd 100 *
vcoubard 1135:22aada733dbd 101 * @experimental
vcoubard 1135:22aada733dbd 102 */
vcoubard 1135:22aada733dbd 103 enum AdvertisingPolicyMode_t {
vcoubard 1135:22aada733dbd 104 ADV_POLICY_IGNORE_WHITELIST = 0,
vcoubard 1135:22aada733dbd 105 ADV_POLICY_FILTER_SCAN_REQS = 1,
vcoubard 1135:22aada733dbd 106 ADV_POLICY_FILTER_CONN_REQS = 2,
vcoubard 1135:22aada733dbd 107 ADV_POLICY_FILTER_ALL_REQS = 3,
vcoubard 1135:22aada733dbd 108 };
vcoubard 1135:22aada733dbd 109
vcoubard 1135:22aada733dbd 110 /**
vcoubard 1135:22aada733dbd 111 * Enumeration for whitelist scanning policy filter modes. The possible
vcoubard 1135:22aada733dbd 112 * filter modes were obtained from the Bluetooth Core Specification
vcoubard 1135:22aada733dbd 113 * 4.2 (Vol. 6), Part B, Section 4.3.3.
vcoubard 1135:22aada733dbd 114 *
vcoubard 1135:22aada733dbd 115 * @experimental
vcoubard 1135:22aada733dbd 116 */
vcoubard 1135:22aada733dbd 117 enum ScanningPolicyMode_t {
vcoubard 1135:22aada733dbd 118 SCAN_POLICY_IGNORE_WHITELIST = 0,
vcoubard 1135:22aada733dbd 119 SCAN_POLICY_FILTER_ALL_ADV = 1,
vcoubard 1135:22aada733dbd 120 };
vcoubard 1135:22aada733dbd 121
vcoubard 1135:22aada733dbd 122 /**
vcoubard 1135:22aada733dbd 123 * Enumeration for the whitelist initiator policy fiter modes. The possible
vcoubard 1135:22aada733dbd 124 * filter modes were obtained from the Bluetooth Core Specification
vcoubard 1135:22aada733dbd 125 * 4.2 (vol. 6), Part B, Section 4.4.4.
vcoubard 1135:22aada733dbd 126 *
vcoubard 1135:22aada733dbd 127 * @experimental
vcoubard 1135:22aada733dbd 128 */
vcoubard 1135:22aada733dbd 129 enum InitiatorPolicyMode_t {
vcoubard 1135:22aada733dbd 130 INIT_POLICY_IGNORE_WHITELIST = 0,
vcoubard 1135:22aada733dbd 131 INIT_POLICY_FILTER_ALL_ADV = 1,
vcoubard 1135:22aada733dbd 132 };
vcoubard 1135:22aada733dbd 133
vcoubard 1135:22aada733dbd 134 /**
vcoubard 1135:22aada733dbd 135 * Representation of a Bluetooth Low Enery Whitelist containing addresses.
vcoubard 1135:22aada733dbd 136 *
vcoubard 1135:22aada733dbd 137 * @experimental
vcoubard 1135:22aada733dbd 138 */
vcoubard 1135:22aada733dbd 139 struct Whitelist_t {
vcoubard 1179:4ab722f8dca0 140 BLEProtocol::Address_t *addresses;
vcoubard 1179:4ab722f8dca0 141 uint8_t size;
vcoubard 1179:4ab722f8dca0 142 uint8_t capacity;
vcoubard 1135:22aada733dbd 143 };
vcoubard 1135:22aada733dbd 144
vcoubard 1135:22aada733dbd 145
vcoubard 1179:4ab722f8dca0 146 /* Describes the current state of the device (more than one bit can be set). */
vcoubard 1131:692ddf04fc42 147 struct GapState_t {
vcoubard 1131:692ddf04fc42 148 unsigned advertising : 1; /**< Peripheral is currently advertising. */
vcoubard 1131:692ddf04fc42 149 unsigned connected : 1; /**< Peripheral is connected to a central. */
vcoubard 1131:692ddf04fc42 150 };
vcoubard 1131:692ddf04fc42 151
vcoubard 1179:4ab722f8dca0 152 typedef uint16_t Handle_t; /* Type for connection handle. */
vcoubard 1131:692ddf04fc42 153
vcoubard 1131:692ddf04fc42 154 typedef struct {
vcoubard 1179:4ab722f8dca0 155 uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1179:4ab722f8dca0 156 uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1179:4ab722f8dca0 157 uint16_t slaveLatency; /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1179:4ab722f8dca0 158 uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1131:692ddf04fc42 159 } ConnectionParams_t;
vcoubard 1131:692ddf04fc42 160
vcoubard 1131:692ddf04fc42 161 enum Role_t {
vcoubard 1131:692ddf04fc42 162 PERIPHERAL = 0x1, /**< Peripheral Role. */
vcoubard 1131:692ddf04fc42 163 CENTRAL = 0x2, /**< Central Role. */
vcoubard 1131:692ddf04fc42 164 };
vcoubard 1131:692ddf04fc42 165
vcoubard 1131:692ddf04fc42 166 struct AdvertisementCallbackParams_t {
vcoubard 1179:4ab722f8dca0 167 BLEProtocol::AddressBytes_t peerAddr;
vcoubard 1179:4ab722f8dca0 168 int8_t rssi;
vcoubard 1179:4ab722f8dca0 169 bool isScanResponse;
vcoubard 1179:4ab722f8dca0 170 GapAdvertisingParams::AdvertisingType_t type;
vcoubard 1179:4ab722f8dca0 171 uint8_t advertisingDataLen;
vcoubard 1179:4ab722f8dca0 172 const uint8_t *advertisingData;
vcoubard 1131:692ddf04fc42 173 };
vcoubard 1131:692ddf04fc42 174 typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> AdvertisementReportCallback_t;
vcoubard 1131:692ddf04fc42 175
vcoubard 1131:692ddf04fc42 176 struct ConnectionCallbackParams_t {
vcoubard 1179:4ab722f8dca0 177 Handle_t handle;
vcoubard 1179:4ab722f8dca0 178 Role_t role;
vcoubard 1179:4ab722f8dca0 179 BLEProtocol::AddressType_t peerAddrType;
vcoubard 1179:4ab722f8dca0 180 BLEProtocol::AddressBytes_t peerAddr;
vcoubard 1179:4ab722f8dca0 181 BLEProtocol::AddressType_t ownAddrType;
vcoubard 1179:4ab722f8dca0 182 BLEProtocol::AddressBytes_t ownAddr;
vcoubard 1179:4ab722f8dca0 183 const ConnectionParams_t *connectionParams;
vcoubard 1131:692ddf04fc42 184
vcoubard 1135:22aada733dbd 185 ConnectionCallbackParams_t(Handle_t handleIn,
vcoubard 1135:22aada733dbd 186 Role_t roleIn,
vcoubard 1135:22aada733dbd 187 BLEProtocol::AddressType_t peerAddrTypeIn,
vcoubard 1135:22aada733dbd 188 const uint8_t *peerAddrIn,
vcoubard 1135:22aada733dbd 189 BLEProtocol::AddressType_t ownAddrTypeIn,
vcoubard 1135:22aada733dbd 190 const uint8_t *ownAddrIn,
vcoubard 1135:22aada733dbd 191 const ConnectionParams_t *connectionParamsIn) :
vcoubard 1131:692ddf04fc42 192 handle(handleIn),
vcoubard 1131:692ddf04fc42 193 role(roleIn),
vcoubard 1131:692ddf04fc42 194 peerAddrType(peerAddrTypeIn),
vcoubard 1131:692ddf04fc42 195 peerAddr(),
vcoubard 1131:692ddf04fc42 196 ownAddrType(ownAddrTypeIn),
vcoubard 1131:692ddf04fc42 197 ownAddr(),
vcoubard 1131:692ddf04fc42 198 connectionParams(connectionParamsIn) {
vcoubard 1131:692ddf04fc42 199 memcpy(peerAddr, peerAddrIn, ADDR_LEN);
vcoubard 1131:692ddf04fc42 200 memcpy(ownAddr, ownAddrIn, ADDR_LEN);
vcoubard 1131:692ddf04fc42 201 }
vcoubard 1131:692ddf04fc42 202 };
vcoubard 1131:692ddf04fc42 203
vcoubard 1131:692ddf04fc42 204 struct DisconnectionCallbackParams_t {
vcoubard 1179:4ab722f8dca0 205 Handle_t handle;
vcoubard 1179:4ab722f8dca0 206 DisconnectionReason_t reason;
vcoubard 1131:692ddf04fc42 207
vcoubard 1131:692ddf04fc42 208 DisconnectionCallbackParams_t(Handle_t handleIn,
vcoubard 1131:692ddf04fc42 209 DisconnectionReason_t reasonIn) :
vcoubard 1131:692ddf04fc42 210 handle(handleIn),
vcoubard 1131:692ddf04fc42 211 reason(reasonIn)
vcoubard 1131:692ddf04fc42 212 {}
vcoubard 1131:692ddf04fc42 213 };
vcoubard 1131:692ddf04fc42 214
vcoubard 1131:692ddf04fc42 215 static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
vcoubard 1131:692ddf04fc42 216 static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
vcoubard 1131:692ddf04fc42 217 return (durationInMillis * 1000) / UNIT_1_25_MS;
vcoubard 1131:692ddf04fc42 218 }
vcoubard 1131:692ddf04fc42 219
vcoubard 1131:692ddf04fc42 220 typedef FunctionPointerWithContext<TimeoutSource_t> TimeoutEventCallback_t;
vcoubard 1131:692ddf04fc42 221 typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> TimeoutEventCallbackChain_t;
vcoubard 1131:692ddf04fc42 222
vcoubard 1131:692ddf04fc42 223 typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallback_t;
vcoubard 1131:692ddf04fc42 224 typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t;
vcoubard 1131:692ddf04fc42 225
vcoubard 1131:692ddf04fc42 226 typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
vcoubard 1132:6362b7c2fdff 227 typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t;
vcoubard 1131:692ddf04fc42 228
vcoubard 1131:692ddf04fc42 229 typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
vcoubard 1131:692ddf04fc42 230
vcoubard 1135:22aada733dbd 231 typedef FunctionPointerWithContext<const Gap *> GapShutdownCallback_t;
vcoubard 1135:22aada733dbd 232 typedef CallChainOfFunctionPointersWithContext<const Gap *> GapShutdownCallbackChain_t;
vcoubard 1135:22aada733dbd 233
vcoubard 1131:692ddf04fc42 234 /*
vcoubard 1131:692ddf04fc42 235 * The following functions are meant to be overridden in the platform-specific sub-class.
vcoubard 1131:692ddf04fc42 236 */
vcoubard 1131:692ddf04fc42 237 public:
vcoubard 1131:692ddf04fc42 238 /**
vcoubard 1131:692ddf04fc42 239 * Set the BTLE MAC address and type. Please note that the address format is
vcoubard 1135:22aada733dbd 240 * least significant byte first (LSB). Please refer to BLEProtocol::AddressBytes_t.
vcoubard 1131:692ddf04fc42 241 *
vcoubard 1131:692ddf04fc42 242 * @return BLE_ERROR_NONE on success.
vcoubard 1131:692ddf04fc42 243 */
vcoubard 1135:22aada733dbd 244 virtual ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
vcoubard 1131:692ddf04fc42 245 /* avoid compiler warnings about unused variables */
vcoubard 1131:692ddf04fc42 246 (void)type;
vcoubard 1131:692ddf04fc42 247 (void)address;
vcoubard 1131:692ddf04fc42 248
vcoubard 1131:692ddf04fc42 249 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 250 }
vcoubard 1131:692ddf04fc42 251
vcoubard 1131:692ddf04fc42 252 /**
vcoubard 1131:692ddf04fc42 253 * Fetch the BTLE MAC address and type.
vcoubard 1131:692ddf04fc42 254 *
vcoubard 1131:692ddf04fc42 255 * @return BLE_ERROR_NONE on success.
vcoubard 1131:692ddf04fc42 256 */
vcoubard 1135:22aada733dbd 257 virtual ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
vcoubard 1131:692ddf04fc42 258 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 259 (void)typeP;
vcoubard 1131:692ddf04fc42 260 (void)address;
vcoubard 1131:692ddf04fc42 261
vcoubard 1131:692ddf04fc42 262 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 263 }
vcoubard 1131:692ddf04fc42 264
vcoubard 1131:692ddf04fc42 265 /**
vcoubard 1134:d540a48f650d 266 * @return Minimum Advertising interval in milliseconds for connectable
vcoubard 1179:4ab722f8dca0 267 * undirected and connectable directed event types.
vcoubard 1131:692ddf04fc42 268 */
vcoubard 1131:692ddf04fc42 269 virtual uint16_t getMinAdvertisingInterval(void) const {
vcoubard 1131:692ddf04fc42 270 return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 271 }
vcoubard 1131:692ddf04fc42 272
vcoubard 1131:692ddf04fc42 273 /**
vcoubard 1134:d540a48f650d 274 * @return Minimum Advertising interval in milliseconds for scannable
vcoubard 1179:4ab722f8dca0 275 * undirected and non-connectable undirected event types.
vcoubard 1131:692ddf04fc42 276 */
vcoubard 1131:692ddf04fc42 277 virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const {
vcoubard 1131:692ddf04fc42 278 return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 279 }
vcoubard 1131:692ddf04fc42 280
vcoubard 1131:692ddf04fc42 281 /**
vcoubard 1131:692ddf04fc42 282 * @return Maximum Advertising interval in milliseconds.
vcoubard 1131:692ddf04fc42 283 */
vcoubard 1131:692ddf04fc42 284 virtual uint16_t getMaxAdvertisingInterval(void) const {
vcoubard 1131:692ddf04fc42 285 return 0xFFFF; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 286 }
vcoubard 1131:692ddf04fc42 287
vcoubard 1131:692ddf04fc42 288 virtual ble_error_t stopAdvertising(void) {
vcoubard 1131:692ddf04fc42 289 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 290 }
vcoubard 1131:692ddf04fc42 291
vcoubard 1131:692ddf04fc42 292 /**
vcoubard 1131:692ddf04fc42 293 * Stop scanning. The current scanning parameters remain in effect.
vcoubard 1131:692ddf04fc42 294 *
vcoubard 1131:692ddf04fc42 295 * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
vcoubard 1131:692ddf04fc42 296 */
vcoubard 1131:692ddf04fc42 297 virtual ble_error_t stopScan() {
vcoubard 1131:692ddf04fc42 298 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 299 }
vcoubard 1131:692ddf04fc42 300
vcoubard 1131:692ddf04fc42 301 /**
vcoubard 1131:692ddf04fc42 302 * Create a connection (GAP Link Establishment).
vcoubard 1131:692ddf04fc42 303 *
vcoubard 1179:4ab722f8dca0 304 * @param peerAddr
vcoubard 1179:4ab722f8dca0 305 * 48-bit address, LSB format.
vcoubard 1179:4ab722f8dca0 306 * @param peerAddrType
vcoubard 1179:4ab722f8dca0 307 * Address type of the peer.
vcoubard 1179:4ab722f8dca0 308 * @param connectionParams
vcoubard 1179:4ab722f8dca0 309 * Connection parameters.
vcoubard 1179:4ab722f8dca0 310 * @param scanParams
vcoubard 1179:4ab722f8dca0 311 * Paramters to be used while scanning for the peer.
vcoubard 1131:692ddf04fc42 312 * @return BLE_ERROR_NONE if connection establishment procedure is started
vcoubard 1179:4ab722f8dca0 313 * successfully. The connectionCallChain (if set) will be invoked upon
vcoubard 1179:4ab722f8dca0 314 * a connection event.
vcoubard 1131:692ddf04fc42 315 */
vcoubard 1135:22aada733dbd 316 virtual ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
vcoubard 1135:22aada733dbd 317 BLEProtocol::AddressType_t peerAddrType,
vcoubard 1135:22aada733dbd 318 const ConnectionParams_t *connectionParams,
vcoubard 1135:22aada733dbd 319 const GapScanningParams *scanParams) {
vcoubard 1131:692ddf04fc42 320 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 321 (void)peerAddr;
vcoubard 1131:692ddf04fc42 322 (void)peerAddrType;
vcoubard 1131:692ddf04fc42 323 (void)connectionParams;
vcoubard 1131:692ddf04fc42 324 (void)scanParams;
vcoubard 1131:692ddf04fc42 325
vcoubard 1131:692ddf04fc42 326 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 327 }
vcoubard 1131:692ddf04fc42 328
vcoubard 1131:692ddf04fc42 329 /**
vcoubard 1135:22aada733dbd 330 * Create a connection (GAP Link Establishment).
vcoubard 1135:22aada733dbd 331 *
vcoubard 1179:4ab722f8dca0 332 * \deprecated: This funtion overloads Gap::connect(const BLEProtocol::Address_t peerAddr,
vcoubard 1179:4ab722f8dca0 333 BLEProtocol::AddressType_t peerAddrType,
vcoubard 1179:4ab722f8dca0 334 const ConnectionParams_t *connectionParams,
vcoubard 1179:4ab722f8dca0 335 const GapScanningParams *scanParams)
vcoubard 1179:4ab722f8dca0 336 * to maintain backward compatibility for change from Gap::AddressType_t to BLEProtocol::AddressType_t
vcoubard 1135:22aada733dbd 337 */
vcoubard 1135:22aada733dbd 338 ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
vcoubard 1135:22aada733dbd 339 DeprecatedAddressType_t peerAddrType,
vcoubard 1135:22aada733dbd 340 const ConnectionParams_t *connectionParams,
vcoubard 1135:22aada733dbd 341 const GapScanningParams *scanParams)
vcoubard 1135:22aada733dbd 342 __deprecated_message("Gap::DeprecatedAddressType_t is deprecated, use BLEProtocol::AddressType_t instead") {
vcoubard 1135:22aada733dbd 343 return connect(peerAddr, (BLEProtocol::AddressType_t) peerAddrType, connectionParams, scanParams);
vcoubard 1135:22aada733dbd 344 }
vcoubard 1135:22aada733dbd 345
vcoubard 1135:22aada733dbd 346 /**
vcoubard 1131:692ddf04fc42 347 * This call initiates the disconnection procedure, and its completion will
vcoubard 1131:692ddf04fc42 348 * be communicated to the application with an invocation of the
vcoubard 1131:692ddf04fc42 349 * disconnectionCallback.
vcoubard 1131:692ddf04fc42 350 *
vcoubard 1179:4ab722f8dca0 351 * @param reason
vcoubard 1179:4ab722f8dca0 352 * The reason for disconnection; to be sent back to the peer.
vcoubard 1131:692ddf04fc42 353 */
vcoubard 1131:692ddf04fc42 354 virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
vcoubard 1131:692ddf04fc42 355 /* avoid compiler warnings about unused variables */
vcoubard 1131:692ddf04fc42 356 (void)connectionHandle;
vcoubard 1131:692ddf04fc42 357 (void)reason;
vcoubard 1131:692ddf04fc42 358
vcoubard 1131:692ddf04fc42 359 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 360 }
vcoubard 1131:692ddf04fc42 361
vcoubard 1131:692ddf04fc42 362 /**
vcoubard 1131:692ddf04fc42 363 * This call initiates the disconnection procedure, and its completion will
vcoubard 1131:692ddf04fc42 364 * be communicated to the application with an invocation of the
vcoubard 1131:692ddf04fc42 365 * disconnectionCallback.
vcoubard 1131:692ddf04fc42 366 *
vcoubard 1179:4ab722f8dca0 367 * @param reason
vcoubard 1179:4ab722f8dca0 368 * The reason for disconnection; to be sent back to the peer.
vcoubard 1131:692ddf04fc42 369 *
vcoubard 1179:4ab722f8dca0 370 * @note: This version of disconnect() doesn't take a connection handle. It
vcoubard 1179:4ab722f8dca0 371 * works reliably only for stacks that are limited to a single
vcoubard 1179:4ab722f8dca0 372 * connection. This API should be considered *deprecated* in favour of the
vcoubard 1179:4ab722f8dca0 373 * alternative, which takes a connection handle. It will be dropped in the future.
vcoubard 1131:692ddf04fc42 374 */
vcoubard 1131:692ddf04fc42 375 virtual ble_error_t disconnect(DisconnectionReason_t reason) {
vcoubard 1131:692ddf04fc42 376 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 377 (void)reason;
vcoubard 1131:692ddf04fc42 378
vcoubard 1131:692ddf04fc42 379 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 380 }
vcoubard 1131:692ddf04fc42 381
vcoubard 1131:692ddf04fc42 382 /**
vcoubard 1131:692ddf04fc42 383 * Get the GAP peripheral preferred connection parameters. These are the
vcoubard 1131:692ddf04fc42 384 * defaults that the peripheral would like to have in a connection. The
vcoubard 1131:692ddf04fc42 385 * choice of the connection parameters is eventually up to the central.
vcoubard 1131:692ddf04fc42 386 *
vcoubard 1131:692ddf04fc42 387 * @param[out] params
vcoubard 1131:692ddf04fc42 388 * The structure where the parameters will be stored. Memory
vcoubard 1131:692ddf04fc42 389 * for this is owned by the caller.
vcoubard 1131:692ddf04fc42 390 *
vcoubard 1131:692ddf04fc42 391 * @return BLE_ERROR_NONE if the parameters were successfully filled into
vcoubard 1179:4ab722f8dca0 392 * the given structure pointed to by params.
vcoubard 1131:692ddf04fc42 393 */
vcoubard 1131:692ddf04fc42 394 virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
vcoubard 1131:692ddf04fc42 395 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 396 (void)params;
vcoubard 1131:692ddf04fc42 397
vcoubard 1131:692ddf04fc42 398 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 399 }
vcoubard 1131:692ddf04fc42 400
vcoubard 1131:692ddf04fc42 401 /**
vcoubard 1131:692ddf04fc42 402 * Set the GAP peripheral preferred connection parameters. These are the
vcoubard 1131:692ddf04fc42 403 * defaults that the peripheral would like to have in a connection. The
vcoubard 1131:692ddf04fc42 404 * choice of the connection parameters is eventually up to the central.
vcoubard 1131:692ddf04fc42 405 *
vcoubard 1131:692ddf04fc42 406 * @param[in] params
vcoubard 1131:692ddf04fc42 407 * The structure containing the desired parameters.
vcoubard 1131:692ddf04fc42 408 */
vcoubard 1131:692ddf04fc42 409 virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
vcoubard 1131:692ddf04fc42 410 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 411 (void)params;
vcoubard 1131:692ddf04fc42 412
vcoubard 1131:692ddf04fc42 413 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 414 }
vcoubard 1131:692ddf04fc42 415
vcoubard 1131:692ddf04fc42 416 /**
vcoubard 1179:4ab722f8dca0 417 * Update connection parameters.
vcoubard 1179:4ab722f8dca0 418 * In the central role this will initiate a Link Layer connection parameter update procedure.
vcoubard 1179:4ab722f8dca0 419 * In the peripheral role, this will send the corresponding L2CAP request and wait for
vcoubard 1179:4ab722f8dca0 420 * the central to perform the procedure.
vcoubard 1131:692ddf04fc42 421 *
vcoubard 1131:692ddf04fc42 422 * @param[in] handle
vcoubard 1131:692ddf04fc42 423 * Connection Handle.
vcoubard 1131:692ddf04fc42 424 * @param[in] params
vcoubard 1131:692ddf04fc42 425 * Pointer to desired connection parameters. If NULL is provided on a peripheral role,
vcoubard 1131:692ddf04fc42 426 * the parameters in the PPCP characteristic of the GAP service will be used instead.
vcoubard 1131:692ddf04fc42 427 */
vcoubard 1131:692ddf04fc42 428 virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) {
vcoubard 1131:692ddf04fc42 429 /* avoid compiler warnings about unused variables */
vcoubard 1131:692ddf04fc42 430 (void)handle;
vcoubard 1131:692ddf04fc42 431 (void)params;
vcoubard 1131:692ddf04fc42 432
vcoubard 1131:692ddf04fc42 433 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 434 }
vcoubard 1131:692ddf04fc42 435
vcoubard 1131:692ddf04fc42 436 /**
vcoubard 1131:692ddf04fc42 437 * Set the device name characteristic in the GAP service.
vcoubard 1131:692ddf04fc42 438 * @param[in] deviceName
vcoubard 1131:692ddf04fc42 439 * The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
vcoubard 1131:692ddf04fc42 440 */
vcoubard 1131:692ddf04fc42 441 virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
vcoubard 1131:692ddf04fc42 442 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 443 (void)deviceName;
vcoubard 1131:692ddf04fc42 444
vcoubard 1131:692ddf04fc42 445 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 446 }
vcoubard 1131:692ddf04fc42 447
vcoubard 1131:692ddf04fc42 448 /**
vcoubard 1131:692ddf04fc42 449 * Get the value of the device name characteristic in the GAP service.
vcoubard 1131:692ddf04fc42 450 * @param[out] deviceName
vcoubard 1131:692ddf04fc42 451 * Pointer to an empty buffer where the UTF-8 *non NULL-
vcoubard 1131:692ddf04fc42 452 * terminated* string will be placed. Set this
vcoubard 1131:692ddf04fc42 453 * value to NULL in order to obtain the deviceName-length
vcoubard 1131:692ddf04fc42 454 * from the 'length' parameter.
vcoubard 1131:692ddf04fc42 455 *
vcoubard 1179:4ab722f8dca0 456 * @param[in/out] lengthP
vcoubard 1131:692ddf04fc42 457 * (on input) Length of the buffer pointed to by deviceName;
vcoubard 1131:692ddf04fc42 458 * (on output) the complete device name length (without the
vcoubard 1131:692ddf04fc42 459 * null terminator).
vcoubard 1131:692ddf04fc42 460 *
vcoubard 1131:692ddf04fc42 461 * @note If the device name is longer than the size of the supplied buffer,
vcoubard 1179:4ab722f8dca0 462 * length will return the complete device name length, and not the
vcoubard 1179:4ab722f8dca0 463 * number of bytes actually returned in deviceName. The application may
vcoubard 1179:4ab722f8dca0 464 * use this information to retry with a suitable buffer size.
vcoubard 1131:692ddf04fc42 465 */
vcoubard 1131:692ddf04fc42 466 virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
vcoubard 1131:692ddf04fc42 467 /* avoid compiler warnings about unused variables */
vcoubard 1131:692ddf04fc42 468 (void)deviceName;
vcoubard 1131:692ddf04fc42 469 (void)lengthP;
vcoubard 1131:692ddf04fc42 470
vcoubard 1131:692ddf04fc42 471 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 472 }
vcoubard 1131:692ddf04fc42 473
vcoubard 1131:692ddf04fc42 474 /**
vcoubard 1131:692ddf04fc42 475 * Set the appearance characteristic in the GAP service.
vcoubard 1131:692ddf04fc42 476 * @param[in] appearance
vcoubard 1131:692ddf04fc42 477 * The new value for the device-appearance.
vcoubard 1131:692ddf04fc42 478 */
vcoubard 1131:692ddf04fc42 479 virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
vcoubard 1131:692ddf04fc42 480 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 481 (void)appearance;
vcoubard 1131:692ddf04fc42 482
vcoubard 1131:692ddf04fc42 483 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 484 }
vcoubard 1131:692ddf04fc42 485
vcoubard 1131:692ddf04fc42 486 /**
vcoubard 1131:692ddf04fc42 487 * Get the appearance characteristic in the GAP service.
vcoubard 1131:692ddf04fc42 488 * @param[out] appearance
vcoubard 1179:4ab722f8dca0 489 * The new value for the device-appearance.
vcoubard 1131:692ddf04fc42 490 */
vcoubard 1131:692ddf04fc42 491 virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
vcoubard 1131:692ddf04fc42 492 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 493 (void)appearanceP;
vcoubard 1131:692ddf04fc42 494
vcoubard 1131:692ddf04fc42 495 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 496 }
vcoubard 1131:692ddf04fc42 497
vcoubard 1131:692ddf04fc42 498 /**
vcoubard 1131:692ddf04fc42 499 * Set the radio's transmit power.
vcoubard 1179:4ab722f8dca0 500 * @param[in] txPower Radio transmit power in dBm.
vcoubard 1131:692ddf04fc42 501 */
vcoubard 1131:692ddf04fc42 502 virtual ble_error_t setTxPower(int8_t txPower) {
vcoubard 1131:692ddf04fc42 503 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 504 (void)txPower;
vcoubard 1131:692ddf04fc42 505
vcoubard 1131:692ddf04fc42 506 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 507 }
vcoubard 1131:692ddf04fc42 508
vcoubard 1131:692ddf04fc42 509 /**
vcoubard 1131:692ddf04fc42 510 * Query the underlying stack for permitted arguments for setTxPower().
vcoubard 1131:692ddf04fc42 511 *
vcoubard 1131:692ddf04fc42 512 * @param[out] valueArrayPP
vcoubard 1131:692ddf04fc42 513 * Out parameter to receive the immutable array of Tx values.
vcoubard 1131:692ddf04fc42 514 * @param[out] countP
vcoubard 1131:692ddf04fc42 515 * Out parameter to receive the array's size.
vcoubard 1131:692ddf04fc42 516 */
vcoubard 1131:692ddf04fc42 517 virtual void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
vcoubard 1131:692ddf04fc42 518 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 519 (void)valueArrayPP;
vcoubard 1131:692ddf04fc42 520 (void)countP;
vcoubard 1131:692ddf04fc42 521
vcoubard 1131:692ddf04fc42 522 *countP = 0; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 523 }
vcoubard 1131:692ddf04fc42 524
vcoubard 1135:22aada733dbd 525 /**
vcoubard 1135:22aada733dbd 526 * @return Maximum size of the whitelist.
vcoubard 1135:22aada733dbd 527 *
vcoubard 1135:22aada733dbd 528 * @experimental
vcoubard 1135:22aada733dbd 529 */
vcoubard 1135:22aada733dbd 530 virtual uint8_t getMaxWhitelistSize(void) const
vcoubard 1135:22aada733dbd 531 {
vcoubard 1135:22aada733dbd 532 return 0;
vcoubard 1135:22aada733dbd 533 }
vcoubard 1135:22aada733dbd 534
vcoubard 1135:22aada733dbd 535 /**
vcoubard 1135:22aada733dbd 536 * Get the internal whitelist to be used by the Link Layer when scanning,
vcoubard 1135:22aada733dbd 537 * advertising or initiating a connection depending on the filter policies.
vcoubard 1135:22aada733dbd 538 *
vcoubard 1179:4ab722f8dca0 539 * @param[in/out] whitelist
vcoubard 1135:22aada733dbd 540 * (on input) whitelist.capacity contains the maximum number
vcoubard 1135:22aada733dbd 541 * of addresses to be returned.
vcoubard 1135:22aada733dbd 542 * (on output) The populated whitelist with copies of the
vcoubard 1135:22aada733dbd 543 * addresses in the implementation's whitelist.
vcoubard 1135:22aada733dbd 544 *
vcoubard 1135:22aada733dbd 545 * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
vcoubard 1135:22aada733dbd 546 * copied into the supplied reference.
vcoubard 1135:22aada733dbd 547 *
vcoubard 1135:22aada733dbd 548 * @experimental
vcoubard 1135:22aada733dbd 549 */
vcoubard 1135:22aada733dbd 550 virtual ble_error_t getWhitelist(Whitelist_t &whitelist) const
vcoubard 1135:22aada733dbd 551 {
vcoubard 1135:22aada733dbd 552 (void) whitelist;
vcoubard 1135:22aada733dbd 553 return BLE_ERROR_NOT_IMPLEMENTED;
vcoubard 1135:22aada733dbd 554 }
vcoubard 1135:22aada733dbd 555
vcoubard 1135:22aada733dbd 556 /**
vcoubard 1135:22aada733dbd 557 * Set the internal whitelist to be used by the Link Layer when scanning,
vcoubard 1135:22aada733dbd 558 * advertising or initiating a connection depending on the filter policies.
vcoubard 1135:22aada733dbd 559 *
vcoubard 1135:22aada733dbd 560 * @param[in] whitelist
vcoubard 1135:22aada733dbd 561 * A reference to a whitelist containing the addresses to
vcoubard 1135:22aada733dbd 562 * be added to the internal whitelist.
vcoubard 1135:22aada733dbd 563 *
vcoubard 1135:22aada733dbd 564 * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
vcoubard 1135:22aada733dbd 565 * populated with the addresses in the given whitelist.
vcoubard 1135:22aada733dbd 566 *
vcoubard 1135:22aada733dbd 567 * @note The whitelist must not contain addresses of type @ref
vcoubard 1135:22aada733dbd 568 * BLEProtocol::AddressType_t::RANDOM_PRIVATE_NON_RESOLVABLE, this
vcoubard 1135:22aada733dbd 569 * this will result in a @ref BLE_ERROR_INVALID_PARAM since the
vcoubard 1135:22aada733dbd 570 * remote peer might change its private address at any time and it
vcoubard 1135:22aada733dbd 571 * is not possible to resolve it.
vcoubard 1135:22aada733dbd 572 * @note If the input whitelist is larger than @ref getMaxWhitelistSize()
vcoubard 1135:22aada733dbd 573 * the @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned.
vcoubard 1135:22aada733dbd 574 *
vcoubard 1135:22aada733dbd 575 * @experimental
vcoubard 1135:22aada733dbd 576 */
vcoubard 1135:22aada733dbd 577 virtual ble_error_t setWhitelist(const Whitelist_t &whitelist)
vcoubard 1135:22aada733dbd 578 {
vcoubard 1135:22aada733dbd 579 (void) whitelist;
vcoubard 1135:22aada733dbd 580 return BLE_ERROR_NOT_IMPLEMENTED;
vcoubard 1135:22aada733dbd 581 }
vcoubard 1135:22aada733dbd 582
vcoubard 1135:22aada733dbd 583 /**
vcoubard 1135:22aada733dbd 584 * Set the advertising policy filter mode to be used in the next call
vcoubard 1135:22aada733dbd 585 * to startAdvertising().
vcoubard 1135:22aada733dbd 586 *
vcoubard 1135:22aada733dbd 587 * @param[in] mode
vcoubard 1135:22aada733dbd 588 * The new advertising policy filter mode.
vcoubard 1135:22aada733dbd 589 *
vcoubard 1135:22aada733dbd 590 * @return BLE_ERROR_NONE if the specified policy filter mode was set
vcoubard 1135:22aada733dbd 591 * successfully.
vcoubard 1135:22aada733dbd 592 *
vcoubard 1135:22aada733dbd 593 * @experimental
vcoubard 1135:22aada733dbd 594 */
vcoubard 1135:22aada733dbd 595 virtual ble_error_t setAdvertisingPolicyMode(AdvertisingPolicyMode_t mode)
vcoubard 1135:22aada733dbd 596 {
vcoubard 1135:22aada733dbd 597 (void) mode;
vcoubard 1135:22aada733dbd 598 return BLE_ERROR_NOT_IMPLEMENTED;
vcoubard 1135:22aada733dbd 599 }
vcoubard 1135:22aada733dbd 600
vcoubard 1135:22aada733dbd 601 /**
vcoubard 1135:22aada733dbd 602 * Set the scan policy filter mode to be used in the next call
vcoubard 1135:22aada733dbd 603 * to startScan().
vcoubard 1135:22aada733dbd 604 *
vcoubard 1135:22aada733dbd 605 * @param[in] mode
vcoubard 1135:22aada733dbd 606 * The new scan policy filter mode.
vcoubard 1135:22aada733dbd 607 *
vcoubard 1135:22aada733dbd 608 * @return BLE_ERROR_NONE if the specified policy filter mode was set
vcoubard 1135:22aada733dbd 609 * successfully.
vcoubard 1135:22aada733dbd 610 *
vcoubard 1135:22aada733dbd 611 * @experimental
vcoubard 1135:22aada733dbd 612 */
vcoubard 1135:22aada733dbd 613 virtual ble_error_t setScanningPolicyMode(ScanningPolicyMode_t mode)
vcoubard 1135:22aada733dbd 614 {
vcoubard 1135:22aada733dbd 615 (void) mode;
vcoubard 1135:22aada733dbd 616 return BLE_ERROR_NOT_IMPLEMENTED;
vcoubard 1135:22aada733dbd 617 }
vcoubard 1135:22aada733dbd 618
vcoubard 1135:22aada733dbd 619 /**
vcoubard 1135:22aada733dbd 620 * Set the initiator policy filter mode to be used.
vcoubard 1135:22aada733dbd 621 *
vcoubard 1135:22aada733dbd 622 * @param[in] mode
vcoubard 1135:22aada733dbd 623 * The new initiator policy filter mode.
vcoubard 1135:22aada733dbd 624 *
vcoubard 1135:22aada733dbd 625 * @return BLE_ERROR_NONE if the specified policy filter mode was set
vcoubard 1135:22aada733dbd 626 * successfully.
vcoubard 1135:22aada733dbd 627 *
vcoubard 1135:22aada733dbd 628 * @experimental
vcoubard 1135:22aada733dbd 629 */
vcoubard 1135:22aada733dbd 630 virtual ble_error_t setInitiatorPolicyMode(InitiatorPolicyMode_t mode)
vcoubard 1135:22aada733dbd 631 {
vcoubard 1135:22aada733dbd 632 (void) mode;
vcoubard 1135:22aada733dbd 633 return BLE_ERROR_NOT_IMPLEMENTED;
vcoubard 1135:22aada733dbd 634 }
vcoubard 1135:22aada733dbd 635
vcoubard 1135:22aada733dbd 636 /**
vcoubard 1135:22aada733dbd 637 * Get the advertising policy filter mode that will be used in the next
vcoubard 1135:22aada733dbd 638 * call to startAdvertising().
vcoubard 1135:22aada733dbd 639 *
vcoubard 1135:22aada733dbd 640 * @return The set advertising policy filter mode.
vcoubard 1135:22aada733dbd 641 *
vcoubard 1135:22aada733dbd 642 * @experimental
vcoubard 1135:22aada733dbd 643 */
vcoubard 1135:22aada733dbd 644 virtual AdvertisingPolicyMode_t getAdvertisingPolicyMode(void) const
vcoubard 1135:22aada733dbd 645 {
vcoubard 1135:22aada733dbd 646 return ADV_POLICY_IGNORE_WHITELIST;
vcoubard 1135:22aada733dbd 647 }
vcoubard 1135:22aada733dbd 648
vcoubard 1135:22aada733dbd 649 /**
vcoubard 1135:22aada733dbd 650 * Get the scan policy filter mode that will be used in the next
vcoubard 1135:22aada733dbd 651 * call to startScan().
vcoubard 1135:22aada733dbd 652 *
vcoubard 1135:22aada733dbd 653 * @return The set scan policy filter mode.
vcoubard 1135:22aada733dbd 654 *
vcoubard 1135:22aada733dbd 655 * @experimental
vcoubard 1135:22aada733dbd 656 */
vcoubard 1135:22aada733dbd 657 virtual ScanningPolicyMode_t getScanningPolicyMode(void) const
vcoubard 1135:22aada733dbd 658 {
vcoubard 1135:22aada733dbd 659 return SCAN_POLICY_IGNORE_WHITELIST;
vcoubard 1135:22aada733dbd 660 }
vcoubard 1135:22aada733dbd 661
vcoubard 1135:22aada733dbd 662 /**
vcoubard 1135:22aada733dbd 663 * Get the initiator policy filter mode that will be used.
vcoubard 1135:22aada733dbd 664 *
vcoubard 1135:22aada733dbd 665 * @return The set scan policy filter mode.
vcoubard 1135:22aada733dbd 666 *
vcoubard 1135:22aada733dbd 667 * @experimental
vcoubard 1135:22aada733dbd 668 */
vcoubard 1135:22aada733dbd 669 virtual InitiatorPolicyMode_t getInitiatorPolicyMode(void) const
vcoubard 1135:22aada733dbd 670 {
vcoubard 1135:22aada733dbd 671 return INIT_POLICY_IGNORE_WHITELIST;
vcoubard 1135:22aada733dbd 672 }
vcoubard 1135:22aada733dbd 673
vcoubard 1135:22aada733dbd 674
vcoubard 1131:692ddf04fc42 675 protected:
vcoubard 1131:692ddf04fc42 676 /* Override the following in the underlying adaptation layer to provide the functionality of scanning. */
vcoubard 1131:692ddf04fc42 677 virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams) {
vcoubard 1131:692ddf04fc42 678 (void)scanningParams;
vcoubard 1131:692ddf04fc42 679 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 680 }
vcoubard 1131:692ddf04fc42 681
vcoubard 1131:692ddf04fc42 682 /*
vcoubard 1131:692ddf04fc42 683 * APIs with non-virtual implementations.
vcoubard 1131:692ddf04fc42 684 */
vcoubard 1131:692ddf04fc42 685 public:
vcoubard 1131:692ddf04fc42 686 /**
vcoubard 1179:4ab722f8dca0 687 * Returns the current GAP state of the device using a bitmask that
vcoubard 1131:692ddf04fc42 688 * describes whether the device is advertising or connected.
vcoubard 1131:692ddf04fc42 689 */
vcoubard 1131:692ddf04fc42 690 GapState_t getState(void) const {
vcoubard 1131:692ddf04fc42 691 return state;
vcoubard 1131:692ddf04fc42 692 }
vcoubard 1131:692ddf04fc42 693
vcoubard 1131:692ddf04fc42 694 /**
vcoubard 1131:692ddf04fc42 695 * Set the GAP advertising mode to use for this device.
vcoubard 1131:692ddf04fc42 696 */
vcoubard 1131:692ddf04fc42 697 void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType) {
vcoubard 1131:692ddf04fc42 698 _advParams.setAdvertisingType(advType);
vcoubard 1131:692ddf04fc42 699 }
vcoubard 1131:692ddf04fc42 700
vcoubard 1131:692ddf04fc42 701 /**
vcoubard 1131:692ddf04fc42 702 * @param[in] interval
vcoubard 1131:692ddf04fc42 703 * Advertising interval in units of milliseconds. Advertising
vcoubard 1131:692ddf04fc42 704 * is disabled if interval is 0. If interval is smaller than
vcoubard 1131:692ddf04fc42 705 * the minimum supported value, then the minimum supported
vcoubard 1131:692ddf04fc42 706 * value is used instead. This minimum value can be discovered
vcoubard 1131:692ddf04fc42 707 * using getMinAdvertisingInterval().
vcoubard 1131:692ddf04fc42 708 *
vcoubard 1131:692ddf04fc42 709 * This field must be set to 0 if connectionMode is equal
vcoubard 1131:692ddf04fc42 710 * to ADV_CONNECTABLE_DIRECTED.
vcoubard 1131:692ddf04fc42 711 *
vcoubard 1179:4ab722f8dca0 712 * @note: Decreasing this value will allow central devices to detect a
vcoubard 1179:4ab722f8dca0 713 * peripheral faster, at the expense of more power being used by the radio
vcoubard 1179:4ab722f8dca0 714 * due to the higher data transmit rate.
vcoubard 1131:692ddf04fc42 715 *
vcoubard 1179:4ab722f8dca0 716 * @Note: [WARNING] This API previously used 0.625ms as the unit for its
vcoubard 1179:4ab722f8dca0 717 * 'interval' argument. That required an explicit conversion from
vcoubard 1179:4ab722f8dca0 718 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
vcoubard 1179:4ab722f8dca0 719 * no longer required as the new units are milliseconds. Any application
vcoubard 1179:4ab722f8dca0 720 * code depending on the old semantics needs to be updated accordingly.
vcoubard 1131:692ddf04fc42 721 */
vcoubard 1131:692ddf04fc42 722 void setAdvertisingInterval(uint16_t interval) {
vcoubard 1131:692ddf04fc42 723 if (interval == 0) {
vcoubard 1131:692ddf04fc42 724 stopAdvertising();
vcoubard 1131:692ddf04fc42 725 } else if (interval < getMinAdvertisingInterval()) {
vcoubard 1131:692ddf04fc42 726 interval = getMinAdvertisingInterval();
vcoubard 1131:692ddf04fc42 727 }
vcoubard 1131:692ddf04fc42 728 _advParams.setInterval(interval);
vcoubard 1131:692ddf04fc42 729 }
vcoubard 1131:692ddf04fc42 730
vcoubard 1131:692ddf04fc42 731 /**
vcoubard 1131:692ddf04fc42 732 * @param[in] timeout
vcoubard 1131:692ddf04fc42 733 * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
vcoubard 1131:692ddf04fc42 734 * and 16383). Use 0 to disable the advertising timeout.
vcoubard 1131:692ddf04fc42 735 */
vcoubard 1131:692ddf04fc42 736 void setAdvertisingTimeout(uint16_t timeout) {
vcoubard 1131:692ddf04fc42 737 _advParams.setTimeout(timeout);
vcoubard 1131:692ddf04fc42 738 }
vcoubard 1131:692ddf04fc42 739
vcoubard 1131:692ddf04fc42 740 /**
vcoubard 1131:692ddf04fc42 741 * Start advertising.
vcoubard 1131:692ddf04fc42 742 */
vcoubard 1131:692ddf04fc42 743 ble_error_t startAdvertising(void) {
vcoubard 1131:692ddf04fc42 744 setAdvertisingData(); /* Update the underlying stack. */
vcoubard 1131:692ddf04fc42 745 return startAdvertising(_advParams);
vcoubard 1131:692ddf04fc42 746 }
vcoubard 1131:692ddf04fc42 747
vcoubard 1131:692ddf04fc42 748 /**
vcoubard 1131:692ddf04fc42 749 * Reset any advertising payload prepared from prior calls to
vcoubard 1131:692ddf04fc42 750 * accumulateAdvertisingPayload(). This automatically propagates the re-
vcoubard 1131:692ddf04fc42 751 * initialized advertising payload to the underlying stack.
vcoubard 1131:692ddf04fc42 752 */
vcoubard 1131:692ddf04fc42 753 void clearAdvertisingPayload(void) {
vcoubard 1131:692ddf04fc42 754 _advPayload.clear();
vcoubard 1131:692ddf04fc42 755 setAdvertisingData();
vcoubard 1131:692ddf04fc42 756 }
vcoubard 1131:692ddf04fc42 757
vcoubard 1131:692ddf04fc42 758 /**
vcoubard 1131:692ddf04fc42 759 * Accumulate an AD structure in the advertising payload. Please note that
vcoubard 1131:692ddf04fc42 760 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1131:692ddf04fc42 761 * as an additional 31 bytes if the advertising payload is too
vcoubard 1131:692ddf04fc42 762 * small.
vcoubard 1131:692ddf04fc42 763 *
vcoubard 1131:692ddf04fc42 764 * @param[in] flags
vcoubard 1131:692ddf04fc42 765 * The flags to be added. Please refer to
vcoubard 1131:692ddf04fc42 766 * GapAdvertisingData::Flags for valid flags. Multiple
vcoubard 1131:692ddf04fc42 767 * flags may be specified in combination.
vcoubard 1131:692ddf04fc42 768 */
vcoubard 1131:692ddf04fc42 769 ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
vcoubard 1131:692ddf04fc42 770 ble_error_t rc;
vcoubard 1131:692ddf04fc42 771 if ((rc = _advPayload.addFlags(flags)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 772 return rc;
vcoubard 1131:692ddf04fc42 773 }
vcoubard 1131:692ddf04fc42 774
vcoubard 1131:692ddf04fc42 775 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 776 }
vcoubard 1131:692ddf04fc42 777
vcoubard 1131:692ddf04fc42 778 /**
vcoubard 1131:692ddf04fc42 779 * Accumulate an AD structure in the advertising payload. Please note that
vcoubard 1131:692ddf04fc42 780 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1131:692ddf04fc42 781 * as an additional 31 bytes if the advertising payload is too
vcoubard 1131:692ddf04fc42 782 * small.
vcoubard 1131:692ddf04fc42 783 *
vcoubard 1179:4ab722f8dca0 784 * @param app
vcoubard 1179:4ab722f8dca0 785 * The appearance of the peripheral.
vcoubard 1131:692ddf04fc42 786 */
vcoubard 1131:692ddf04fc42 787 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
vcoubard 1131:692ddf04fc42 788 setAppearance(app);
vcoubard 1131:692ddf04fc42 789
vcoubard 1131:692ddf04fc42 790 ble_error_t rc;
vcoubard 1131:692ddf04fc42 791 if ((rc = _advPayload.addAppearance(app)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 792 return rc;
vcoubard 1131:692ddf04fc42 793 }
vcoubard 1131:692ddf04fc42 794
vcoubard 1131:692ddf04fc42 795 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 796 }
vcoubard 1131:692ddf04fc42 797
vcoubard 1131:692ddf04fc42 798 /**
vcoubard 1131:692ddf04fc42 799 * Accumulate an AD structure in the advertising payload. Please note that
vcoubard 1131:692ddf04fc42 800 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1131:692ddf04fc42 801 * as an additional 31 bytes if the advertising payload is too
vcoubard 1131:692ddf04fc42 802 * small.
vcoubard 1131:692ddf04fc42 803 *
vcoubard 1179:4ab722f8dca0 804 * @param power
vcoubard 1179:4ab722f8dca0 805 * The max transmit power to be used by the controller (in dBm).
vcoubard 1131:692ddf04fc42 806 */
vcoubard 1131:692ddf04fc42 807 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
vcoubard 1131:692ddf04fc42 808 ble_error_t rc;
vcoubard 1131:692ddf04fc42 809 if ((rc = _advPayload.addTxPower(power)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 810 return rc;
vcoubard 1131:692ddf04fc42 811 }
vcoubard 1131:692ddf04fc42 812
vcoubard 1131:692ddf04fc42 813 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 814 }
vcoubard 1131:692ddf04fc42 815
vcoubard 1131:692ddf04fc42 816 /**
vcoubard 1131:692ddf04fc42 817 * Accumulate a variable length byte-stream as an AD structure in the
vcoubard 1131:692ddf04fc42 818 * advertising payload. Please note that the payload is limited to 31 bytes.
vcoubard 1131:692ddf04fc42 819 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
vcoubard 1131:692ddf04fc42 820 * advertising payload is too small.
vcoubard 1131:692ddf04fc42 821 *
vcoubard 1179:4ab722f8dca0 822 * @param type The type describing the variable length data.
vcoubard 1179:4ab722f8dca0 823 * @param data Data bytes.
vcoubard 1179:4ab722f8dca0 824 * @param len Length of data.
vcoubard 1135:22aada733dbd 825 *
vcoubard 1135:22aada733dbd 826 * @return BLE_ERROR_NONE if the advertisement payload was updated based on
vcoubard 1135:22aada733dbd 827 * matching AD type; otherwise, an appropriate error.
vcoubard 1135:22aada733dbd 828 *
vcoubard 1135:22aada733dbd 829 * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS,
vcoubard 1135:22aada733dbd 830 * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS,
vcoubard 1135:22aada733dbd 831 * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS,
vcoubard 1135:22aada733dbd 832 * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the
vcoubard 1135:22aada733dbd 833 * supplied value is appended to the values previously added to the
vcoubard 1135:22aada733dbd 834 * payload.
vcoubard 1131:692ddf04fc42 835 */
vcoubard 1131:692ddf04fc42 836 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard 1131:692ddf04fc42 837 if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
vcoubard 1131:692ddf04fc42 838 setDeviceName(data);
vcoubard 1131:692ddf04fc42 839 }
vcoubard 1131:692ddf04fc42 840
vcoubard 1131:692ddf04fc42 841 ble_error_t rc;
vcoubard 1131:692ddf04fc42 842 if ((rc = _advPayload.addData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 843 return rc;
vcoubard 1131:692ddf04fc42 844 }
vcoubard 1131:692ddf04fc42 845
vcoubard 1131:692ddf04fc42 846 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 847 }
vcoubard 1131:692ddf04fc42 848
vcoubard 1131:692ddf04fc42 849 /**
vcoubard 1131:692ddf04fc42 850 * Update a particular ADV field in the advertising payload (based on
vcoubard 1135:22aada733dbd 851 * matching type).
vcoubard 1131:692ddf04fc42 852 *
vcoubard 1179:4ab722f8dca0 853 * @param[in] type The ADV type field describing the variable length data.
vcoubard 1179:4ab722f8dca0 854 * @param[in] data Data bytes.
vcoubard 1179:4ab722f8dca0 855 * @param[in] len Length of data.
vcoubard 1131:692ddf04fc42 856 *
vcoubard 1179:4ab722f8dca0 857 * @note: If advertisements are enabled, then the update will take effect immediately.
vcoubard 1131:692ddf04fc42 858 *
vcoubard 1131:692ddf04fc42 859 * @return BLE_ERROR_NONE if the advertisement payload was updated based on
vcoubard 1135:22aada733dbd 860 * matching AD type; otherwise, an appropriate error.
vcoubard 1131:692ddf04fc42 861 */
vcoubard 1131:692ddf04fc42 862 ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard 1131:692ddf04fc42 863 if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
vcoubard 1131:692ddf04fc42 864 setDeviceName(data);
vcoubard 1131:692ddf04fc42 865 }
vcoubard 1131:692ddf04fc42 866
vcoubard 1131:692ddf04fc42 867 ble_error_t rc;
vcoubard 1131:692ddf04fc42 868 if ((rc = _advPayload.updateData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 869 return rc;
vcoubard 1131:692ddf04fc42 870 }
vcoubard 1131:692ddf04fc42 871
vcoubard 1131:692ddf04fc42 872 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 873 }
vcoubard 1131:692ddf04fc42 874
vcoubard 1131:692ddf04fc42 875 /**
vcoubard 1131:692ddf04fc42 876 * Set up a particular, user-constructed advertisement payload for the
vcoubard 1131:692ddf04fc42 877 * underlying stack. It would be uncommon for this API to be used directly;
vcoubard 1179:4ab722f8dca0 878 * there are other APIs to build an advertisement payload (see above).
vcoubard 1131:692ddf04fc42 879 */
vcoubard 1131:692ddf04fc42 880 ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) {
vcoubard 1131:692ddf04fc42 881 _advPayload = payload;
vcoubard 1131:692ddf04fc42 882 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 883 }
vcoubard 1131:692ddf04fc42 884
vcoubard 1131:692ddf04fc42 885 /**
vcoubard 1179:4ab722f8dca0 886 * @return Read back advertising data. Useful for storing and
vcoubard 1179:4ab722f8dca0 887 * restoring payload.
vcoubard 1131:692ddf04fc42 888 */
vcoubard 1131:692ddf04fc42 889 const GapAdvertisingData &getAdvertisingPayload(void) const {
vcoubard 1131:692ddf04fc42 890 return _advPayload;
vcoubard 1131:692ddf04fc42 891 }
vcoubard 1131:692ddf04fc42 892
vcoubard 1131:692ddf04fc42 893 /**
vcoubard 1131:692ddf04fc42 894 * Accumulate a variable length byte-stream as an AD structure in the
vcoubard 1131:692ddf04fc42 895 * scanResponse payload.
vcoubard 1131:692ddf04fc42 896 *
vcoubard 1179:4ab722f8dca0 897 * @param[in] type The type describing the variable length data.
vcoubard 1179:4ab722f8dca0 898 * @param[in] data Data bytes.
vcoubard 1179:4ab722f8dca0 899 * @param[in] len Length of data.
vcoubard 1131:692ddf04fc42 900 */
vcoubard 1131:692ddf04fc42 901 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard 1131:692ddf04fc42 902 ble_error_t rc;
vcoubard 1131:692ddf04fc42 903 if ((rc = _scanResponse.addData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 904 return rc;
vcoubard 1131:692ddf04fc42 905 }
vcoubard 1131:692ddf04fc42 906
vcoubard 1131:692ddf04fc42 907 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 908 }
vcoubard 1131:692ddf04fc42 909
vcoubard 1131:692ddf04fc42 910 /**
vcoubard 1131:692ddf04fc42 911 * Reset any scan response prepared from prior calls to
vcoubard 1179:4ab722f8dca0 912 * accumulateScanResponse().
vcoubard 1131:692ddf04fc42 913 *
vcoubard 1179:4ab722f8dca0 914 * Note: This should be followed by a call to setAdvertisingPayload() or
vcoubard 1179:4ab722f8dca0 915 * startAdvertising() before the update takes effect.
vcoubard 1131:692ddf04fc42 916 */
vcoubard 1131:692ddf04fc42 917 void clearScanResponse(void) {
vcoubard 1131:692ddf04fc42 918 _scanResponse.clear();
vcoubard 1131:692ddf04fc42 919 setAdvertisingData();
vcoubard 1131:692ddf04fc42 920 }
vcoubard 1131:692ddf04fc42 921
vcoubard 1131:692ddf04fc42 922 /**
vcoubard 1131:692ddf04fc42 923 * Set up parameters for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 924 * @param[in] interval
vcoubard 1131:692ddf04fc42 925 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 926 * @param[in] window
vcoubard 1131:692ddf04fc42 927 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 928 * @param[in] timeout
vcoubard 1131:692ddf04fc42 929 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
vcoubard 1131:692ddf04fc42 930 * @param[in] activeScanning
vcoubard 1131:692ddf04fc42 931 * Set to True if active-scanning is required. This is used to fetch the
vcoubard 1131:692ddf04fc42 932 * scan response from a peer if possible.
vcoubard 1131:692ddf04fc42 933 *
vcoubard 1179:4ab722f8dca0 934 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1179:4ab722f8dca0 935 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1179:4ab722f8dca0 936 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1179:4ab722f8dca0 937 * to have the interval and window set to the same value. In this case,
vcoubard 1179:4ab722f8dca0 938 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1179:4ab722f8dca0 939 * interval.
vcoubard 1131:692ddf04fc42 940 *
vcoubard 1179:4ab722f8dca0 941 * Once the scanning parameters have been configured, scanning can be
vcoubard 1179:4ab722f8dca0 942 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 943 *
vcoubard 1179:4ab722f8dca0 944 * @Note: The scan interval and window are recommendations to the BLE stack.
vcoubard 1131:692ddf04fc42 945 */
vcoubard 1131:692ddf04fc42 946 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
vcoubard 1131:692ddf04fc42 947 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
vcoubard 1131:692ddf04fc42 948 uint16_t timeout = 0,
vcoubard 1131:692ddf04fc42 949 bool activeScanning = false) {
vcoubard 1131:692ddf04fc42 950 ble_error_t rc;
vcoubard 1131:692ddf04fc42 951 if (((rc = _scanningParams.setInterval(interval)) == BLE_ERROR_NONE) &&
vcoubard 1131:692ddf04fc42 952 ((rc = _scanningParams.setWindow(window)) == BLE_ERROR_NONE) &&
vcoubard 1131:692ddf04fc42 953 ((rc = _scanningParams.setTimeout(timeout)) == BLE_ERROR_NONE)) {
vcoubard 1131:692ddf04fc42 954 _scanningParams.setActiveScanning(activeScanning);
vcoubard 1131:692ddf04fc42 955 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 956 }
vcoubard 1131:692ddf04fc42 957
vcoubard 1131:692ddf04fc42 958 return rc;
vcoubard 1131:692ddf04fc42 959 }
vcoubard 1131:692ddf04fc42 960
vcoubard 1131:692ddf04fc42 961 /**
vcoubard 1131:692ddf04fc42 962 * Set up the scanInterval parameter for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 963 * @param[in] interval
vcoubard 1131:692ddf04fc42 964 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 965 *
vcoubard 1179:4ab722f8dca0 966 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1179:4ab722f8dca0 967 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1179:4ab722f8dca0 968 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1179:4ab722f8dca0 969 * to have the interval and window set to the same value. In this case,
vcoubard 1179:4ab722f8dca0 970 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1179:4ab722f8dca0 971 * interval.
vcoubard 1131:692ddf04fc42 972 *
vcoubard 1179:4ab722f8dca0 973 * Once the scanning parameters have been configured, scanning can be
vcoubard 1179:4ab722f8dca0 974 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 975 */
vcoubard 1131:692ddf04fc42 976 ble_error_t setScanInterval(uint16_t interval) {
vcoubard 1131:692ddf04fc42 977 return _scanningParams.setInterval(interval);
vcoubard 1131:692ddf04fc42 978 }
vcoubard 1131:692ddf04fc42 979
vcoubard 1131:692ddf04fc42 980 /**
vcoubard 1131:692ddf04fc42 981 * Set up the scanWindow parameter for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 982 * @param[in] window
vcoubard 1131:692ddf04fc42 983 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 984 *
vcoubard 1179:4ab722f8dca0 985 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1179:4ab722f8dca0 986 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1179:4ab722f8dca0 987 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1179:4ab722f8dca0 988 * to have the interval and window set to the same value. In this case,
vcoubard 1179:4ab722f8dca0 989 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1179:4ab722f8dca0 990 * interval.
vcoubard 1131:692ddf04fc42 991 *
vcoubard 1179:4ab722f8dca0 992 * Once the scanning parameters have been configured, scanning can be
vcoubard 1179:4ab722f8dca0 993 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 994 *
vcoubard 1179:4ab722f8dca0 995 * If scanning is already active, the updated value of scanWindow will be
vcoubard 1179:4ab722f8dca0 996 * propagated to the underlying BLE stack.
vcoubard 1131:692ddf04fc42 997 */
vcoubard 1131:692ddf04fc42 998 ble_error_t setScanWindow(uint16_t window) {
vcoubard 1131:692ddf04fc42 999 ble_error_t rc;
vcoubard 1131:692ddf04fc42 1000 if ((rc = _scanningParams.setWindow(window)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 1001 return rc;
vcoubard 1131:692ddf04fc42 1002 }
vcoubard 1131:692ddf04fc42 1003
vcoubard 1131:692ddf04fc42 1004 /* If scanning is already active, propagate the new setting to the stack. */
vcoubard 1131:692ddf04fc42 1005 if (scanningActive) {
vcoubard 1131:692ddf04fc42 1006 return startRadioScan(_scanningParams);
vcoubard 1131:692ddf04fc42 1007 }
vcoubard 1131:692ddf04fc42 1008
vcoubard 1131:692ddf04fc42 1009 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 1010 }
vcoubard 1131:692ddf04fc42 1011
vcoubard 1131:692ddf04fc42 1012 /**
vcoubard 1131:692ddf04fc42 1013 * Set up parameters for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 1014 * @param[in] timeout
vcoubard 1131:692ddf04fc42 1015 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
vcoubard 1131:692ddf04fc42 1016 *
vcoubard 1179:4ab722f8dca0 1017 * Once the scanning parameters have been configured, scanning can be
vcoubard 1179:4ab722f8dca0 1018 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 1019 *
vcoubard 1179:4ab722f8dca0 1020 * If scanning is already active, the updated value of scanTimeout will be
vcoubard 1179:4ab722f8dca0 1021 * propagated to the underlying BLE stack.
vcoubard 1131:692ddf04fc42 1022 */
vcoubard 1131:692ddf04fc42 1023 ble_error_t setScanTimeout(uint16_t timeout) {
vcoubard 1131:692ddf04fc42 1024 ble_error_t rc;
vcoubard 1131:692ddf04fc42 1025 if ((rc = _scanningParams.setTimeout(timeout)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 1026 return rc;
vcoubard 1131:692ddf04fc42 1027 }
vcoubard 1131:692ddf04fc42 1028
vcoubard 1131:692ddf04fc42 1029 /* If scanning is already active, propagate the new settings to the stack. */
vcoubard 1131:692ddf04fc42 1030 if (scanningActive) {
vcoubard 1131:692ddf04fc42 1031 return startRadioScan(_scanningParams);
vcoubard 1131:692ddf04fc42 1032 }
vcoubard 1131:692ddf04fc42 1033
vcoubard 1131:692ddf04fc42 1034 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 1035 }
vcoubard 1131:692ddf04fc42 1036
vcoubard 1131:692ddf04fc42 1037 /**
vcoubard 1179:4ab722f8dca0 1038 * Set up parameters for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 1039 * @param[in] activeScanning
vcoubard 1179:4ab722f8dca0 1040 * Set to True if active-scanning is required. This is used to fetch the
vcoubard 1179:4ab722f8dca0 1041 * scan response from a peer if possible.
vcoubard 1131:692ddf04fc42 1042 *
vcoubard 1179:4ab722f8dca0 1043 * Once the scanning parameters have been configured, scanning can be
vcoubard 1179:4ab722f8dca0 1044 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 1045 *
vcoubard 1179:4ab722f8dca0 1046 * If scanning is already in progress, then active-scanning will be enabled
vcoubard 1179:4ab722f8dca0 1047 * for the underlying BLE stack.
vcoubard 1131:692ddf04fc42 1048 */
vcoubard 1131:692ddf04fc42 1049 ble_error_t setActiveScanning(bool activeScanning) {
vcoubard 1131:692ddf04fc42 1050 _scanningParams.setActiveScanning(activeScanning);
vcoubard 1131:692ddf04fc42 1051
vcoubard 1131:692ddf04fc42 1052 /* If scanning is already active, propagate the new settings to the stack. */
vcoubard 1131:692ddf04fc42 1053 if (scanningActive) {
vcoubard 1131:692ddf04fc42 1054 return startRadioScan(_scanningParams);
vcoubard 1131:692ddf04fc42 1055 }
vcoubard 1131:692ddf04fc42 1056
vcoubard 1131:692ddf04fc42 1057 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 1058 }
vcoubard 1131:692ddf04fc42 1059
vcoubard 1131:692ddf04fc42 1060 /**
vcoubard 1131:692ddf04fc42 1061 * Start scanning (Observer Procedure) based on the parameters currently in
vcoubard 1131:692ddf04fc42 1062 * effect.
vcoubard 1131:692ddf04fc42 1063 *
vcoubard 1131:692ddf04fc42 1064 * @param[in] callback
vcoubard 1131:692ddf04fc42 1065 * The application-specific callback to be invoked upon
vcoubard 1131:692ddf04fc42 1066 * receiving every advertisement report. This can be passed in
vcoubard 1131:692ddf04fc42 1067 * as NULL, in which case scanning may not be enabled at all.
vcoubard 1131:692ddf04fc42 1068 */
vcoubard 1131:692ddf04fc42 1069 ble_error_t startScan(void (*callback)(const AdvertisementCallbackParams_t *params)) {
vcoubard 1131:692ddf04fc42 1070 ble_error_t err = BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 1071 if (callback) {
vcoubard 1131:692ddf04fc42 1072 if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 1073 scanningActive = true;
vcoubard 1131:692ddf04fc42 1074 onAdvertisementReport.attach(callback);
vcoubard 1131:692ddf04fc42 1075 }
vcoubard 1131:692ddf04fc42 1076 }
vcoubard 1131:692ddf04fc42 1077
vcoubard 1131:692ddf04fc42 1078 return err;
vcoubard 1131:692ddf04fc42 1079 }
vcoubard 1131:692ddf04fc42 1080
vcoubard 1131:692ddf04fc42 1081 /**
vcoubard 1179:4ab722f8dca0 1082 * Same as above, but this takes an (object, method) pair for a callback.
vcoubard 1131:692ddf04fc42 1083 */
vcoubard 1131:692ddf04fc42 1084 template<typename T>
vcoubard 1131:692ddf04fc42 1085 ble_error_t startScan(T *object, void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)) {
vcoubard 1131:692ddf04fc42 1086 ble_error_t err = BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 1087 if (object && callbackMember) {
vcoubard 1131:692ddf04fc42 1088 if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 1089 scanningActive = true;
vcoubard 1131:692ddf04fc42 1090 onAdvertisementReport.attach(object, callbackMember);
vcoubard 1131:692ddf04fc42 1091 }
vcoubard 1131:692ddf04fc42 1092 }
vcoubard 1131:692ddf04fc42 1093
vcoubard 1131:692ddf04fc42 1094 return err;
vcoubard 1131:692ddf04fc42 1095 }
vcoubard 1131:692ddf04fc42 1096
vcoubard 1131:692ddf04fc42 1097 /**
vcoubard 1131:692ddf04fc42 1098 * Initialize radio-notification events to be generated from the stack.
vcoubard 1131:692ddf04fc42 1099 * This API doesn't need to be called directly.
vcoubard 1131:692ddf04fc42 1100 *
vcoubard 1131:692ddf04fc42 1101 * Radio Notification is a feature that enables ACTIVE and INACTIVE
vcoubard 1131:692ddf04fc42 1102 * (nACTIVE) signals from the stack that notify the application when the
vcoubard 1131:692ddf04fc42 1103 * radio is in use.
vcoubard 1131:692ddf04fc42 1104 *
vcoubard 1131:692ddf04fc42 1105 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard 1131:692ddf04fc42 1106 * signal is sent at the end of the radio event. These signals can be used
vcoubard 1131:692ddf04fc42 1107 * by the application programmer to synchronize application logic with radio
vcoubard 1131:692ddf04fc42 1108 * activity. For example, the ACTIVE signal can be used to shut off external
vcoubard 1131:692ddf04fc42 1109 * devices, to manage peak current drawn during periods when the radio is on,
vcoubard 1131:692ddf04fc42 1110 * or to trigger sensor data collection for transmission in the Radio Event.
vcoubard 1131:692ddf04fc42 1111 *
vcoubard 1131:692ddf04fc42 1112 * @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
vcoubard 1131:692ddf04fc42 1113 */
vcoubard 1131:692ddf04fc42 1114 virtual ble_error_t initRadioNotification(void) {
vcoubard 1131:692ddf04fc42 1115 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 1116 }
vcoubard 1131:692ddf04fc42 1117
vcoubard 1131:692ddf04fc42 1118 private:
vcoubard 1131:692ddf04fc42 1119 ble_error_t setAdvertisingData(void) {
vcoubard 1131:692ddf04fc42 1120 return setAdvertisingData(_advPayload, _scanResponse);
vcoubard 1131:692ddf04fc42 1121 }
vcoubard 1131:692ddf04fc42 1122
vcoubard 1131:692ddf04fc42 1123 private:
vcoubard 1131:692ddf04fc42 1124 virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0;
vcoubard 1131:692ddf04fc42 1125 virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
vcoubard 1131:692ddf04fc42 1126
vcoubard 1131:692ddf04fc42 1127 public:
vcoubard 1131:692ddf04fc42 1128 /**
vcoubard 1179:4ab722f8dca0 1129 * Accessors to read back currently active advertising params.
vcoubard 1131:692ddf04fc42 1130 */
vcoubard 1131:692ddf04fc42 1131 GapAdvertisingParams &getAdvertisingParams(void) {
vcoubard 1131:692ddf04fc42 1132 return _advParams;
vcoubard 1131:692ddf04fc42 1133 }
vcoubard 1131:692ddf04fc42 1134 const GapAdvertisingParams &getAdvertisingParams(void) const {
vcoubard 1131:692ddf04fc42 1135 return _advParams;
vcoubard 1131:692ddf04fc42 1136 }
vcoubard 1131:692ddf04fc42 1137
vcoubard 1131:692ddf04fc42 1138 /**
vcoubard 1131:692ddf04fc42 1139 * Set up a particular, user-constructed set of advertisement parameters for
vcoubard 1131:692ddf04fc42 1140 * the underlying stack. It would be uncommon for this API to be used
vcoubard 1131:692ddf04fc42 1141 * directly; there are other APIs to tweak advertisement parameters
vcoubard 1131:692ddf04fc42 1142 * individually.
vcoubard 1131:692ddf04fc42 1143 */
vcoubard 1131:692ddf04fc42 1144 void setAdvertisingParams(const GapAdvertisingParams &newParams) {
vcoubard 1131:692ddf04fc42 1145 _advParams = newParams;
vcoubard 1131:692ddf04fc42 1146 }
vcoubard 1131:692ddf04fc42 1147
vcoubard 1131:692ddf04fc42 1148 /* Event callback handlers. */
vcoubard 1131:692ddf04fc42 1149 public:
vcoubard 1131:692ddf04fc42 1150 /**
vcoubard 1131:692ddf04fc42 1151 * Set up a callback for timeout events. Refer to TimeoutSource_t for
vcoubard 1131:692ddf04fc42 1152 * possible event types.
vcoubard 1179:4ab722f8dca0 1153 * @note It is possible to unregister callbacks using onTimeout().detach(callback)
vcoubard 1131:692ddf04fc42 1154 */
vcoubard 1131:692ddf04fc42 1155 void onTimeout(TimeoutEventCallback_t callback) {
vcoubard 1131:692ddf04fc42 1156 timeoutCallbackChain.add(callback);
vcoubard 1131:692ddf04fc42 1157 }
vcoubard 1131:692ddf04fc42 1158
vcoubard 1131:692ddf04fc42 1159 /**
vcoubard 1179:4ab722f8dca0 1160 * @brief provide access to the callchain of timeout event callbacks
vcoubard 1179:4ab722f8dca0 1161 * It is possible to register callbacks using onTimeout().add(callback);
vcoubard 1179:4ab722f8dca0 1162 * It is possible to unregister callbacks using onTimeout().detach(callback)
vcoubard 1179:4ab722f8dca0 1163 * @return The timeout event callbacks chain
vcoubard 1131:692ddf04fc42 1164 */
vcoubard 1131:692ddf04fc42 1165 TimeoutEventCallbackChain_t& onTimeout() {
vcoubard 1131:692ddf04fc42 1166 return timeoutCallbackChain;
vcoubard 1131:692ddf04fc42 1167 }
vcoubard 1131:692ddf04fc42 1168
vcoubard 1131:692ddf04fc42 1169 /**
vcoubard 1131:692ddf04fc42 1170 * Append to a chain of callbacks to be invoked upon GAP connection.
vcoubard 1131:692ddf04fc42 1171 * @note It is possible to unregister callbacks using onConnection().detach(callback)
vcoubard 1131:692ddf04fc42 1172 */
vcoubard 1179:4ab722f8dca0 1173 void onConnection(ConnectionEventCallback_t callback) {connectionCallChain.add(callback);}
vcoubard 1179:4ab722f8dca0 1174
vcoubard 1179:4ab722f8dca0 1175 template<typename T>
vcoubard 1179:4ab722f8dca0 1176 void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
vcoubard 1131:692ddf04fc42 1177
vcoubard 1131:692ddf04fc42 1178 /**
vcoubard 1179:4ab722f8dca0 1179 * @brief provide access to the callchain of connection event callbacks
vcoubard 1179:4ab722f8dca0 1180 * It is possible to register callbacks using onConnection().add(callback);
vcoubard 1179:4ab722f8dca0 1181 * It is possible to unregister callbacks using onConnection().detach(callback)
vcoubard 1179:4ab722f8dca0 1182 * @return The connection event callbacks chain
vcoubard 1131:692ddf04fc42 1183 */
vcoubard 1132:6362b7c2fdff 1184 ConnectionEventCallbackChain_t& onConnection() {
vcoubard 1131:692ddf04fc42 1185 return connectionCallChain;
vcoubard 1131:692ddf04fc42 1186 }
vcoubard 1131:692ddf04fc42 1187
vcoubard 1131:692ddf04fc42 1188 /**
vcoubard 1131:692ddf04fc42 1189 * Append to a chain of callbacks to be invoked upon GAP disconnection.
vcoubard 1179:4ab722f8dca0 1190 * @note It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard 1131:692ddf04fc42 1191 */
vcoubard 1179:4ab722f8dca0 1192 void onDisconnection(DisconnectionEventCallback_t callback) {disconnectionCallChain.add(callback);}
vcoubard 1179:4ab722f8dca0 1193
vcoubard 1179:4ab722f8dca0 1194 template<typename T>
vcoubard 1179:4ab722f8dca0 1195 void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
vcoubard 1131:692ddf04fc42 1196
vcoubard 1131:692ddf04fc42 1197 /**
vcoubard 1179:4ab722f8dca0 1198 * @brief provide access to the callchain of disconnection event callbacks
vcoubard 1179:4ab722f8dca0 1199 * It is possible to register callbacks using onDisconnection().add(callback);
vcoubard 1179:4ab722f8dca0 1200 * It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard 1179:4ab722f8dca0 1201 * @return The disconnection event callbacks chain
vcoubard 1131:692ddf04fc42 1202 */
vcoubard 1131:692ddf04fc42 1203 DisconnectionEventCallbackChain_t& onDisconnection() {
vcoubard 1131:692ddf04fc42 1204 return disconnectionCallChain;
vcoubard 1131:692ddf04fc42 1205 }
vcoubard 1131:692ddf04fc42 1206
vcoubard 1131:692ddf04fc42 1207 /**
vcoubard 1131:692ddf04fc42 1208 * Set the application callback for radio-notification events.
vcoubard 1131:692ddf04fc42 1209 *
vcoubard 1131:692ddf04fc42 1210 * Radio Notification is a feature that enables ACTIVE and INACTIVE
vcoubard 1131:692ddf04fc42 1211 * (nACTIVE) signals from the stack that notify the application when the
vcoubard 1131:692ddf04fc42 1212 * radio is in use.
vcoubard 1131:692ddf04fc42 1213 *
vcoubard 1131:692ddf04fc42 1214 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard 1131:692ddf04fc42 1215 * signal is sent at the end of the radio event. These signals can be used
vcoubard 1131:692ddf04fc42 1216 * by the application programmer to synchronize application logic with radio
vcoubard 1131:692ddf04fc42 1217 * activity. For example, the ACTIVE signal can be used to shut off external
vcoubard 1131:692ddf04fc42 1218 * devices, to manage peak current drawn during periods when the radio is on,
vcoubard 1131:692ddf04fc42 1219 * or to trigger sensor data collection for transmission in the Radio Event.
vcoubard 1131:692ddf04fc42 1220 *
vcoubard 1179:4ab722f8dca0 1221 * @param callback
vcoubard 1179:4ab722f8dca0 1222 * The application handler to be invoked in response to a radio
vcoubard 1179:4ab722f8dca0 1223 * ACTIVE/INACTIVE event.
vcoubard 1179:4ab722f8dca0 1224 *
vcoubard 1179:4ab722f8dca0 1225 * Or in the other version:
vcoubard 1179:4ab722f8dca0 1226 *
vcoubard 1179:4ab722f8dca0 1227 * @param tptr
vcoubard 1179:4ab722f8dca0 1228 * Pointer to the object of a class defining the member callback
vcoubard 1179:4ab722f8dca0 1229 * function (mptr).
vcoubard 1179:4ab722f8dca0 1230 * @param mptr
vcoubard 1179:4ab722f8dca0 1231 * The member callback (within the context of an object) to be
vcoubard 1179:4ab722f8dca0 1232 * invoked in response to a radio ACTIVE/INACTIVE event.
vcoubard 1131:692ddf04fc42 1233 */
vcoubard 1131:692ddf04fc42 1234 void onRadioNotification(void (*callback)(bool param)) {
vcoubard 1131:692ddf04fc42 1235 radioNotificationCallback.attach(callback);
vcoubard 1131:692ddf04fc42 1236 }
vcoubard 1131:692ddf04fc42 1237 template <typename T>
vcoubard 1131:692ddf04fc42 1238 void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
vcoubard 1131:692ddf04fc42 1239 radioNotificationCallback.attach(tptr, mptr);
vcoubard 1131:692ddf04fc42 1240 }
vcoubard 1131:692ddf04fc42 1241
vcoubard 1135:22aada733dbd 1242 /**
vcoubard 1135:22aada733dbd 1243 * Setup a callback to be invoked to notify the user application that the
vcoubard 1135:22aada733dbd 1244 * Gap instance is about to shutdown (possibly as a result of a call
vcoubard 1135:22aada733dbd 1245 * to BLE::shutdown()).
vcoubard 1135:22aada733dbd 1246 *
vcoubard 1179:4ab722f8dca0 1247 * @Note: It is possible to chain together multiple onShutdown callbacks
vcoubard 1135:22aada733dbd 1248 * (potentially from different modules of an application) to be notified
vcoubard 1135:22aada733dbd 1249 * before the Gap instance is shutdown.
vcoubard 1135:22aada733dbd 1250 *
vcoubard 1179:4ab722f8dca0 1251 * @Note: It is also possible to set up a callback into a member function of
vcoubard 1135:22aada733dbd 1252 * some object.
vcoubard 1135:22aada733dbd 1253 *
vcoubard 1179:4ab722f8dca0 1254 * @Note It is possible to unregister a callback using onShutdown().detach(callback)
vcoubard 1135:22aada733dbd 1255 */
vcoubard 1135:22aada733dbd 1256 void onShutdown(const GapShutdownCallback_t& callback) {
vcoubard 1135:22aada733dbd 1257 shutdownCallChain.add(callback);
vcoubard 1135:22aada733dbd 1258 }
vcoubard 1135:22aada733dbd 1259 template <typename T>
vcoubard 1135:22aada733dbd 1260 void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
vcoubard 1135:22aada733dbd 1261 shutdownCallChain.add(objPtr, memberPtr);
vcoubard 1135:22aada733dbd 1262 }
vcoubard 1135:22aada733dbd 1263
vcoubard 1135:22aada733dbd 1264 /**
vcoubard 1179:4ab722f8dca0 1265 * @brief provide access to the callchain of shutdown event callbacks
vcoubard 1179:4ab722f8dca0 1266 * It is possible to register callbacks using onShutdown().add(callback);
vcoubard 1179:4ab722f8dca0 1267 * It is possible to unregister callbacks using onShutdown().detach(callback)
vcoubard 1179:4ab722f8dca0 1268 * @return The shutdown event callbacks chain
vcoubard 1135:22aada733dbd 1269 */
vcoubard 1135:22aada733dbd 1270 GapShutdownCallbackChain_t& onShutdown() {
vcoubard 1135:22aada733dbd 1271 return shutdownCallChain;
vcoubard 1135:22aada733dbd 1272 }
vcoubard 1135:22aada733dbd 1273
vcoubard 1135:22aada733dbd 1274 public:
vcoubard 1135:22aada733dbd 1275 /**
vcoubard 1135:22aada733dbd 1276 * Notify all registered onShutdown callbacks that the Gap instance is
vcoubard 1135:22aada733dbd 1277 * about to be shutdown and clear all Gap state of the
vcoubard 1135:22aada733dbd 1278 * associated object.
vcoubard 1135:22aada733dbd 1279 *
vcoubard 1135:22aada733dbd 1280 * This function is meant to be overridden in the platform-specific
vcoubard 1135:22aada733dbd 1281 * sub-class. Nevertheless, the sub-class is only expected to reset its
vcoubard 1135:22aada733dbd 1282 * state and not the data held in Gap members. This shall be achieved by a
vcoubard 1135:22aada733dbd 1283 * call to Gap::reset() from the sub-class' reset() implementation.
vcoubard 1135:22aada733dbd 1284 *
vcoubard 1135:22aada733dbd 1285 * @return BLE_ERROR_NONE on success.
vcoubard 1135:22aada733dbd 1286 *
vcoubard 1179:4ab722f8dca0 1287 * @note: Currently a call to reset() does not reset the advertising and
vcoubard 1135:22aada733dbd 1288 * scan parameters to default values.
vcoubard 1135:22aada733dbd 1289 */
vcoubard 1135:22aada733dbd 1290 virtual ble_error_t reset(void) {
vcoubard 1135:22aada733dbd 1291 /* Notify that the instance is about to shutdown */
vcoubard 1135:22aada733dbd 1292 shutdownCallChain.call(this);
vcoubard 1135:22aada733dbd 1293 shutdownCallChain.clear();
vcoubard 1135:22aada733dbd 1294
vcoubard 1135:22aada733dbd 1295 /* Clear Gap state */
vcoubard 1135:22aada733dbd 1296 state.advertising = 0;
vcoubard 1135:22aada733dbd 1297 state.connected = 0;
vcoubard 1180:e11b058d005e 1298 connectionCount = 0;
vcoubard 1135:22aada733dbd 1299
vcoubard 1135:22aada733dbd 1300 /* Clear scanning state */
vcoubard 1135:22aada733dbd 1301 scanningActive = false;
vcoubard 1135:22aada733dbd 1302
vcoubard 1135:22aada733dbd 1303 /* Clear advertising and scanning data */
vcoubard 1135:22aada733dbd 1304 _advPayload.clear();
vcoubard 1135:22aada733dbd 1305 _scanResponse.clear();
vcoubard 1135:22aada733dbd 1306
vcoubard 1135:22aada733dbd 1307 /* Clear callbacks */
vcoubard 1135:22aada733dbd 1308 timeoutCallbackChain.clear();
vcoubard 1135:22aada733dbd 1309 connectionCallChain.clear();
vcoubard 1135:22aada733dbd 1310 disconnectionCallChain.clear();
vcoubard 1135:22aada733dbd 1311 radioNotificationCallback = NULL;
vcoubard 1135:22aada733dbd 1312 onAdvertisementReport = NULL;
vcoubard 1135:22aada733dbd 1313
vcoubard 1135:22aada733dbd 1314 return BLE_ERROR_NONE;
vcoubard 1135:22aada733dbd 1315 }
vcoubard 1135:22aada733dbd 1316
vcoubard 1131:692ddf04fc42 1317 protected:
vcoubard 1131:692ddf04fc42 1318 Gap() :
vcoubard 1131:692ddf04fc42 1319 _advParams(),
vcoubard 1131:692ddf04fc42 1320 _advPayload(),
vcoubard 1131:692ddf04fc42 1321 _scanningParams(),
vcoubard 1131:692ddf04fc42 1322 _scanResponse(),
vcoubard 1180:e11b058d005e 1323 connectionCount(0),
vcoubard 1131:692ddf04fc42 1324 state(),
vcoubard 1131:692ddf04fc42 1325 scanningActive(false),
vcoubard 1131:692ddf04fc42 1326 timeoutCallbackChain(),
vcoubard 1131:692ddf04fc42 1327 radioNotificationCallback(),
vcoubard 1131:692ddf04fc42 1328 onAdvertisementReport(),
vcoubard 1131:692ddf04fc42 1329 connectionCallChain(),
vcoubard 1131:692ddf04fc42 1330 disconnectionCallChain() {
vcoubard 1131:692ddf04fc42 1331 _advPayload.clear();
vcoubard 1131:692ddf04fc42 1332 _scanResponse.clear();
vcoubard 1131:692ddf04fc42 1333 }
vcoubard 1131:692ddf04fc42 1334
vcoubard 1131:692ddf04fc42 1335 /* Entry points for the underlying stack to report events back to the user. */
vcoubard 1131:692ddf04fc42 1336 public:
vcoubard 1135:22aada733dbd 1337 void processConnectionEvent(Handle_t handle,
vcoubard 1135:22aada733dbd 1338 Role_t role,
vcoubard 1135:22aada733dbd 1339 BLEProtocol::AddressType_t peerAddrType,
vcoubard 1135:22aada733dbd 1340 const BLEProtocol::AddressBytes_t peerAddr,
vcoubard 1135:22aada733dbd 1341 BLEProtocol::AddressType_t ownAddrType,
vcoubard 1135:22aada733dbd 1342 const BLEProtocol::AddressBytes_t ownAddr,
vcoubard 1135:22aada733dbd 1343 const ConnectionParams_t *connectionParams) {
vcoubard 1180:e11b058d005e 1344 /* Update Gap state */
vcoubard 1180:e11b058d005e 1345 state.advertising = 0;
vcoubard 1180:e11b058d005e 1346 state.connected = 1;
vcoubard 1180:e11b058d005e 1347 ++connectionCount;
vcoubard 1180:e11b058d005e 1348
vcoubard 1131:692ddf04fc42 1349 ConnectionCallbackParams_t callbackParams(handle, role, peerAddrType, peerAddr, ownAddrType, ownAddr, connectionParams);
vcoubard 1131:692ddf04fc42 1350 connectionCallChain.call(&callbackParams);
vcoubard 1131:692ddf04fc42 1351 }
vcoubard 1131:692ddf04fc42 1352
vcoubard 1131:692ddf04fc42 1353 void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
vcoubard 1180:e11b058d005e 1354 /* Update Gap state */
vcoubard 1180:e11b058d005e 1355 --connectionCount;
vcoubard 1180:e11b058d005e 1356 if (!connectionCount) {
vcoubard 1180:e11b058d005e 1357 state.connected = 0;
vcoubard 1180:e11b058d005e 1358 }
vcoubard 1180:e11b058d005e 1359
vcoubard 1131:692ddf04fc42 1360 DisconnectionCallbackParams_t callbackParams(handle, reason);
vcoubard 1131:692ddf04fc42 1361 disconnectionCallChain.call(&callbackParams);
vcoubard 1131:692ddf04fc42 1362 }
vcoubard 1131:692ddf04fc42 1363
vcoubard 1135:22aada733dbd 1364 void processAdvertisementReport(const BLEProtocol::AddressBytes_t peerAddr,
vcoubard 1135:22aada733dbd 1365 int8_t rssi,
vcoubard 1135:22aada733dbd 1366 bool isScanResponse,
vcoubard 1131:692ddf04fc42 1367 GapAdvertisingParams::AdvertisingType_t type,
vcoubard 1135:22aada733dbd 1368 uint8_t advertisingDataLen,
vcoubard 1135:22aada733dbd 1369 const uint8_t *advertisingData) {
vcoubard 1131:692ddf04fc42 1370 AdvertisementCallbackParams_t params;
vcoubard 1131:692ddf04fc42 1371 memcpy(params.peerAddr, peerAddr, ADDR_LEN);
vcoubard 1131:692ddf04fc42 1372 params.rssi = rssi;
vcoubard 1131:692ddf04fc42 1373 params.isScanResponse = isScanResponse;
vcoubard 1131:692ddf04fc42 1374 params.type = type;
vcoubard 1131:692ddf04fc42 1375 params.advertisingDataLen = advertisingDataLen;
vcoubard 1131:692ddf04fc42 1376 params.advertisingData = advertisingData;
vcoubard 1131:692ddf04fc42 1377 onAdvertisementReport.call(&params);
vcoubard 1131:692ddf04fc42 1378 }
vcoubard 1131:692ddf04fc42 1379
vcoubard 1131:692ddf04fc42 1380 void processTimeoutEvent(TimeoutSource_t source) {
vcoubard 1179:4ab722f8dca0 1381 if (source == TIMEOUT_SRC_ADVERTISING) {
vcoubard 1179:4ab722f8dca0 1382 /* Update gap state if the source is an advertising timeout */
vcoubard 1179:4ab722f8dca0 1383 state.advertising = 0;
vcoubard 1179:4ab722f8dca0 1384 }
vcoubard 1131:692ddf04fc42 1385 if (timeoutCallbackChain) {
vcoubard 1131:692ddf04fc42 1386 timeoutCallbackChain(source);
vcoubard 1131:692ddf04fc42 1387 }
vcoubard 1131:692ddf04fc42 1388 }
vcoubard 1131:692ddf04fc42 1389
vcoubard 1131:692ddf04fc42 1390 protected:
vcoubard 1131:692ddf04fc42 1391 GapAdvertisingParams _advParams;
vcoubard 1131:692ddf04fc42 1392 GapAdvertisingData _advPayload;
vcoubard 1131:692ddf04fc42 1393 GapScanningParams _scanningParams;
vcoubard 1131:692ddf04fc42 1394 GapAdvertisingData _scanResponse;
vcoubard 1131:692ddf04fc42 1395
vcoubard 1180:e11b058d005e 1396 /**
vcoubard 1180:e11b058d005e 1397 * Total number of open connections.
vcoubard 1180:e11b058d005e 1398 */
vcoubard 1180:e11b058d005e 1399 uint8_t connectionCount;
vcoubard 1131:692ddf04fc42 1400 GapState_t state;
vcoubard 1131:692ddf04fc42 1401 bool scanningActive;
vcoubard 1131:692ddf04fc42 1402
vcoubard 1131:692ddf04fc42 1403 protected:
vcoubard 1131:692ddf04fc42 1404 TimeoutEventCallbackChain_t timeoutCallbackChain;
vcoubard 1131:692ddf04fc42 1405 RadioNotificationEventCallback_t radioNotificationCallback;
vcoubard 1131:692ddf04fc42 1406 AdvertisementReportCallback_t onAdvertisementReport;
vcoubard 1131:692ddf04fc42 1407 ConnectionEventCallbackChain_t connectionCallChain;
vcoubard 1131:692ddf04fc42 1408 DisconnectionEventCallbackChain_t disconnectionCallChain;
vcoubard 1131:692ddf04fc42 1409
vcoubard 1131:692ddf04fc42 1410 private:
vcoubard 1135:22aada733dbd 1411 GapShutdownCallbackChain_t shutdownCallChain;
vcoubard 1135:22aada733dbd 1412
vcoubard 1135:22aada733dbd 1413 private:
vcoubard 1131:692ddf04fc42 1414 /* Disallow copy and assignment. */
vcoubard 1131:692ddf04fc42 1415 Gap(const Gap &);
vcoubard 1131:692ddf04fc42 1416 Gap& operator=(const Gap &);
vcoubard 1131:692ddf04fc42 1417 };
vcoubard 1131:692ddf04fc42 1418
rgrover1 710:b2e1a2660ec2 1419 #endif // ifndef __GAP_H__