Andrew Fox / BLE_API

add "LE Device Address" 0x1B to advertising data types

Fork of BLE_API by Bluetooth Low Energy

ble/Gap.h@1121:df91547290be, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:52:04 2016 +0000
Revision:
1121:df91547290be
Parent:
1119:7a487d506451
Child:
1122:57dcf7dc2fe8
Synchronized with git rev a488074d

Author: Andres Amaya Garcia

Change Whitelisting API according to comments

Who changed what in which revision?

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