High level Bluetooth Low Energy API and radio abstraction layer

Fork of BLE_API by Bluetooth Low Energy

Committer:
vcoubard
Date:
Mon Jan 11 08:52:02 2016 +0000
Revision:
1118:88af68f0226b
Parent:
1117:421bdb7c5711
Child:
1119:7a487d506451
Synchronized with git rev 42a202e0
Author: Andres Amaya Garcia
Finilise Whitelisting experimental API

This is the finilised experimental API that introduces support for
whitelisting. The changes are focused in Gap and introduces the following
functions, that are expected to be implemented by each of the vendor specific
glue code (e.g. ble-nrf51822 module):

- getMaxWhitelistSize(): Get the maximum whitelist size, this can be set by
using a yotta config definition.
- getWhitelist(): Gets a copy of the internal whitelist containing BLE
addresses.
- setWhitelist(): Replace the whitelist with new addresses.
- setAdvertisingPolicyMode(), setScanningPolicyMode() and
setInitiatorPolicyMode(): Functions used to set the relevan policy filter
mode as described in the BLE Specification v4.2 Vol 6, Part B, Section 4.2.1.
- getAdvertisingPolicyMode(), getScanningPolicyMode() and
getInitiatorPolicyMode(): Functions used to get the relevan policy filter
mode as described in the BLE Specification v4.2 Vol 6, Part B, Section 4.2.1.

The following enumerators were added to Gap to describe the desired policy
filter mode:

- AdvertisingPolicyMode_t
- ScanningPolicyMode_t
- InitiatorPolicyMode_t

Finally, the following typedef was added to provide a view of the
underlying implementation's internal whitelist:

- Whitelist_t

**NOTE:** Clearly, these API additions require changes to the underlying
implementation!

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 1115:82d4a8a56d91 69 typedef BLEProtocol::AddressBytes_t Address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::Address_t instead. */
vcoubard 1115:82d4a8a56d91 70 typedef BLEProtocol::AddressBytes_t address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::Address_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 {
rgrover1 710:b2e1a2660ec2 144 uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 710:b2e1a2660ec2 145 uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 710:b2e1a2660ec2 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 1115:82d4a8a56d91 169 BLEProtocol::AddressBytes_t peerAddr;
vcoubard 1078:79c089630b38 170 BLEProtocol::AddressType_t ownAddrType;
vcoubard 1115:82d4a8a56d91 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 1079:6e2d9514f3df 229 * least significant byte first (LSB). Please refer to BLEProtocol::Address_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 1118:88af68f0226b 519 return BLE_ERROR_NOT_IMPLEMENTED;
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 1118:88af68f0226b 545 * @param[out] 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 1118:88af68f0226b 560 virtual ble_error_t setWhitelist(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 1079:6e2d9514f3df 1294 void processConnectionEvent(Handle_t handle,
vcoubard 1079:6e2d9514f3df 1295 Role_t role,
vcoubard 1079:6e2d9514f3df 1296 BLEProtocol::AddressType_t peerAddrType,
vcoubard 1115:82d4a8a56d91 1297 const BLEProtocol::AddressBytes_t peerAddr,
vcoubard 1079:6e2d9514f3df 1298 BLEProtocol::AddressType_t ownAddrType,
vcoubard 1115:82d4a8a56d91 1299 const BLEProtocol::AddressBytes_t ownAddr,
vcoubard 1079:6e2d9514f3df 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 1115:82d4a8a56d91 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__