Wang Xinglu / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Dependencies:   nRF51822

Dependents:   LinkNode_LIS3DH

Fork of BLE_API by Bluetooth Low Energy

ble/Gap.h@1135:22aada733dbd, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:13:54 2016 +0100
Revision:
1135:22aada733dbd
Parent:
1134:d540a48f650d
Child:
1156:e1ea38b576c6
Synchronized with git rev 17e37360

Author: Vincent Coubard

Merge pull request #161 from ARMmbed/develop



merge branch develop (v2.4.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 1135:22aada733dbd 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 1135:22aada733dbd 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 1135:22aada733dbd 55 * \deprecated: Use BLEProtocol::AddressType_t instead.
vcoubard 1135:22aada733dbd 56 *
vcoubard 1135:22aada733dbd 57 * DEPRECATION ALERT: The following constants have been left in their
vcoubard 1135:22aada733dbd 58 * deprecated state to transparenly support existing applications which may
vcoubard 1135:22aada733dbd 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 1135:22aada733dbd 68 static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN; /**< Length (in octets) of the BLE MAC address. */
vcoubard 1135:22aada733dbd 69 typedef BLEProtocol::AddressBytes_t Address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::AddressBytes_t instead. */
vcoubard 1135:22aada733dbd 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 1135:22aada733dbd 140 BLEProtocol::Address_t *addresses;
vcoubard 1135:22aada733dbd 141 uint8_t size;
vcoubard 1135:22aada733dbd 142 uint8_t capacity;
vcoubard 1135:22aada733dbd 143 };
vcoubard 1135:22aada733dbd 144
vcoubard 1135:22aada733dbd 145
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 152 typedef uint16_t Handle_t; /* Type for connection handle. */
vcoubard 1131:692ddf04fc42 153
vcoubard 1131:692ddf04fc42 154 typedef struct {
vcoubard 1135:22aada733dbd 155 uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1135:22aada733dbd 156 uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1135:22aada733dbd 157 uint16_t slaveLatency; /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1131:692ddf04fc42 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 1135:22aada733dbd 167 BLEProtocol::AddressBytes_t peerAddr;
vcoubard 1135:22aada733dbd 168 int8_t rssi;
vcoubard 1135:22aada733dbd 169 bool isScanResponse;
vcoubard 1135:22aada733dbd 170 GapAdvertisingParams::AdvertisingType_t type;
vcoubard 1135:22aada733dbd 171 uint8_t advertisingDataLen;
vcoubard 1135:22aada733dbd 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 1135:22aada733dbd 177 Handle_t handle;
vcoubard 1135:22aada733dbd 178 Role_t role;
vcoubard 1135:22aada733dbd 179 BLEProtocol::AddressType_t peerAddrType;
vcoubard 1135:22aada733dbd 180 BLEProtocol::AddressBytes_t peerAddr;
vcoubard 1135:22aada733dbd 181 BLEProtocol::AddressType_t ownAddrType;
vcoubard 1135:22aada733dbd 182 BLEProtocol::AddressBytes_t ownAddr;
vcoubard 1135:22aada733dbd 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 1131:692ddf04fc42 205 Handle_t handle;
vcoubard 1131:692ddf04fc42 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 1134:d540a48f650d 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 1134:d540a48f650d 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 1131:692ddf04fc42 304 * @param peerAddr
vcoubard 1131:692ddf04fc42 305 * 48-bit address, LSB format.
vcoubard 1131:692ddf04fc42 306 * @param peerAddrType
vcoubard 1131:692ddf04fc42 307 * Address type of the peer.
vcoubard 1131:692ddf04fc42 308 * @param connectionParams
vcoubard 1131:692ddf04fc42 309 * Connection parameters.
vcoubard 1131:692ddf04fc42 310 * @param scanParams
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 313 * successfully. The connectionCallChain (if set) will be invoked upon
vcoubard 1131:692ddf04fc42 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 1135:22aada733dbd 332 * \deprecated: This funtion overloads Gap::connect(const BLEProtocol::Address_t peerAddr,
vcoubard 1135:22aada733dbd 333 BLEProtocol::AddressType_t peerAddrType,
vcoubard 1135:22aada733dbd 334 const ConnectionParams_t *connectionParams,
vcoubard 1135:22aada733dbd 335 const GapScanningParams *scanParams)
vcoubard 1135:22aada733dbd 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 1131:692ddf04fc42 351 * @param reason
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 367 * @param reason
vcoubard 1131:692ddf04fc42 368 * The reason for disconnection; to be sent back to the peer.
vcoubard 1131:692ddf04fc42 369 *
vcoubard 1131:692ddf04fc42 370 * @note: This version of disconnect() doesn't take a connection handle. It
vcoubard 1131:692ddf04fc42 371 * works reliably only for stacks that are limited to a single
vcoubard 1131:692ddf04fc42 372 * connection. This API should be considered *deprecated* in favour of the
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 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 1131:692ddf04fc42 417 * Update connection parameters.
vcoubard 1131:692ddf04fc42 418 * In the central role this will initiate a Link Layer connection parameter update procedure.
vcoubard 1131:692ddf04fc42 419 * In the peripheral role, this will send the corresponding L2CAP request and wait for
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 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 1131:692ddf04fc42 462 * length will return the complete device name length, and not the
vcoubard 1131:692ddf04fc42 463 * number of bytes actually returned in deviceName. The application may
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 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 1131:692ddf04fc42 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 1135:22aada733dbd 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 1131:692ddf04fc42 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 1131:692ddf04fc42 712 * @note: Decreasing this value will allow central devices to detect a
vcoubard 1131:692ddf04fc42 713 * peripheral faster, at the expense of more power being used by the radio
vcoubard 1131:692ddf04fc42 714 * due to the higher data transmit rate.
vcoubard 1131:692ddf04fc42 715 *
vcoubard 1131:692ddf04fc42 716 * @Note: [WARNING] This API previously used 0.625ms as the unit for its
vcoubard 1131:692ddf04fc42 717 * 'interval' argument. That required an explicit conversion from
vcoubard 1131:692ddf04fc42 718 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
vcoubard 1131:692ddf04fc42 719 * no longer required as the new units are milliseconds. Any application
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 784 * @param app
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 804 * @param power
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 822 * @param type The type describing the variable length data.
vcoubard 1131:692ddf04fc42 823 * @param data Data bytes.
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 853 * @param[in] type The ADV type field describing the variable length data.
vcoubard 1131:692ddf04fc42 854 * @param[in] data Data bytes.
vcoubard 1131:692ddf04fc42 855 * @param[in] len Length of data.
vcoubard 1131:692ddf04fc42 856 *
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 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 1131:692ddf04fc42 886 * @return Read back advertising data. Useful for storing and
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 897 * @param[in] type The type describing the variable length data.
vcoubard 1131:692ddf04fc42 898 * @param[in] data Data bytes.
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 912 * accumulateScanResponse().
vcoubard 1131:692ddf04fc42 913 *
vcoubard 1131:692ddf04fc42 914 * Note: This should be followed by a call to setAdvertisingPayload() or
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 934 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1131:692ddf04fc42 935 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1131:692ddf04fc42 936 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1131:692ddf04fc42 937 * to have the interval and window set to the same value. In this case,
vcoubard 1131:692ddf04fc42 938 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1131:692ddf04fc42 939 * interval.
vcoubard 1131:692ddf04fc42 940 *
vcoubard 1131:692ddf04fc42 941 * Once the scanning parameters have been configured, scanning can be
vcoubard 1131:692ddf04fc42 942 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 943 *
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 966 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1131:692ddf04fc42 967 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1131:692ddf04fc42 968 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1131:692ddf04fc42 969 * to have the interval and window set to the same value. In this case,
vcoubard 1131:692ddf04fc42 970 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1131:692ddf04fc42 971 * interval.
vcoubard 1131:692ddf04fc42 972 *
vcoubard 1131:692ddf04fc42 973 * Once the scanning parameters have been configured, scanning can be
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 985 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1131:692ddf04fc42 986 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1131:692ddf04fc42 987 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1131:692ddf04fc42 988 * to have the interval and window set to the same value. In this case,
vcoubard 1131:692ddf04fc42 989 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1131:692ddf04fc42 990 * interval.
vcoubard 1131:692ddf04fc42 991 *
vcoubard 1131:692ddf04fc42 992 * Once the scanning parameters have been configured, scanning can be
vcoubard 1131:692ddf04fc42 993 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 994 *
vcoubard 1131:692ddf04fc42 995 * If scanning is already active, the updated value of scanWindow will be
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 1017 * Once the scanning parameters have been configured, scanning can be
vcoubard 1131:692ddf04fc42 1018 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 1019 *
vcoubard 1131:692ddf04fc42 1020 * If scanning is already active, the updated value of scanTimeout will be
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 1038 * Set up parameters for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 1039 * @param[in] activeScanning
vcoubard 1131:692ddf04fc42 1040 * Set to True if active-scanning is required. This is used to fetch the
vcoubard 1131:692ddf04fc42 1041 * scan response from a peer if possible.
vcoubard 1131:692ddf04fc42 1042 *
vcoubard 1131:692ddf04fc42 1043 * Once the scanning parameters have been configured, scanning can be
vcoubard 1131:692ddf04fc42 1044 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 1045 *
vcoubard 1131:692ddf04fc42 1046 * If scanning is already in progress, then active-scanning will be enabled
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 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 1131:692ddf04fc42 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 1131:692ddf04fc42 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 1131:692ddf04fc42 1160 * @brief provide access to the callchain of timeout event callbacks
vcoubard 1131:692ddf04fc42 1161 * It is possible to register callbacks using onTimeout().add(callback);
vcoubard 1132:6362b7c2fdff 1162 * It is possible to unregister callbacks using onTimeout().detach(callback)
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 1173 void onConnection(ConnectionEventCallback_t callback) {connectionCallChain.add(callback);}
vcoubard 1131:692ddf04fc42 1174
vcoubard 1131:692ddf04fc42 1175 template<typename T>
vcoubard 1131:692ddf04fc42 1176 void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
vcoubard 1131:692ddf04fc42 1177
vcoubard 1131:692ddf04fc42 1178 /**
vcoubard 1131:692ddf04fc42 1179 * @brief provide access to the callchain of connection event callbacks
vcoubard 1131:692ddf04fc42 1180 * It is possible to register callbacks using onConnection().add(callback);
vcoubard 1132:6362b7c2fdff 1181 * It is possible to unregister callbacks using onConnection().detach(callback)
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 1190 * @note It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard 1131:692ddf04fc42 1191 */
vcoubard 1131:692ddf04fc42 1192 void onDisconnection(DisconnectionEventCallback_t callback) {disconnectionCallChain.add(callback);}
vcoubard 1131:692ddf04fc42 1193
vcoubard 1131:692ddf04fc42 1194 template<typename T>
vcoubard 1131:692ddf04fc42 1195 void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
vcoubard 1131:692ddf04fc42 1196
vcoubard 1131:692ddf04fc42 1197 /**
vcoubard 1131:692ddf04fc42 1198 * @brief provide access to the callchain of disconnection event callbacks
vcoubard 1131:692ddf04fc42 1199 * It is possible to register callbacks using onDisconnection().add(callback);
vcoubard 1132:6362b7c2fdff 1200 * It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard 1131:692ddf04fc42 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 1131:692ddf04fc42 1221 * @param callback
vcoubard 1131:692ddf04fc42 1222 * The application handler to be invoked in response to a radio
vcoubard 1131:692ddf04fc42 1223 * ACTIVE/INACTIVE event.
vcoubard 1131:692ddf04fc42 1224 *
vcoubard 1131:692ddf04fc42 1225 * Or in the other version:
vcoubard 1131:692ddf04fc42 1226 *
vcoubard 1131:692ddf04fc42 1227 * @param tptr
vcoubard 1131:692ddf04fc42 1228 * Pointer to the object of a class defining the member callback
vcoubard 1131:692ddf04fc42 1229 * function (mptr).
vcoubard 1131:692ddf04fc42 1230 * @param mptr
vcoubard 1131:692ddf04fc42 1231 * The member callback (within the context of an object) to be
vcoubard 1131:692ddf04fc42 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 1135:22aada733dbd 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 1135:22aada733dbd 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 1135:22aada733dbd 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 1135:22aada733dbd 1265 * @brief provide access to the callchain of shutdown event callbacks
vcoubard 1135:22aada733dbd 1266 * It is possible to register callbacks using onShutdown().add(callback);
vcoubard 1135:22aada733dbd 1267 * It is possible to unregister callbacks using onShutdown().detach(callback)
vcoubard 1135:22aada733dbd 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 1135:22aada733dbd 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 1135:22aada733dbd 1298
vcoubard 1135:22aada733dbd 1299 /* Clear scanning state */
vcoubard 1135:22aada733dbd 1300 scanningActive = false;
vcoubard 1135:22aada733dbd 1301
vcoubard 1135:22aada733dbd 1302 /* Clear advertising and scanning data */
vcoubard 1135:22aada733dbd 1303 _advPayload.clear();
vcoubard 1135:22aada733dbd 1304 _scanResponse.clear();
vcoubard 1135:22aada733dbd 1305
vcoubard 1135:22aada733dbd 1306 /* Clear callbacks */
vcoubard 1135:22aada733dbd 1307 timeoutCallbackChain.clear();
vcoubard 1135:22aada733dbd 1308 connectionCallChain.clear();
vcoubard 1135:22aada733dbd 1309 disconnectionCallChain.clear();
vcoubard 1135:22aada733dbd 1310 radioNotificationCallback = NULL;
vcoubard 1135:22aada733dbd 1311 onAdvertisementReport = NULL;
vcoubard 1135:22aada733dbd 1312
vcoubard 1135:22aada733dbd 1313 return BLE_ERROR_NONE;
vcoubard 1135:22aada733dbd 1314 }
vcoubard 1135:22aada733dbd 1315
vcoubard 1131:692ddf04fc42 1316 protected:
vcoubard 1131:692ddf04fc42 1317 Gap() :
vcoubard 1131:692ddf04fc42 1318 _advParams(),
vcoubard 1131:692ddf04fc42 1319 _advPayload(),
vcoubard 1131:692ddf04fc42 1320 _scanningParams(),
vcoubard 1131:692ddf04fc42 1321 _scanResponse(),
vcoubard 1131:692ddf04fc42 1322 state(),
vcoubard 1131:692ddf04fc42 1323 scanningActive(false),
vcoubard 1131:692ddf04fc42 1324 timeoutCallbackChain(),
vcoubard 1131:692ddf04fc42 1325 radioNotificationCallback(),
vcoubard 1131:692ddf04fc42 1326 onAdvertisementReport(),
vcoubard 1131:692ddf04fc42 1327 connectionCallChain(),
vcoubard 1131:692ddf04fc42 1328 disconnectionCallChain() {
vcoubard 1131:692ddf04fc42 1329 _advPayload.clear();
vcoubard 1131:692ddf04fc42 1330 _scanResponse.clear();
vcoubard 1131:692ddf04fc42 1331 }
vcoubard 1131:692ddf04fc42 1332
vcoubard 1131:692ddf04fc42 1333 /* Entry points for the underlying stack to report events back to the user. */
vcoubard 1131:692ddf04fc42 1334 public:
vcoubard 1135:22aada733dbd 1335 void processConnectionEvent(Handle_t handle,
vcoubard 1135:22aada733dbd 1336 Role_t role,
vcoubard 1135:22aada733dbd 1337 BLEProtocol::AddressType_t peerAddrType,
vcoubard 1135:22aada733dbd 1338 const BLEProtocol::AddressBytes_t peerAddr,
vcoubard 1135:22aada733dbd 1339 BLEProtocol::AddressType_t ownAddrType,
vcoubard 1135:22aada733dbd 1340 const BLEProtocol::AddressBytes_t ownAddr,
vcoubard 1135:22aada733dbd 1341 const ConnectionParams_t *connectionParams) {
vcoubard 1131:692ddf04fc42 1342 state.connected = 1;
vcoubard 1131:692ddf04fc42 1343 ConnectionCallbackParams_t callbackParams(handle, role, peerAddrType, peerAddr, ownAddrType, ownAddr, connectionParams);
vcoubard 1131:692ddf04fc42 1344 connectionCallChain.call(&callbackParams);
vcoubard 1131:692ddf04fc42 1345 }
vcoubard 1131:692ddf04fc42 1346
vcoubard 1131:692ddf04fc42 1347 void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
vcoubard 1131:692ddf04fc42 1348 state.connected = 0;
vcoubard 1131:692ddf04fc42 1349 DisconnectionCallbackParams_t callbackParams(handle, reason);
vcoubard 1131:692ddf04fc42 1350 disconnectionCallChain.call(&callbackParams);
vcoubard 1131:692ddf04fc42 1351 }
vcoubard 1131:692ddf04fc42 1352
vcoubard 1135:22aada733dbd 1353 void processAdvertisementReport(const BLEProtocol::AddressBytes_t peerAddr,
vcoubard 1135:22aada733dbd 1354 int8_t rssi,
vcoubard 1135:22aada733dbd 1355 bool isScanResponse,
vcoubard 1131:692ddf04fc42 1356 GapAdvertisingParams::AdvertisingType_t type,
vcoubard 1135:22aada733dbd 1357 uint8_t advertisingDataLen,
vcoubard 1135:22aada733dbd 1358 const uint8_t *advertisingData) {
vcoubard 1131:692ddf04fc42 1359 AdvertisementCallbackParams_t params;
vcoubard 1131:692ddf04fc42 1360 memcpy(params.peerAddr, peerAddr, ADDR_LEN);
vcoubard 1131:692ddf04fc42 1361 params.rssi = rssi;
vcoubard 1131:692ddf04fc42 1362 params.isScanResponse = isScanResponse;
vcoubard 1131:692ddf04fc42 1363 params.type = type;
vcoubard 1131:692ddf04fc42 1364 params.advertisingDataLen = advertisingDataLen;
vcoubard 1131:692ddf04fc42 1365 params.advertisingData = advertisingData;
vcoubard 1131:692ddf04fc42 1366 onAdvertisementReport.call(&params);
vcoubard 1131:692ddf04fc42 1367 }
vcoubard 1131:692ddf04fc42 1368
vcoubard 1131:692ddf04fc42 1369 void processTimeoutEvent(TimeoutSource_t source) {
vcoubard 1131:692ddf04fc42 1370 if (timeoutCallbackChain) {
vcoubard 1131:692ddf04fc42 1371 timeoutCallbackChain(source);
vcoubard 1131:692ddf04fc42 1372 }
vcoubard 1131:692ddf04fc42 1373 }
vcoubard 1131:692ddf04fc42 1374
vcoubard 1131:692ddf04fc42 1375 protected:
vcoubard 1131:692ddf04fc42 1376 GapAdvertisingParams _advParams;
vcoubard 1131:692ddf04fc42 1377 GapAdvertisingData _advPayload;
vcoubard 1131:692ddf04fc42 1378 GapScanningParams _scanningParams;
vcoubard 1131:692ddf04fc42 1379 GapAdvertisingData _scanResponse;
vcoubard 1131:692ddf04fc42 1380
vcoubard 1131:692ddf04fc42 1381 GapState_t state;
vcoubard 1131:692ddf04fc42 1382 bool scanningActive;
vcoubard 1131:692ddf04fc42 1383
vcoubard 1131:692ddf04fc42 1384 protected:
vcoubard 1131:692ddf04fc42 1385 TimeoutEventCallbackChain_t timeoutCallbackChain;
vcoubard 1131:692ddf04fc42 1386 RadioNotificationEventCallback_t radioNotificationCallback;
vcoubard 1131:692ddf04fc42 1387 AdvertisementReportCallback_t onAdvertisementReport;
vcoubard 1131:692ddf04fc42 1388 ConnectionEventCallbackChain_t connectionCallChain;
vcoubard 1131:692ddf04fc42 1389 DisconnectionEventCallbackChain_t disconnectionCallChain;
vcoubard 1131:692ddf04fc42 1390
vcoubard 1131:692ddf04fc42 1391 private:
vcoubard 1135:22aada733dbd 1392 GapShutdownCallbackChain_t shutdownCallChain;
vcoubard 1135:22aada733dbd 1393
vcoubard 1135:22aada733dbd 1394 private:
vcoubard 1131:692ddf04fc42 1395 /* Disallow copy and assignment. */
vcoubard 1131:692ddf04fc42 1396 Gap(const Gap &);
vcoubard 1131:692ddf04fc42 1397 Gap& operator=(const Gap &);
vcoubard 1131:692ddf04fc42 1398 };
vcoubard 1131:692ddf04fc42 1399
rgrover1 710:b2e1a2660ec2 1400 #endif // ifndef __GAP_H__