High level Bluetooth Low Energy API and radio abstraction layer

Dependents:   BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate BLE_ANCS_SDAPI_IRC ... more

Overview

The BLE_API is a high level abstraction for using Bluetooth Low Energy on multiple platforms. For details and examples using the BLE_API please see the BLE_API Summary Page. Or click on the API Documentation tab above.

Supported Services

Supported services can be found in the BLE_API/services folder.

Committer:
vcoubard
Date:
Mon Jan 11 08:52:04 2016 +0000
Revision:
1122:57dcf7dc2fe8
Parent:
1121:df91547290be
Child:
1123:685c954464e1
Synchronized with git rev 0b2ca7aa
Author: Andres Amaya Garcia
Add capacity to whitelist structure

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