Alex Cordonnier / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Fork of BLE_API by Bluetooth Low Energy

ble/Gap.h@1182:b70129080ddf, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:15:34 2016 +0100
Revision:
1182:b70129080ddf
Parent:
1180:e11b058d005e
Child:
1183:1589830dbdb7
Synchronized with git rev 07ad5292

Author: Andres Amaya Garcia

Update Gap state in startAdvertising()

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 1182:b70129080ddf 744 ble_error_t rc;
vcoubard 1131:692ddf04fc42 745 setAdvertisingData(); /* Update the underlying stack. */
vcoubard 1182:b70129080ddf 746 if ((rc = startAdvertising(_advParams)) == BLE_ERROR_NONE) {
vcoubard 1182:b70129080ddf 747 state.advertising = 1;
vcoubard 1182:b70129080ddf 748 }
vcoubard 1182:b70129080ddf 749 return rc;
vcoubard 1131:692ddf04fc42 750 }
vcoubard 1131:692ddf04fc42 751
vcoubard 1131:692ddf04fc42 752 /**
vcoubard 1131:692ddf04fc42 753 * Reset any advertising payload prepared from prior calls to
vcoubard 1131:692ddf04fc42 754 * accumulateAdvertisingPayload(). This automatically propagates the re-
vcoubard 1131:692ddf04fc42 755 * initialized advertising payload to the underlying stack.
vcoubard 1131:692ddf04fc42 756 */
vcoubard 1131:692ddf04fc42 757 void clearAdvertisingPayload(void) {
vcoubard 1131:692ddf04fc42 758 _advPayload.clear();
vcoubard 1131:692ddf04fc42 759 setAdvertisingData();
vcoubard 1131:692ddf04fc42 760 }
vcoubard 1131:692ddf04fc42 761
vcoubard 1131:692ddf04fc42 762 /**
vcoubard 1131:692ddf04fc42 763 * Accumulate an AD structure in the advertising payload. Please note that
vcoubard 1131:692ddf04fc42 764 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1131:692ddf04fc42 765 * as an additional 31 bytes if the advertising payload is too
vcoubard 1131:692ddf04fc42 766 * small.
vcoubard 1131:692ddf04fc42 767 *
vcoubard 1131:692ddf04fc42 768 * @param[in] flags
vcoubard 1131:692ddf04fc42 769 * The flags to be added. Please refer to
vcoubard 1131:692ddf04fc42 770 * GapAdvertisingData::Flags for valid flags. Multiple
vcoubard 1131:692ddf04fc42 771 * flags may be specified in combination.
vcoubard 1131:692ddf04fc42 772 */
vcoubard 1131:692ddf04fc42 773 ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
vcoubard 1131:692ddf04fc42 774 ble_error_t rc;
vcoubard 1131:692ddf04fc42 775 if ((rc = _advPayload.addFlags(flags)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 776 return rc;
vcoubard 1131:692ddf04fc42 777 }
vcoubard 1131:692ddf04fc42 778
vcoubard 1131:692ddf04fc42 779 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 780 }
vcoubard 1131:692ddf04fc42 781
vcoubard 1131:692ddf04fc42 782 /**
vcoubard 1131:692ddf04fc42 783 * Accumulate an AD structure in the advertising payload. Please note that
vcoubard 1131:692ddf04fc42 784 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1131:692ddf04fc42 785 * as an additional 31 bytes if the advertising payload is too
vcoubard 1131:692ddf04fc42 786 * small.
vcoubard 1131:692ddf04fc42 787 *
vcoubard 1179:4ab722f8dca0 788 * @param app
vcoubard 1179:4ab722f8dca0 789 * The appearance of the peripheral.
vcoubard 1131:692ddf04fc42 790 */
vcoubard 1131:692ddf04fc42 791 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
vcoubard 1131:692ddf04fc42 792 setAppearance(app);
vcoubard 1131:692ddf04fc42 793
vcoubard 1131:692ddf04fc42 794 ble_error_t rc;
vcoubard 1131:692ddf04fc42 795 if ((rc = _advPayload.addAppearance(app)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 796 return rc;
vcoubard 1131:692ddf04fc42 797 }
vcoubard 1131:692ddf04fc42 798
vcoubard 1131:692ddf04fc42 799 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 800 }
vcoubard 1131:692ddf04fc42 801
vcoubard 1131:692ddf04fc42 802 /**
vcoubard 1131:692ddf04fc42 803 * Accumulate an AD structure in the advertising payload. Please note that
vcoubard 1131:692ddf04fc42 804 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1131:692ddf04fc42 805 * as an additional 31 bytes if the advertising payload is too
vcoubard 1131:692ddf04fc42 806 * small.
vcoubard 1131:692ddf04fc42 807 *
vcoubard 1179:4ab722f8dca0 808 * @param power
vcoubard 1179:4ab722f8dca0 809 * The max transmit power to be used by the controller (in dBm).
vcoubard 1131:692ddf04fc42 810 */
vcoubard 1131:692ddf04fc42 811 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
vcoubard 1131:692ddf04fc42 812 ble_error_t rc;
vcoubard 1131:692ddf04fc42 813 if ((rc = _advPayload.addTxPower(power)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 814 return rc;
vcoubard 1131:692ddf04fc42 815 }
vcoubard 1131:692ddf04fc42 816
vcoubard 1131:692ddf04fc42 817 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 818 }
vcoubard 1131:692ddf04fc42 819
vcoubard 1131:692ddf04fc42 820 /**
vcoubard 1131:692ddf04fc42 821 * Accumulate a variable length byte-stream as an AD structure in the
vcoubard 1131:692ddf04fc42 822 * advertising payload. Please note that the payload is limited to 31 bytes.
vcoubard 1131:692ddf04fc42 823 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
vcoubard 1131:692ddf04fc42 824 * advertising payload is too small.
vcoubard 1131:692ddf04fc42 825 *
vcoubard 1179:4ab722f8dca0 826 * @param type The type describing the variable length data.
vcoubard 1179:4ab722f8dca0 827 * @param data Data bytes.
vcoubard 1179:4ab722f8dca0 828 * @param len Length of data.
vcoubard 1135:22aada733dbd 829 *
vcoubard 1135:22aada733dbd 830 * @return BLE_ERROR_NONE if the advertisement payload was updated based on
vcoubard 1135:22aada733dbd 831 * matching AD type; otherwise, an appropriate error.
vcoubard 1135:22aada733dbd 832 *
vcoubard 1135:22aada733dbd 833 * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS,
vcoubard 1135:22aada733dbd 834 * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS,
vcoubard 1135:22aada733dbd 835 * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS,
vcoubard 1135:22aada733dbd 836 * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the
vcoubard 1135:22aada733dbd 837 * supplied value is appended to the values previously added to the
vcoubard 1135:22aada733dbd 838 * payload.
vcoubard 1131:692ddf04fc42 839 */
vcoubard 1131:692ddf04fc42 840 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard 1131:692ddf04fc42 841 if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
vcoubard 1131:692ddf04fc42 842 setDeviceName(data);
vcoubard 1131:692ddf04fc42 843 }
vcoubard 1131:692ddf04fc42 844
vcoubard 1131:692ddf04fc42 845 ble_error_t rc;
vcoubard 1131:692ddf04fc42 846 if ((rc = _advPayload.addData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 847 return rc;
vcoubard 1131:692ddf04fc42 848 }
vcoubard 1131:692ddf04fc42 849
vcoubard 1131:692ddf04fc42 850 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 851 }
vcoubard 1131:692ddf04fc42 852
vcoubard 1131:692ddf04fc42 853 /**
vcoubard 1131:692ddf04fc42 854 * Update a particular ADV field in the advertising payload (based on
vcoubard 1135:22aada733dbd 855 * matching type).
vcoubard 1131:692ddf04fc42 856 *
vcoubard 1179:4ab722f8dca0 857 * @param[in] type The ADV type field describing the variable length data.
vcoubard 1179:4ab722f8dca0 858 * @param[in] data Data bytes.
vcoubard 1179:4ab722f8dca0 859 * @param[in] len Length of data.
vcoubard 1131:692ddf04fc42 860 *
vcoubard 1179:4ab722f8dca0 861 * @note: If advertisements are enabled, then the update will take effect immediately.
vcoubard 1131:692ddf04fc42 862 *
vcoubard 1131:692ddf04fc42 863 * @return BLE_ERROR_NONE if the advertisement payload was updated based on
vcoubard 1135:22aada733dbd 864 * matching AD type; otherwise, an appropriate error.
vcoubard 1131:692ddf04fc42 865 */
vcoubard 1131:692ddf04fc42 866 ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard 1131:692ddf04fc42 867 if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
vcoubard 1131:692ddf04fc42 868 setDeviceName(data);
vcoubard 1131:692ddf04fc42 869 }
vcoubard 1131:692ddf04fc42 870
vcoubard 1131:692ddf04fc42 871 ble_error_t rc;
vcoubard 1131:692ddf04fc42 872 if ((rc = _advPayload.updateData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 873 return rc;
vcoubard 1131:692ddf04fc42 874 }
vcoubard 1131:692ddf04fc42 875
vcoubard 1131:692ddf04fc42 876 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 877 }
vcoubard 1131:692ddf04fc42 878
vcoubard 1131:692ddf04fc42 879 /**
vcoubard 1131:692ddf04fc42 880 * Set up a particular, user-constructed advertisement payload for the
vcoubard 1131:692ddf04fc42 881 * underlying stack. It would be uncommon for this API to be used directly;
vcoubard 1179:4ab722f8dca0 882 * there are other APIs to build an advertisement payload (see above).
vcoubard 1131:692ddf04fc42 883 */
vcoubard 1131:692ddf04fc42 884 ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) {
vcoubard 1131:692ddf04fc42 885 _advPayload = payload;
vcoubard 1131:692ddf04fc42 886 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 887 }
vcoubard 1131:692ddf04fc42 888
vcoubard 1131:692ddf04fc42 889 /**
vcoubard 1179:4ab722f8dca0 890 * @return Read back advertising data. Useful for storing and
vcoubard 1179:4ab722f8dca0 891 * restoring payload.
vcoubard 1131:692ddf04fc42 892 */
vcoubard 1131:692ddf04fc42 893 const GapAdvertisingData &getAdvertisingPayload(void) const {
vcoubard 1131:692ddf04fc42 894 return _advPayload;
vcoubard 1131:692ddf04fc42 895 }
vcoubard 1131:692ddf04fc42 896
vcoubard 1131:692ddf04fc42 897 /**
vcoubard 1131:692ddf04fc42 898 * Accumulate a variable length byte-stream as an AD structure in the
vcoubard 1131:692ddf04fc42 899 * scanResponse payload.
vcoubard 1131:692ddf04fc42 900 *
vcoubard 1179:4ab722f8dca0 901 * @param[in] type The type describing the variable length data.
vcoubard 1179:4ab722f8dca0 902 * @param[in] data Data bytes.
vcoubard 1179:4ab722f8dca0 903 * @param[in] len Length of data.
vcoubard 1131:692ddf04fc42 904 */
vcoubard 1131:692ddf04fc42 905 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard 1131:692ddf04fc42 906 ble_error_t rc;
vcoubard 1131:692ddf04fc42 907 if ((rc = _scanResponse.addData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 908 return rc;
vcoubard 1131:692ddf04fc42 909 }
vcoubard 1131:692ddf04fc42 910
vcoubard 1131:692ddf04fc42 911 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 912 }
vcoubard 1131:692ddf04fc42 913
vcoubard 1131:692ddf04fc42 914 /**
vcoubard 1131:692ddf04fc42 915 * Reset any scan response prepared from prior calls to
vcoubard 1179:4ab722f8dca0 916 * accumulateScanResponse().
vcoubard 1131:692ddf04fc42 917 *
vcoubard 1179:4ab722f8dca0 918 * Note: This should be followed by a call to setAdvertisingPayload() or
vcoubard 1179:4ab722f8dca0 919 * startAdvertising() before the update takes effect.
vcoubard 1131:692ddf04fc42 920 */
vcoubard 1131:692ddf04fc42 921 void clearScanResponse(void) {
vcoubard 1131:692ddf04fc42 922 _scanResponse.clear();
vcoubard 1131:692ddf04fc42 923 setAdvertisingData();
vcoubard 1131:692ddf04fc42 924 }
vcoubard 1131:692ddf04fc42 925
vcoubard 1131:692ddf04fc42 926 /**
vcoubard 1131:692ddf04fc42 927 * Set up parameters for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 928 * @param[in] interval
vcoubard 1131:692ddf04fc42 929 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 930 * @param[in] window
vcoubard 1131:692ddf04fc42 931 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 932 * @param[in] timeout
vcoubard 1131:692ddf04fc42 933 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
vcoubard 1131:692ddf04fc42 934 * @param[in] activeScanning
vcoubard 1131:692ddf04fc42 935 * Set to True if active-scanning is required. This is used to fetch the
vcoubard 1131:692ddf04fc42 936 * scan response from a peer if possible.
vcoubard 1131:692ddf04fc42 937 *
vcoubard 1179:4ab722f8dca0 938 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1179:4ab722f8dca0 939 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1179:4ab722f8dca0 940 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1179:4ab722f8dca0 941 * to have the interval and window set to the same value. In this case,
vcoubard 1179:4ab722f8dca0 942 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1179:4ab722f8dca0 943 * interval.
vcoubard 1131:692ddf04fc42 944 *
vcoubard 1179:4ab722f8dca0 945 * Once the scanning parameters have been configured, scanning can be
vcoubard 1179:4ab722f8dca0 946 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 947 *
vcoubard 1179:4ab722f8dca0 948 * @Note: The scan interval and window are recommendations to the BLE stack.
vcoubard 1131:692ddf04fc42 949 */
vcoubard 1131:692ddf04fc42 950 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
vcoubard 1131:692ddf04fc42 951 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
vcoubard 1131:692ddf04fc42 952 uint16_t timeout = 0,
vcoubard 1131:692ddf04fc42 953 bool activeScanning = false) {
vcoubard 1131:692ddf04fc42 954 ble_error_t rc;
vcoubard 1131:692ddf04fc42 955 if (((rc = _scanningParams.setInterval(interval)) == BLE_ERROR_NONE) &&
vcoubard 1131:692ddf04fc42 956 ((rc = _scanningParams.setWindow(window)) == BLE_ERROR_NONE) &&
vcoubard 1131:692ddf04fc42 957 ((rc = _scanningParams.setTimeout(timeout)) == BLE_ERROR_NONE)) {
vcoubard 1131:692ddf04fc42 958 _scanningParams.setActiveScanning(activeScanning);
vcoubard 1131:692ddf04fc42 959 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 960 }
vcoubard 1131:692ddf04fc42 961
vcoubard 1131:692ddf04fc42 962 return rc;
vcoubard 1131:692ddf04fc42 963 }
vcoubard 1131:692ddf04fc42 964
vcoubard 1131:692ddf04fc42 965 /**
vcoubard 1131:692ddf04fc42 966 * Set up the scanInterval parameter for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 967 * @param[in] interval
vcoubard 1131:692ddf04fc42 968 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 969 *
vcoubard 1179:4ab722f8dca0 970 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1179:4ab722f8dca0 971 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1179:4ab722f8dca0 972 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1179:4ab722f8dca0 973 * to have the interval and window set to the same value. In this case,
vcoubard 1179:4ab722f8dca0 974 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1179:4ab722f8dca0 975 * interval.
vcoubard 1131:692ddf04fc42 976 *
vcoubard 1179:4ab722f8dca0 977 * Once the scanning parameters have been configured, scanning can be
vcoubard 1179:4ab722f8dca0 978 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 979 */
vcoubard 1131:692ddf04fc42 980 ble_error_t setScanInterval(uint16_t interval) {
vcoubard 1131:692ddf04fc42 981 return _scanningParams.setInterval(interval);
vcoubard 1131:692ddf04fc42 982 }
vcoubard 1131:692ddf04fc42 983
vcoubard 1131:692ddf04fc42 984 /**
vcoubard 1131:692ddf04fc42 985 * Set up the scanWindow parameter for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 986 * @param[in] window
vcoubard 1131:692ddf04fc42 987 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 988 *
vcoubard 1179:4ab722f8dca0 989 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1179:4ab722f8dca0 990 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1179:4ab722f8dca0 991 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1179:4ab722f8dca0 992 * to have the interval and window set to the same value. In this case,
vcoubard 1179:4ab722f8dca0 993 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1179:4ab722f8dca0 994 * interval.
vcoubard 1131:692ddf04fc42 995 *
vcoubard 1179:4ab722f8dca0 996 * Once the scanning parameters have been configured, scanning can be
vcoubard 1179:4ab722f8dca0 997 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 998 *
vcoubard 1179:4ab722f8dca0 999 * If scanning is already active, the updated value of scanWindow will be
vcoubard 1179:4ab722f8dca0 1000 * propagated to the underlying BLE stack.
vcoubard 1131:692ddf04fc42 1001 */
vcoubard 1131:692ddf04fc42 1002 ble_error_t setScanWindow(uint16_t window) {
vcoubard 1131:692ddf04fc42 1003 ble_error_t rc;
vcoubard 1131:692ddf04fc42 1004 if ((rc = _scanningParams.setWindow(window)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 1005 return rc;
vcoubard 1131:692ddf04fc42 1006 }
vcoubard 1131:692ddf04fc42 1007
vcoubard 1131:692ddf04fc42 1008 /* If scanning is already active, propagate the new setting to the stack. */
vcoubard 1131:692ddf04fc42 1009 if (scanningActive) {
vcoubard 1131:692ddf04fc42 1010 return startRadioScan(_scanningParams);
vcoubard 1131:692ddf04fc42 1011 }
vcoubard 1131:692ddf04fc42 1012
vcoubard 1131:692ddf04fc42 1013 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 1014 }
vcoubard 1131:692ddf04fc42 1015
vcoubard 1131:692ddf04fc42 1016 /**
vcoubard 1131:692ddf04fc42 1017 * Set up parameters for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 1018 * @param[in] timeout
vcoubard 1131:692ddf04fc42 1019 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
vcoubard 1131:692ddf04fc42 1020 *
vcoubard 1179:4ab722f8dca0 1021 * Once the scanning parameters have been configured, scanning can be
vcoubard 1179:4ab722f8dca0 1022 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 1023 *
vcoubard 1179:4ab722f8dca0 1024 * If scanning is already active, the updated value of scanTimeout will be
vcoubard 1179:4ab722f8dca0 1025 * propagated to the underlying BLE stack.
vcoubard 1131:692ddf04fc42 1026 */
vcoubard 1131:692ddf04fc42 1027 ble_error_t setScanTimeout(uint16_t timeout) {
vcoubard 1131:692ddf04fc42 1028 ble_error_t rc;
vcoubard 1131:692ddf04fc42 1029 if ((rc = _scanningParams.setTimeout(timeout)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 1030 return rc;
vcoubard 1131:692ddf04fc42 1031 }
vcoubard 1131:692ddf04fc42 1032
vcoubard 1131:692ddf04fc42 1033 /* If scanning is already active, propagate the new settings to the stack. */
vcoubard 1131:692ddf04fc42 1034 if (scanningActive) {
vcoubard 1131:692ddf04fc42 1035 return startRadioScan(_scanningParams);
vcoubard 1131:692ddf04fc42 1036 }
vcoubard 1131:692ddf04fc42 1037
vcoubard 1131:692ddf04fc42 1038 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 1039 }
vcoubard 1131:692ddf04fc42 1040
vcoubard 1131:692ddf04fc42 1041 /**
vcoubard 1179:4ab722f8dca0 1042 * Set up parameters for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 1043 * @param[in] activeScanning
vcoubard 1179:4ab722f8dca0 1044 * Set to True if active-scanning is required. This is used to fetch the
vcoubard 1179:4ab722f8dca0 1045 * scan response from a peer if possible.
vcoubard 1131:692ddf04fc42 1046 *
vcoubard 1179:4ab722f8dca0 1047 * Once the scanning parameters have been configured, scanning can be
vcoubard 1179:4ab722f8dca0 1048 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 1049 *
vcoubard 1179:4ab722f8dca0 1050 * If scanning is already in progress, then active-scanning will be enabled
vcoubard 1179:4ab722f8dca0 1051 * for the underlying BLE stack.
vcoubard 1131:692ddf04fc42 1052 */
vcoubard 1131:692ddf04fc42 1053 ble_error_t setActiveScanning(bool activeScanning) {
vcoubard 1131:692ddf04fc42 1054 _scanningParams.setActiveScanning(activeScanning);
vcoubard 1131:692ddf04fc42 1055
vcoubard 1131:692ddf04fc42 1056 /* If scanning is already active, propagate the new settings to the stack. */
vcoubard 1131:692ddf04fc42 1057 if (scanningActive) {
vcoubard 1131:692ddf04fc42 1058 return startRadioScan(_scanningParams);
vcoubard 1131:692ddf04fc42 1059 }
vcoubard 1131:692ddf04fc42 1060
vcoubard 1131:692ddf04fc42 1061 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 1062 }
vcoubard 1131:692ddf04fc42 1063
vcoubard 1131:692ddf04fc42 1064 /**
vcoubard 1131:692ddf04fc42 1065 * Start scanning (Observer Procedure) based on the parameters currently in
vcoubard 1131:692ddf04fc42 1066 * effect.
vcoubard 1131:692ddf04fc42 1067 *
vcoubard 1131:692ddf04fc42 1068 * @param[in] callback
vcoubard 1131:692ddf04fc42 1069 * The application-specific callback to be invoked upon
vcoubard 1131:692ddf04fc42 1070 * receiving every advertisement report. This can be passed in
vcoubard 1131:692ddf04fc42 1071 * as NULL, in which case scanning may not be enabled at all.
vcoubard 1131:692ddf04fc42 1072 */
vcoubard 1131:692ddf04fc42 1073 ble_error_t startScan(void (*callback)(const AdvertisementCallbackParams_t *params)) {
vcoubard 1131:692ddf04fc42 1074 ble_error_t err = BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 1075 if (callback) {
vcoubard 1131:692ddf04fc42 1076 if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 1077 scanningActive = true;
vcoubard 1131:692ddf04fc42 1078 onAdvertisementReport.attach(callback);
vcoubard 1131:692ddf04fc42 1079 }
vcoubard 1131:692ddf04fc42 1080 }
vcoubard 1131:692ddf04fc42 1081
vcoubard 1131:692ddf04fc42 1082 return err;
vcoubard 1131:692ddf04fc42 1083 }
vcoubard 1131:692ddf04fc42 1084
vcoubard 1131:692ddf04fc42 1085 /**
vcoubard 1179:4ab722f8dca0 1086 * Same as above, but this takes an (object, method) pair for a callback.
vcoubard 1131:692ddf04fc42 1087 */
vcoubard 1131:692ddf04fc42 1088 template<typename T>
vcoubard 1131:692ddf04fc42 1089 ble_error_t startScan(T *object, void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)) {
vcoubard 1131:692ddf04fc42 1090 ble_error_t err = BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 1091 if (object && callbackMember) {
vcoubard 1131:692ddf04fc42 1092 if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 1093 scanningActive = true;
vcoubard 1131:692ddf04fc42 1094 onAdvertisementReport.attach(object, callbackMember);
vcoubard 1131:692ddf04fc42 1095 }
vcoubard 1131:692ddf04fc42 1096 }
vcoubard 1131:692ddf04fc42 1097
vcoubard 1131:692ddf04fc42 1098 return err;
vcoubard 1131:692ddf04fc42 1099 }
vcoubard 1131:692ddf04fc42 1100
vcoubard 1131:692ddf04fc42 1101 /**
vcoubard 1131:692ddf04fc42 1102 * Initialize radio-notification events to be generated from the stack.
vcoubard 1131:692ddf04fc42 1103 * This API doesn't need to be called directly.
vcoubard 1131:692ddf04fc42 1104 *
vcoubard 1131:692ddf04fc42 1105 * Radio Notification is a feature that enables ACTIVE and INACTIVE
vcoubard 1131:692ddf04fc42 1106 * (nACTIVE) signals from the stack that notify the application when the
vcoubard 1131:692ddf04fc42 1107 * radio is in use.
vcoubard 1131:692ddf04fc42 1108 *
vcoubard 1131:692ddf04fc42 1109 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard 1131:692ddf04fc42 1110 * signal is sent at the end of the radio event. These signals can be used
vcoubard 1131:692ddf04fc42 1111 * by the application programmer to synchronize application logic with radio
vcoubard 1131:692ddf04fc42 1112 * activity. For example, the ACTIVE signal can be used to shut off external
vcoubard 1131:692ddf04fc42 1113 * devices, to manage peak current drawn during periods when the radio is on,
vcoubard 1131:692ddf04fc42 1114 * or to trigger sensor data collection for transmission in the Radio Event.
vcoubard 1131:692ddf04fc42 1115 *
vcoubard 1131:692ddf04fc42 1116 * @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
vcoubard 1131:692ddf04fc42 1117 */
vcoubard 1131:692ddf04fc42 1118 virtual ble_error_t initRadioNotification(void) {
vcoubard 1131:692ddf04fc42 1119 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 1120 }
vcoubard 1131:692ddf04fc42 1121
vcoubard 1131:692ddf04fc42 1122 private:
vcoubard 1131:692ddf04fc42 1123 ble_error_t setAdvertisingData(void) {
vcoubard 1131:692ddf04fc42 1124 return setAdvertisingData(_advPayload, _scanResponse);
vcoubard 1131:692ddf04fc42 1125 }
vcoubard 1131:692ddf04fc42 1126
vcoubard 1131:692ddf04fc42 1127 private:
vcoubard 1131:692ddf04fc42 1128 virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0;
vcoubard 1131:692ddf04fc42 1129 virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
vcoubard 1131:692ddf04fc42 1130
vcoubard 1131:692ddf04fc42 1131 public:
vcoubard 1131:692ddf04fc42 1132 /**
vcoubard 1179:4ab722f8dca0 1133 * Accessors to read back currently active advertising params.
vcoubard 1131:692ddf04fc42 1134 */
vcoubard 1131:692ddf04fc42 1135 GapAdvertisingParams &getAdvertisingParams(void) {
vcoubard 1131:692ddf04fc42 1136 return _advParams;
vcoubard 1131:692ddf04fc42 1137 }
vcoubard 1131:692ddf04fc42 1138 const GapAdvertisingParams &getAdvertisingParams(void) const {
vcoubard 1131:692ddf04fc42 1139 return _advParams;
vcoubard 1131:692ddf04fc42 1140 }
vcoubard 1131:692ddf04fc42 1141
vcoubard 1131:692ddf04fc42 1142 /**
vcoubard 1131:692ddf04fc42 1143 * Set up a particular, user-constructed set of advertisement parameters for
vcoubard 1131:692ddf04fc42 1144 * the underlying stack. It would be uncommon for this API to be used
vcoubard 1131:692ddf04fc42 1145 * directly; there are other APIs to tweak advertisement parameters
vcoubard 1131:692ddf04fc42 1146 * individually.
vcoubard 1131:692ddf04fc42 1147 */
vcoubard 1131:692ddf04fc42 1148 void setAdvertisingParams(const GapAdvertisingParams &newParams) {
vcoubard 1131:692ddf04fc42 1149 _advParams = newParams;
vcoubard 1131:692ddf04fc42 1150 }
vcoubard 1131:692ddf04fc42 1151
vcoubard 1131:692ddf04fc42 1152 /* Event callback handlers. */
vcoubard 1131:692ddf04fc42 1153 public:
vcoubard 1131:692ddf04fc42 1154 /**
vcoubard 1131:692ddf04fc42 1155 * Set up a callback for timeout events. Refer to TimeoutSource_t for
vcoubard 1131:692ddf04fc42 1156 * possible event types.
vcoubard 1179:4ab722f8dca0 1157 * @note It is possible to unregister callbacks using onTimeout().detach(callback)
vcoubard 1131:692ddf04fc42 1158 */
vcoubard 1131:692ddf04fc42 1159 void onTimeout(TimeoutEventCallback_t callback) {
vcoubard 1131:692ddf04fc42 1160 timeoutCallbackChain.add(callback);
vcoubard 1131:692ddf04fc42 1161 }
vcoubard 1131:692ddf04fc42 1162
vcoubard 1131:692ddf04fc42 1163 /**
vcoubard 1179:4ab722f8dca0 1164 * @brief provide access to the callchain of timeout event callbacks
vcoubard 1179:4ab722f8dca0 1165 * It is possible to register callbacks using onTimeout().add(callback);
vcoubard 1179:4ab722f8dca0 1166 * It is possible to unregister callbacks using onTimeout().detach(callback)
vcoubard 1179:4ab722f8dca0 1167 * @return The timeout event callbacks chain
vcoubard 1131:692ddf04fc42 1168 */
vcoubard 1131:692ddf04fc42 1169 TimeoutEventCallbackChain_t& onTimeout() {
vcoubard 1131:692ddf04fc42 1170 return timeoutCallbackChain;
vcoubard 1131:692ddf04fc42 1171 }
vcoubard 1131:692ddf04fc42 1172
vcoubard 1131:692ddf04fc42 1173 /**
vcoubard 1131:692ddf04fc42 1174 * Append to a chain of callbacks to be invoked upon GAP connection.
vcoubard 1131:692ddf04fc42 1175 * @note It is possible to unregister callbacks using onConnection().detach(callback)
vcoubard 1131:692ddf04fc42 1176 */
vcoubard 1179:4ab722f8dca0 1177 void onConnection(ConnectionEventCallback_t callback) {connectionCallChain.add(callback);}
vcoubard 1179:4ab722f8dca0 1178
vcoubard 1179:4ab722f8dca0 1179 template<typename T>
vcoubard 1179:4ab722f8dca0 1180 void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
vcoubard 1131:692ddf04fc42 1181
vcoubard 1131:692ddf04fc42 1182 /**
vcoubard 1179:4ab722f8dca0 1183 * @brief provide access to the callchain of connection event callbacks
vcoubard 1179:4ab722f8dca0 1184 * It is possible to register callbacks using onConnection().add(callback);
vcoubard 1179:4ab722f8dca0 1185 * It is possible to unregister callbacks using onConnection().detach(callback)
vcoubard 1179:4ab722f8dca0 1186 * @return The connection event callbacks chain
vcoubard 1131:692ddf04fc42 1187 */
vcoubard 1132:6362b7c2fdff 1188 ConnectionEventCallbackChain_t& onConnection() {
vcoubard 1131:692ddf04fc42 1189 return connectionCallChain;
vcoubard 1131:692ddf04fc42 1190 }
vcoubard 1131:692ddf04fc42 1191
vcoubard 1131:692ddf04fc42 1192 /**
vcoubard 1131:692ddf04fc42 1193 * Append to a chain of callbacks to be invoked upon GAP disconnection.
vcoubard 1179:4ab722f8dca0 1194 * @note It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard 1131:692ddf04fc42 1195 */
vcoubard 1179:4ab722f8dca0 1196 void onDisconnection(DisconnectionEventCallback_t callback) {disconnectionCallChain.add(callback);}
vcoubard 1179:4ab722f8dca0 1197
vcoubard 1179:4ab722f8dca0 1198 template<typename T>
vcoubard 1179:4ab722f8dca0 1199 void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
vcoubard 1131:692ddf04fc42 1200
vcoubard 1131:692ddf04fc42 1201 /**
vcoubard 1179:4ab722f8dca0 1202 * @brief provide access to the callchain of disconnection event callbacks
vcoubard 1179:4ab722f8dca0 1203 * It is possible to register callbacks using onDisconnection().add(callback);
vcoubard 1179:4ab722f8dca0 1204 * It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard 1179:4ab722f8dca0 1205 * @return The disconnection event callbacks chain
vcoubard 1131:692ddf04fc42 1206 */
vcoubard 1131:692ddf04fc42 1207 DisconnectionEventCallbackChain_t& onDisconnection() {
vcoubard 1131:692ddf04fc42 1208 return disconnectionCallChain;
vcoubard 1131:692ddf04fc42 1209 }
vcoubard 1131:692ddf04fc42 1210
vcoubard 1131:692ddf04fc42 1211 /**
vcoubard 1131:692ddf04fc42 1212 * Set the application callback for radio-notification events.
vcoubard 1131:692ddf04fc42 1213 *
vcoubard 1131:692ddf04fc42 1214 * Radio Notification is a feature that enables ACTIVE and INACTIVE
vcoubard 1131:692ddf04fc42 1215 * (nACTIVE) signals from the stack that notify the application when the
vcoubard 1131:692ddf04fc42 1216 * radio is in use.
vcoubard 1131:692ddf04fc42 1217 *
vcoubard 1131:692ddf04fc42 1218 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard 1131:692ddf04fc42 1219 * signal is sent at the end of the radio event. These signals can be used
vcoubard 1131:692ddf04fc42 1220 * by the application programmer to synchronize application logic with radio
vcoubard 1131:692ddf04fc42 1221 * activity. For example, the ACTIVE signal can be used to shut off external
vcoubard 1131:692ddf04fc42 1222 * devices, to manage peak current drawn during periods when the radio is on,
vcoubard 1131:692ddf04fc42 1223 * or to trigger sensor data collection for transmission in the Radio Event.
vcoubard 1131:692ddf04fc42 1224 *
vcoubard 1179:4ab722f8dca0 1225 * @param callback
vcoubard 1179:4ab722f8dca0 1226 * The application handler to be invoked in response to a radio
vcoubard 1179:4ab722f8dca0 1227 * ACTIVE/INACTIVE event.
vcoubard 1179:4ab722f8dca0 1228 *
vcoubard 1179:4ab722f8dca0 1229 * Or in the other version:
vcoubard 1179:4ab722f8dca0 1230 *
vcoubard 1179:4ab722f8dca0 1231 * @param tptr
vcoubard 1179:4ab722f8dca0 1232 * Pointer to the object of a class defining the member callback
vcoubard 1179:4ab722f8dca0 1233 * function (mptr).
vcoubard 1179:4ab722f8dca0 1234 * @param mptr
vcoubard 1179:4ab722f8dca0 1235 * The member callback (within the context of an object) to be
vcoubard 1179:4ab722f8dca0 1236 * invoked in response to a radio ACTIVE/INACTIVE event.
vcoubard 1131:692ddf04fc42 1237 */
vcoubard 1131:692ddf04fc42 1238 void onRadioNotification(void (*callback)(bool param)) {
vcoubard 1131:692ddf04fc42 1239 radioNotificationCallback.attach(callback);
vcoubard 1131:692ddf04fc42 1240 }
vcoubard 1131:692ddf04fc42 1241 template <typename T>
vcoubard 1131:692ddf04fc42 1242 void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
vcoubard 1131:692ddf04fc42 1243 radioNotificationCallback.attach(tptr, mptr);
vcoubard 1131:692ddf04fc42 1244 }
vcoubard 1131:692ddf04fc42 1245
vcoubard 1135:22aada733dbd 1246 /**
vcoubard 1135:22aada733dbd 1247 * Setup a callback to be invoked to notify the user application that the
vcoubard 1135:22aada733dbd 1248 * Gap instance is about to shutdown (possibly as a result of a call
vcoubard 1135:22aada733dbd 1249 * to BLE::shutdown()).
vcoubard 1135:22aada733dbd 1250 *
vcoubard 1179:4ab722f8dca0 1251 * @Note: It is possible to chain together multiple onShutdown callbacks
vcoubard 1135:22aada733dbd 1252 * (potentially from different modules of an application) to be notified
vcoubard 1135:22aada733dbd 1253 * before the Gap instance is shutdown.
vcoubard 1135:22aada733dbd 1254 *
vcoubard 1179:4ab722f8dca0 1255 * @Note: It is also possible to set up a callback into a member function of
vcoubard 1135:22aada733dbd 1256 * some object.
vcoubard 1135:22aada733dbd 1257 *
vcoubard 1179:4ab722f8dca0 1258 * @Note It is possible to unregister a callback using onShutdown().detach(callback)
vcoubard 1135:22aada733dbd 1259 */
vcoubard 1135:22aada733dbd 1260 void onShutdown(const GapShutdownCallback_t& callback) {
vcoubard 1135:22aada733dbd 1261 shutdownCallChain.add(callback);
vcoubard 1135:22aada733dbd 1262 }
vcoubard 1135:22aada733dbd 1263 template <typename T>
vcoubard 1135:22aada733dbd 1264 void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
vcoubard 1135:22aada733dbd 1265 shutdownCallChain.add(objPtr, memberPtr);
vcoubard 1135:22aada733dbd 1266 }
vcoubard 1135:22aada733dbd 1267
vcoubard 1135:22aada733dbd 1268 /**
vcoubard 1179:4ab722f8dca0 1269 * @brief provide access to the callchain of shutdown event callbacks
vcoubard 1179:4ab722f8dca0 1270 * It is possible to register callbacks using onShutdown().add(callback);
vcoubard 1179:4ab722f8dca0 1271 * It is possible to unregister callbacks using onShutdown().detach(callback)
vcoubard 1179:4ab722f8dca0 1272 * @return The shutdown event callbacks chain
vcoubard 1135:22aada733dbd 1273 */
vcoubard 1135:22aada733dbd 1274 GapShutdownCallbackChain_t& onShutdown() {
vcoubard 1135:22aada733dbd 1275 return shutdownCallChain;
vcoubard 1135:22aada733dbd 1276 }
vcoubard 1135:22aada733dbd 1277
vcoubard 1135:22aada733dbd 1278 public:
vcoubard 1135:22aada733dbd 1279 /**
vcoubard 1135:22aada733dbd 1280 * Notify all registered onShutdown callbacks that the Gap instance is
vcoubard 1135:22aada733dbd 1281 * about to be shutdown and clear all Gap state of the
vcoubard 1135:22aada733dbd 1282 * associated object.
vcoubard 1135:22aada733dbd 1283 *
vcoubard 1135:22aada733dbd 1284 * This function is meant to be overridden in the platform-specific
vcoubard 1135:22aada733dbd 1285 * sub-class. Nevertheless, the sub-class is only expected to reset its
vcoubard 1135:22aada733dbd 1286 * state and not the data held in Gap members. This shall be achieved by a
vcoubard 1135:22aada733dbd 1287 * call to Gap::reset() from the sub-class' reset() implementation.
vcoubard 1135:22aada733dbd 1288 *
vcoubard 1135:22aada733dbd 1289 * @return BLE_ERROR_NONE on success.
vcoubard 1135:22aada733dbd 1290 *
vcoubard 1179:4ab722f8dca0 1291 * @note: Currently a call to reset() does not reset the advertising and
vcoubard 1135:22aada733dbd 1292 * scan parameters to default values.
vcoubard 1135:22aada733dbd 1293 */
vcoubard 1135:22aada733dbd 1294 virtual ble_error_t reset(void) {
vcoubard 1135:22aada733dbd 1295 /* Notify that the instance is about to shutdown */
vcoubard 1135:22aada733dbd 1296 shutdownCallChain.call(this);
vcoubard 1135:22aada733dbd 1297 shutdownCallChain.clear();
vcoubard 1135:22aada733dbd 1298
vcoubard 1135:22aada733dbd 1299 /* Clear Gap state */
vcoubard 1135:22aada733dbd 1300 state.advertising = 0;
vcoubard 1135:22aada733dbd 1301 state.connected = 0;
vcoubard 1180:e11b058d005e 1302 connectionCount = 0;
vcoubard 1135:22aada733dbd 1303
vcoubard 1135:22aada733dbd 1304 /* Clear scanning state */
vcoubard 1135:22aada733dbd 1305 scanningActive = false;
vcoubard 1135:22aada733dbd 1306
vcoubard 1135:22aada733dbd 1307 /* Clear advertising and scanning data */
vcoubard 1135:22aada733dbd 1308 _advPayload.clear();
vcoubard 1135:22aada733dbd 1309 _scanResponse.clear();
vcoubard 1135:22aada733dbd 1310
vcoubard 1135:22aada733dbd 1311 /* Clear callbacks */
vcoubard 1135:22aada733dbd 1312 timeoutCallbackChain.clear();
vcoubard 1135:22aada733dbd 1313 connectionCallChain.clear();
vcoubard 1135:22aada733dbd 1314 disconnectionCallChain.clear();
vcoubard 1135:22aada733dbd 1315 radioNotificationCallback = NULL;
vcoubard 1135:22aada733dbd 1316 onAdvertisementReport = NULL;
vcoubard 1135:22aada733dbd 1317
vcoubard 1135:22aada733dbd 1318 return BLE_ERROR_NONE;
vcoubard 1135:22aada733dbd 1319 }
vcoubard 1135:22aada733dbd 1320
vcoubard 1131:692ddf04fc42 1321 protected:
vcoubard 1131:692ddf04fc42 1322 Gap() :
vcoubard 1131:692ddf04fc42 1323 _advParams(),
vcoubard 1131:692ddf04fc42 1324 _advPayload(),
vcoubard 1131:692ddf04fc42 1325 _scanningParams(),
vcoubard 1131:692ddf04fc42 1326 _scanResponse(),
vcoubard 1180:e11b058d005e 1327 connectionCount(0),
vcoubard 1131:692ddf04fc42 1328 state(),
vcoubard 1131:692ddf04fc42 1329 scanningActive(false),
vcoubard 1131:692ddf04fc42 1330 timeoutCallbackChain(),
vcoubard 1131:692ddf04fc42 1331 radioNotificationCallback(),
vcoubard 1131:692ddf04fc42 1332 onAdvertisementReport(),
vcoubard 1131:692ddf04fc42 1333 connectionCallChain(),
vcoubard 1131:692ddf04fc42 1334 disconnectionCallChain() {
vcoubard 1131:692ddf04fc42 1335 _advPayload.clear();
vcoubard 1131:692ddf04fc42 1336 _scanResponse.clear();
vcoubard 1131:692ddf04fc42 1337 }
vcoubard 1131:692ddf04fc42 1338
vcoubard 1131:692ddf04fc42 1339 /* Entry points for the underlying stack to report events back to the user. */
vcoubard 1131:692ddf04fc42 1340 public:
vcoubard 1135:22aada733dbd 1341 void processConnectionEvent(Handle_t handle,
vcoubard 1135:22aada733dbd 1342 Role_t role,
vcoubard 1135:22aada733dbd 1343 BLEProtocol::AddressType_t peerAddrType,
vcoubard 1135:22aada733dbd 1344 const BLEProtocol::AddressBytes_t peerAddr,
vcoubard 1135:22aada733dbd 1345 BLEProtocol::AddressType_t ownAddrType,
vcoubard 1135:22aada733dbd 1346 const BLEProtocol::AddressBytes_t ownAddr,
vcoubard 1135:22aada733dbd 1347 const ConnectionParams_t *connectionParams) {
vcoubard 1180:e11b058d005e 1348 /* Update Gap state */
vcoubard 1180:e11b058d005e 1349 state.advertising = 0;
vcoubard 1180:e11b058d005e 1350 state.connected = 1;
vcoubard 1180:e11b058d005e 1351 ++connectionCount;
vcoubard 1180:e11b058d005e 1352
vcoubard 1131:692ddf04fc42 1353 ConnectionCallbackParams_t callbackParams(handle, role, peerAddrType, peerAddr, ownAddrType, ownAddr, connectionParams);
vcoubard 1131:692ddf04fc42 1354 connectionCallChain.call(&callbackParams);
vcoubard 1131:692ddf04fc42 1355 }
vcoubard 1131:692ddf04fc42 1356
vcoubard 1131:692ddf04fc42 1357 void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
vcoubard 1180:e11b058d005e 1358 /* Update Gap state */
vcoubard 1180:e11b058d005e 1359 --connectionCount;
vcoubard 1180:e11b058d005e 1360 if (!connectionCount) {
vcoubard 1180:e11b058d005e 1361 state.connected = 0;
vcoubard 1180:e11b058d005e 1362 }
vcoubard 1180:e11b058d005e 1363
vcoubard 1131:692ddf04fc42 1364 DisconnectionCallbackParams_t callbackParams(handle, reason);
vcoubard 1131:692ddf04fc42 1365 disconnectionCallChain.call(&callbackParams);
vcoubard 1131:692ddf04fc42 1366 }
vcoubard 1131:692ddf04fc42 1367
vcoubard 1135:22aada733dbd 1368 void processAdvertisementReport(const BLEProtocol::AddressBytes_t peerAddr,
vcoubard 1135:22aada733dbd 1369 int8_t rssi,
vcoubard 1135:22aada733dbd 1370 bool isScanResponse,
vcoubard 1131:692ddf04fc42 1371 GapAdvertisingParams::AdvertisingType_t type,
vcoubard 1135:22aada733dbd 1372 uint8_t advertisingDataLen,
vcoubard 1135:22aada733dbd 1373 const uint8_t *advertisingData) {
vcoubard 1131:692ddf04fc42 1374 AdvertisementCallbackParams_t params;
vcoubard 1131:692ddf04fc42 1375 memcpy(params.peerAddr, peerAddr, ADDR_LEN);
vcoubard 1131:692ddf04fc42 1376 params.rssi = rssi;
vcoubard 1131:692ddf04fc42 1377 params.isScanResponse = isScanResponse;
vcoubard 1131:692ddf04fc42 1378 params.type = type;
vcoubard 1131:692ddf04fc42 1379 params.advertisingDataLen = advertisingDataLen;
vcoubard 1131:692ddf04fc42 1380 params.advertisingData = advertisingData;
vcoubard 1131:692ddf04fc42 1381 onAdvertisementReport.call(&params);
vcoubard 1131:692ddf04fc42 1382 }
vcoubard 1131:692ddf04fc42 1383
vcoubard 1131:692ddf04fc42 1384 void processTimeoutEvent(TimeoutSource_t source) {
vcoubard 1179:4ab722f8dca0 1385 if (source == TIMEOUT_SRC_ADVERTISING) {
vcoubard 1179:4ab722f8dca0 1386 /* Update gap state if the source is an advertising timeout */
vcoubard 1179:4ab722f8dca0 1387 state.advertising = 0;
vcoubard 1179:4ab722f8dca0 1388 }
vcoubard 1131:692ddf04fc42 1389 if (timeoutCallbackChain) {
vcoubard 1131:692ddf04fc42 1390 timeoutCallbackChain(source);
vcoubard 1131:692ddf04fc42 1391 }
vcoubard 1131:692ddf04fc42 1392 }
vcoubard 1131:692ddf04fc42 1393
vcoubard 1131:692ddf04fc42 1394 protected:
vcoubard 1131:692ddf04fc42 1395 GapAdvertisingParams _advParams;
vcoubard 1131:692ddf04fc42 1396 GapAdvertisingData _advPayload;
vcoubard 1131:692ddf04fc42 1397 GapScanningParams _scanningParams;
vcoubard 1131:692ddf04fc42 1398 GapAdvertisingData _scanResponse;
vcoubard 1131:692ddf04fc42 1399
vcoubard 1180:e11b058d005e 1400 /**
vcoubard 1180:e11b058d005e 1401 * Total number of open connections.
vcoubard 1180:e11b058d005e 1402 */
vcoubard 1180:e11b058d005e 1403 uint8_t connectionCount;
vcoubard 1131:692ddf04fc42 1404 GapState_t state;
vcoubard 1131:692ddf04fc42 1405 bool scanningActive;
vcoubard 1131:692ddf04fc42 1406
vcoubard 1131:692ddf04fc42 1407 protected:
vcoubard 1131:692ddf04fc42 1408 TimeoutEventCallbackChain_t timeoutCallbackChain;
vcoubard 1131:692ddf04fc42 1409 RadioNotificationEventCallback_t radioNotificationCallback;
vcoubard 1131:692ddf04fc42 1410 AdvertisementReportCallback_t onAdvertisementReport;
vcoubard 1131:692ddf04fc42 1411 ConnectionEventCallbackChain_t connectionCallChain;
vcoubard 1131:692ddf04fc42 1412 DisconnectionEventCallbackChain_t disconnectionCallChain;
vcoubard 1131:692ddf04fc42 1413
vcoubard 1131:692ddf04fc42 1414 private:
vcoubard 1135:22aada733dbd 1415 GapShutdownCallbackChain_t shutdownCallChain;
vcoubard 1135:22aada733dbd 1416
vcoubard 1135:22aada733dbd 1417 private:
vcoubard 1131:692ddf04fc42 1418 /* Disallow copy and assignment. */
vcoubard 1131:692ddf04fc42 1419 Gap(const Gap &);
vcoubard 1131:692ddf04fc42 1420 Gap& operator=(const Gap &);
vcoubard 1131:692ddf04fc42 1421 };
vcoubard 1131:692ddf04fc42 1422
rgrover1 710:b2e1a2660ec2 1423 #endif // ifndef __GAP_H__