Neil Johnson / microbit-ARMBand

Official Sheffield ARMBand micro:bit program

microbit/microbit-dal/BLE_API/ble/Gap.h@0:b9164b348919, 2016-10-17 (annotated)

Committer:
MrBedfordVan
Date:
Mon Oct 17 12:41:20 2016 +0000
Revision:
0:b9164b348919
Official Sheffield ARMBand Micro:bit program

Who changed what in which revision?

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