erkin yucel / mbed-os

mbed os with nrf51 internal bandgap enabled to read battery level

Dependents:   BLE_file_test BLE_Blink ExternalEncoder

features/FEATURE_BLE/ble/Gap.h@0:f269e3021894, 2016-10-23 (annotated)

Committer:
elessair
Date:
Sun Oct 23 15:10:02 2016 +0000
Revision:
0:f269e3021894
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
elessair 0:f269e3021894 1 /* mbed Microcontroller Library
elessair 0:f269e3021894 2 * Copyright (c) 2006-2013 ARM Limited
elessair 0:f269e3021894 3 *
elessair 0:f269e3021894 4 * Licensed under the Apache License, Version 2.0 (the "License");
elessair 0:f269e3021894 5 * you may not use this file except in compliance with the License.
elessair 0:f269e3021894 6 * You may obtain a copy of the License at
elessair 0:f269e3021894 7 *
elessair 0:f269e3021894 8 * http://www.apache.org/licenses/LICENSE-2.0
elessair 0:f269e3021894 9 *
elessair 0:f269e3021894 10 * Unless required by applicable law or agreed to in writing, software
elessair 0:f269e3021894 11 * distributed under the License is distributed on an "AS IS" BASIS,
elessair 0:f269e3021894 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
elessair 0:f269e3021894 13 * See the License for the specific language governing permissions and
elessair 0:f269e3021894 14 * limitations under the License.
elessair 0:f269e3021894 15 */
elessair 0:f269e3021894 16
elessair 0:f269e3021894 17 #ifndef __GAP_H__
elessair 0:f269e3021894 18 #define __GAP_H__
elessair 0:f269e3021894 19
elessair 0:f269e3021894 20 #include "ble/BLEProtocol.h"
elessair 0:f269e3021894 21 #include "GapAdvertisingData.h"
elessair 0:f269e3021894 22 #include "GapAdvertisingParams.h"
elessair 0:f269e3021894 23 #include "GapScanningParams.h"
elessair 0:f269e3021894 24 #include "GapEvents.h"
elessair 0:f269e3021894 25 #include "CallChainOfFunctionPointersWithContext.h"
elessair 0:f269e3021894 26 #include "FunctionPointerWithContext.h"
elessair 0:f269e3021894 27 #include "deprecate.h"
elessair 0:f269e3021894 28
elessair 0:f269e3021894 29 /* Forward declarations for classes that will only be used for pointers or references in the following. */
elessair 0:f269e3021894 30 class GapAdvertisingParams;
elessair 0:f269e3021894 31 class GapScanningParams;
elessair 0:f269e3021894 32 class GapAdvertisingData;
elessair 0:f269e3021894 33
elessair 0:f269e3021894 34 class Gap {
elessair 0:f269e3021894 35 /*
elessair 0:f269e3021894 36 * DEPRECATION ALERT: all of the APIs in this `public` block are deprecated.
elessair 0:f269e3021894 37 * They have been relocated to the class BLEProtocol.
elessair 0:f269e3021894 38 */
elessair 0:f269e3021894 39 public:
elessair 0:f269e3021894 40 /**
elessair 0:f269e3021894 41 * Address-type for BLEProtocol addresses.
elessair 0:f269e3021894 42 *
elessair 0:f269e3021894 43 * @deprecated Use BLEProtocol::AddressType_t instead.
elessair 0:f269e3021894 44 */
elessair 0:f269e3021894 45 typedef BLEProtocol::AddressType_t AddressType_t;
elessair 0:f269e3021894 46
elessair 0:f269e3021894 47 /**
elessair 0:f269e3021894 48 * Address-type for BLEProtocol addresses.
elessair 0:f269e3021894 49 *
elessair 0:f269e3021894 50 * @deprecated Use BLEProtocol::AddressType_t instead.
elessair 0:f269e3021894 51 */
elessair 0:f269e3021894 52 typedef BLEProtocol::AddressType_t addr_type_t;
elessair 0:f269e3021894 53
elessair 0:f269e3021894 54 /**
elessair 0:f269e3021894 55 * Address-type for BLEProtocol addresses.
elessair 0:f269e3021894 56 *
elessair 0:f269e3021894 57 * @deprecated Use BLEProtocol::AddressType_t instead. The following
elessair 0:f269e3021894 58 * constants have been left in their deprecated state to
elessair 0:f269e3021894 59 * transparenly support existing applications which may have
elessair 0:f269e3021894 60 * used Gap::ADDR_TYPE_*.
elessair 0:f269e3021894 61 */
elessair 0:f269e3021894 62 enum DeprecatedAddressType_t {
elessair 0:f269e3021894 63 ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC,
elessair 0:f269e3021894 64 ADDR_TYPE_RANDOM_STATIC = BLEProtocol::AddressType::RANDOM_STATIC,
elessair 0:f269e3021894 65 ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_RESOLVABLE,
elessair 0:f269e3021894 66 ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE
elessair 0:f269e3021894 67 };
elessair 0:f269e3021894 68
elessair 0:f269e3021894 69 /**
elessair 0:f269e3021894 70 * Length (in octets) of the BLE MAC address.
elessair 0:f269e3021894 71 */
elessair 0:f269e3021894 72 static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN;
elessair 0:f269e3021894 73 /**
elessair 0:f269e3021894 74 * 48-bit address, LSB format.
elessair 0:f269e3021894 75 *
elessair 0:f269e3021894 76 * @deprecated Use BLEProtocol::AddressBytes_t instead.
elessair 0:f269e3021894 77 */
elessair 0:f269e3021894 78 typedef BLEProtocol::AddressBytes_t Address_t;
elessair 0:f269e3021894 79 /**
elessair 0:f269e3021894 80 * 48-bit address, LSB format.
elessair 0:f269e3021894 81 *
elessair 0:f269e3021894 82 * @deprecated Use BLEProtocol::AddressBytes_t instead.
elessair 0:f269e3021894 83 */
elessair 0:f269e3021894 84 typedef BLEProtocol::AddressBytes_t address_t;
elessair 0:f269e3021894 85
elessair 0:f269e3021894 86 public:
elessair 0:f269e3021894 87 /**
elessair 0:f269e3021894 88 * Enumeration for timeout sources.
elessair 0:f269e3021894 89 */
elessair 0:f269e3021894 90 enum TimeoutSource_t {
elessair 0:f269e3021894 91 TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */
elessair 0:f269e3021894 92 TIMEOUT_SRC_SECURITY_REQUEST = 0x01, /**< Security request timeout. */
elessair 0:f269e3021894 93 TIMEOUT_SRC_SCAN = 0x02, /**< Scanning timeout. */
elessair 0:f269e3021894 94 TIMEOUT_SRC_CONN = 0x03, /**< Connection timeout. */
elessair 0:f269e3021894 95 };
elessair 0:f269e3021894 96
elessair 0:f269e3021894 97 /**
elessair 0:f269e3021894 98 * Enumeration for disconnection reasons. The values for these reasons are
elessair 0:f269e3021894 99 * derived from Nordic's implementation, but the reasons are meant to be
elessair 0:f269e3021894 100 * independent of the transport. If you are returned a reason that is not
elessair 0:f269e3021894 101 * covered by this enumeration, please refer to the underlying
elessair 0:f269e3021894 102 * transport library.
elessair 0:f269e3021894 103 */
elessair 0:f269e3021894 104 enum DisconnectionReason_t {
elessair 0:f269e3021894 105 CONNECTION_TIMEOUT = 0x08,
elessair 0:f269e3021894 106 REMOTE_USER_TERMINATED_CONNECTION = 0x13,
elessair 0:f269e3021894 107 REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, /**< Remote device terminated connection due to low resources.*/
elessair 0:f269e3021894 108 REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /**< Remote device terminated connection due to power off. */
elessair 0:f269e3021894 109 LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
elessair 0:f269e3021894 110 CONN_INTERVAL_UNACCEPTABLE = 0x3B,
elessair 0:f269e3021894 111 };
elessair 0:f269e3021894 112
elessair 0:f269e3021894 113 /**
elessair 0:f269e3021894 114 * Enumeration for whitelist advertising policy filter modes. The possible
elessair 0:f269e3021894 115 * filter modes were obtained from the Bluetooth Core Specification
elessair 0:f269e3021894 116 * 4.2 (Vol. 6), Part B, Section 4.3.2.
elessair 0:f269e3021894 117 *
elessair 0:f269e3021894 118 * @experimental
elessair 0:f269e3021894 119 */
elessair 0:f269e3021894 120 enum AdvertisingPolicyMode_t {
elessair 0:f269e3021894 121 ADV_POLICY_IGNORE_WHITELIST = 0,
elessair 0:f269e3021894 122 ADV_POLICY_FILTER_SCAN_REQS = 1,
elessair 0:f269e3021894 123 ADV_POLICY_FILTER_CONN_REQS = 2,
elessair 0:f269e3021894 124 ADV_POLICY_FILTER_ALL_REQS = 3,
elessair 0:f269e3021894 125 };
elessair 0:f269e3021894 126
elessair 0:f269e3021894 127 /**
elessair 0:f269e3021894 128 * Enumeration for whitelist scanning policy filter modes. The possible
elessair 0:f269e3021894 129 * filter modes were obtained from the Bluetooth Core Specification
elessair 0:f269e3021894 130 * 4.2 (Vol. 6), Part B, Section 4.3.3.
elessair 0:f269e3021894 131 *
elessair 0:f269e3021894 132 * @experimental
elessair 0:f269e3021894 133 */
elessair 0:f269e3021894 134 enum ScanningPolicyMode_t {
elessair 0:f269e3021894 135 SCAN_POLICY_IGNORE_WHITELIST = 0,
elessair 0:f269e3021894 136 SCAN_POLICY_FILTER_ALL_ADV = 1,
elessair 0:f269e3021894 137 };
elessair 0:f269e3021894 138
elessair 0:f269e3021894 139 /**
elessair 0:f269e3021894 140 * Enumeration for the whitelist initiator policy fiter modes. The possible
elessair 0:f269e3021894 141 * filter modes were obtained from the Bluetooth Core Specification
elessair 0:f269e3021894 142 * 4.2 (vol. 6), Part B, Section 4.4.4.
elessair 0:f269e3021894 143 *
elessair 0:f269e3021894 144 * @experimental
elessair 0:f269e3021894 145 */
elessair 0:f269e3021894 146 enum InitiatorPolicyMode_t {
elessair 0:f269e3021894 147 INIT_POLICY_IGNORE_WHITELIST = 0,
elessair 0:f269e3021894 148 INIT_POLICY_FILTER_ALL_ADV = 1,
elessair 0:f269e3021894 149 };
elessair 0:f269e3021894 150
elessair 0:f269e3021894 151 /**
elessair 0:f269e3021894 152 * Representation of a Bluetooth Low Enery Whitelist containing addresses.
elessair 0:f269e3021894 153 *
elessair 0:f269e3021894 154 * @experimental
elessair 0:f269e3021894 155 */
elessair 0:f269e3021894 156 struct Whitelist_t {
elessair 0:f269e3021894 157 BLEProtocol::Address_t *addresses; /**< List of BLE addresses in the whitelist. */
elessair 0:f269e3021894 158 uint8_t size; /**< Total number of BLE addresses in this whitelist */
elessair 0:f269e3021894 159 uint8_t capacity; /**< Maximum number of BLE addresses that can be added to this whitelist. */
elessair 0:f269e3021894 160 };
elessair 0:f269e3021894 161
elessair 0:f269e3021894 162
elessair 0:f269e3021894 163 /**
elessair 0:f269e3021894 164 * Describes the current state of the device (more than one bit can be set).
elessair 0:f269e3021894 165 */
elessair 0:f269e3021894 166 struct GapState_t {
elessair 0:f269e3021894 167 unsigned advertising : 1; /**< Peripheral is currently advertising. */
elessair 0:f269e3021894 168 unsigned connected : 1; /**< Peripheral is connected to a central. */
elessair 0:f269e3021894 169 };
elessair 0:f269e3021894 170
elessair 0:f269e3021894 171 /**
elessair 0:f269e3021894 172 * Type for connection handle.
elessair 0:f269e3021894 173 */
elessair 0:f269e3021894 174 typedef uint16_t Handle_t;
elessair 0:f269e3021894 175
elessair 0:f269e3021894 176 /**
elessair 0:f269e3021894 177 * Structure containing GAP connection parameters. When in peripheral role
elessair 0:f269e3021894 178 * the connection parameters are suggestions. The choice of the connection
elessair 0:f269e3021894 179 * parameters is eventually up to the central.
elessair 0:f269e3021894 180 */
elessair 0:f269e3021894 181 typedef struct {
elessair 0:f269e3021894 182 uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see BLE_GAP_CP_LIMITS.*/
elessair 0:f269e3021894 183 uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see BLE_GAP_CP_LIMITS.*/
elessair 0:f269e3021894 184 uint16_t slaveLatency; /**< Slave Latency in number of connection events, see BLE_GAP_CP_LIMITS.*/
elessair 0:f269e3021894 185 uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see BLE_GAP_CP_LIMITS.*/
elessair 0:f269e3021894 186 } ConnectionParams_t;
elessair 0:f269e3021894 187
elessair 0:f269e3021894 188 /**
elessair 0:f269e3021894 189 * Enumeration for the possible GAP roles of a BLE device.
elessair 0:f269e3021894 190 */
elessair 0:f269e3021894 191 enum Role_t {
elessair 0:f269e3021894 192 PERIPHERAL = 0x1, /**< Peripheral Role. */
elessair 0:f269e3021894 193 CENTRAL = 0x2, /**< Central Role. */
elessair 0:f269e3021894 194 };
elessair 0:f269e3021894 195
elessair 0:f269e3021894 196 /**
elessair 0:f269e3021894 197 * Structure containing data and metadata of a scanned advertising packet.
elessair 0:f269e3021894 198 */
elessair 0:f269e3021894 199 struct AdvertisementCallbackParams_t {
elessair 0:f269e3021894 200 BLEProtocol::AddressBytes_t peerAddr; /**< The peer's BLE address. */
elessair 0:f269e3021894 201 int8_t rssi; /**< The advertisement packet RSSI value. */
elessair 0:f269e3021894 202 bool isScanResponse; /**< Whether this packet is the response to a scan request. */
elessair 0:f269e3021894 203 GapAdvertisingParams::AdvertisingType_t type; /**< The type of advertisement. */
elessair 0:f269e3021894 204 uint8_t advertisingDataLen; /**< Length of the advertisement data. */
elessair 0:f269e3021894 205 const uint8_t *advertisingData; /**< Pointer to the advertisement packet's data. */
elessair 0:f269e3021894 206 };
elessair 0:f269e3021894 207
elessair 0:f269e3021894 208 /**
elessair 0:f269e3021894 209 * Type for the handlers of advertisement callback events. Refer to
elessair 0:f269e3021894 210 * Gap::startScan().
elessair 0:f269e3021894 211 */
elessair 0:f269e3021894 212 typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> AdvertisementReportCallback_t;
elessair 0:f269e3021894 213
elessair 0:f269e3021894 214 /**
elessair 0:f269e3021894 215 * Encapsulates the parameters of a connection. This information is passed
elessair 0:f269e3021894 216 * to the registered handler of connection events. Refer to Gap::onConnection().
elessair 0:f269e3021894 217 */
elessair 0:f269e3021894 218 struct ConnectionCallbackParams_t {
elessair 0:f269e3021894 219 Handle_t handle; /**< The ID for this connection */
elessair 0:f269e3021894 220 Role_t role; /**< This device's role in the connection */
elessair 0:f269e3021894 221 BLEProtocol::AddressType_t peerAddrType; /**< The peer's BLE address type */
elessair 0:f269e3021894 222 BLEProtocol::AddressBytes_t peerAddr; /**< The peer's BLE address */
elessair 0:f269e3021894 223 BLEProtocol::AddressType_t ownAddrType; /**< This device's BLE address type */
elessair 0:f269e3021894 224 BLEProtocol::AddressBytes_t ownAddr; /**< This devices's BLE address */
elessair 0:f269e3021894 225 const ConnectionParams_t *connectionParams; /**< The currently configured connection parameters */
elessair 0:f269e3021894 226
elessair 0:f269e3021894 227 /**
elessair 0:f269e3021894 228 * Constructor for ConnectionCallbackParams_t.
elessair 0:f269e3021894 229 *
elessair 0:f269e3021894 230 * @param[in] handleIn
elessair 0:f269e3021894 231 * Value for ConnectionCallbackParams_t::handle
elessair 0:f269e3021894 232 * @param[in] roleIn
elessair 0:f269e3021894 233 * Value for ConnectionCallbackParams_t::role
elessair 0:f269e3021894 234 * @param[in] peerAddrTypeIn
elessair 0:f269e3021894 235 * Value for ConnectionCallbackParams_t::peerAddrType
elessair 0:f269e3021894 236 * @param[in] peerAddrIn
elessair 0:f269e3021894 237 * Value for ConnectionCallbackParams_t::peerAddr
elessair 0:f269e3021894 238 * @param[in] ownAddrTypeIn
elessair 0:f269e3021894 239 * Value for ConnectionCallbackParams_t::ownAddrType
elessair 0:f269e3021894 240 * @param[in] ownAddrIn
elessair 0:f269e3021894 241 * Value for ConnectionCallbackParams_t::ownAddr
elessair 0:f269e3021894 242 * @param[in] connectionParamsIn
elessair 0:f269e3021894 243 * Value for ConnectionCallbackParams_t::connectionParams
elessair 0:f269e3021894 244 */
elessair 0:f269e3021894 245 ConnectionCallbackParams_t(Handle_t handleIn,
elessair 0:f269e3021894 246 Role_t roleIn,
elessair 0:f269e3021894 247 BLEProtocol::AddressType_t peerAddrTypeIn,
elessair 0:f269e3021894 248 const uint8_t *peerAddrIn,
elessair 0:f269e3021894 249 BLEProtocol::AddressType_t ownAddrTypeIn,
elessair 0:f269e3021894 250 const uint8_t *ownAddrIn,
elessair 0:f269e3021894 251 const ConnectionParams_t *connectionParamsIn) :
elessair 0:f269e3021894 252 handle(handleIn),
elessair 0:f269e3021894 253 role(roleIn),
elessair 0:f269e3021894 254 peerAddrType(peerAddrTypeIn),
elessair 0:f269e3021894 255 peerAddr(),
elessair 0:f269e3021894 256 ownAddrType(ownAddrTypeIn),
elessair 0:f269e3021894 257 ownAddr(),
elessair 0:f269e3021894 258 connectionParams(connectionParamsIn) {
elessair 0:f269e3021894 259 memcpy(peerAddr, peerAddrIn, ADDR_LEN);
elessair 0:f269e3021894 260 memcpy(ownAddr, ownAddrIn, ADDR_LEN);
elessair 0:f269e3021894 261 }
elessair 0:f269e3021894 262 };
elessair 0:f269e3021894 263
elessair 0:f269e3021894 264 /**
elessair 0:f269e3021894 265 * Structure that encapsulates information about a disconnection event.
elessair 0:f269e3021894 266 * Refer to Gap::onDisconnection().
elessair 0:f269e3021894 267 */
elessair 0:f269e3021894 268 struct DisconnectionCallbackParams_t {
elessair 0:f269e3021894 269 Handle_t handle; /**< The ID of the connection that caused the disconnection event */
elessair 0:f269e3021894 270 DisconnectionReason_t reason; /**< The reason of the disconnection event */
elessair 0:f269e3021894 271
elessair 0:f269e3021894 272 /**
elessair 0:f269e3021894 273 * Constructor for DisconnectionCallbackParams_t.
elessair 0:f269e3021894 274 *
elessair 0:f269e3021894 275 * @param[in] handleIn
elessair 0:f269e3021894 276 * Value for DisconnectionCallbackParams_t::handle.
elessair 0:f269e3021894 277 * @param[in] reasonIn
elessair 0:f269e3021894 278 * Value for DisconnectionCallbackParams_t::reason.
elessair 0:f269e3021894 279 */
elessair 0:f269e3021894 280 DisconnectionCallbackParams_t(Handle_t handleIn,
elessair 0:f269e3021894 281 DisconnectionReason_t reasonIn) :
elessair 0:f269e3021894 282 handle(handleIn),
elessair 0:f269e3021894 283 reason(reasonIn)
elessair 0:f269e3021894 284 {}
elessair 0:f269e3021894 285 };
elessair 0:f269e3021894 286
elessair 0:f269e3021894 287 static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
elessair 0:f269e3021894 288 /**
elessair 0:f269e3021894 289 * Helper function to convert from units of milliseconds to GAP duration
elessair 0:f269e3021894 290 * units.
elessair 0:f269e3021894 291 *
elessair 0:f269e3021894 292 * @param[in] durationInMillis
elessair 0:f269e3021894 293 * The duration in milliseconds.
elessair 0:f269e3021894 294 *
elessair 0:f269e3021894 295 * @return The duration in GAP duration units.
elessair 0:f269e3021894 296 */
elessair 0:f269e3021894 297 static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
elessair 0:f269e3021894 298 return (durationInMillis * 1000) / UNIT_1_25_MS;
elessair 0:f269e3021894 299 }
elessair 0:f269e3021894 300
elessair 0:f269e3021894 301 /**
elessair 0:f269e3021894 302 * Type for the registered callbacks added to the timeout event callchain.
elessair 0:f269e3021894 303 * Refer to Gap::onTimeout().
elessair 0:f269e3021894 304 */
elessair 0:f269e3021894 305 typedef FunctionPointerWithContext<TimeoutSource_t> TimeoutEventCallback_t;
elessair 0:f269e3021894 306 /**
elessair 0:f269e3021894 307 * Type for the timeout event callchain. Refer to Gap::onTimeout().
elessair 0:f269e3021894 308 */
elessair 0:f269e3021894 309 typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> TimeoutEventCallbackChain_t;
elessair 0:f269e3021894 310
elessair 0:f269e3021894 311 /**
elessair 0:f269e3021894 312 * Type for the registered callbacks added to the connection event
elessair 0:f269e3021894 313 * callchain. Refer to Gap::onConnection().
elessair 0:f269e3021894 314 */
elessair 0:f269e3021894 315 typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallback_t;
elessair 0:f269e3021894 316 /**
elessair 0:f269e3021894 317 * Type for the connection event callchain. Refer to Gap::onConnection().
elessair 0:f269e3021894 318 */
elessair 0:f269e3021894 319 typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t;
elessair 0:f269e3021894 320
elessair 0:f269e3021894 321 /**
elessair 0:f269e3021894 322 * Type for the registered callbacks added to the disconnection event
elessair 0:f269e3021894 323 * callchain. Refer to Gap::onDisconnetion().
elessair 0:f269e3021894 324 */
elessair 0:f269e3021894 325 typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
elessair 0:f269e3021894 326 /**
elessair 0:f269e3021894 327 * Type for the disconnection event callchain. Refer to Gap::onDisconnection().
elessair 0:f269e3021894 328 */
elessair 0:f269e3021894 329 typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t;
elessair 0:f269e3021894 330
elessair 0:f269e3021894 331 /**
elessair 0:f269e3021894 332 * Type for the handlers of radio notification callback events. Refer to
elessair 0:f269e3021894 333 * Gap::onRadioNotification().
elessair 0:f269e3021894 334 */
elessair 0:f269e3021894 335 typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
elessair 0:f269e3021894 336
elessair 0:f269e3021894 337 /**
elessair 0:f269e3021894 338 * Type for the handlers of shutdown callback events. Refer to
elessair 0:f269e3021894 339 * Gap::onShutdown().
elessair 0:f269e3021894 340 */
elessair 0:f269e3021894 341 typedef FunctionPointerWithContext<const Gap *> GapShutdownCallback_t;
elessair 0:f269e3021894 342 /**
elessair 0:f269e3021894 343 * Type for the shutdown event callchain. Refer to Gap::onShutdown().
elessair 0:f269e3021894 344 */
elessair 0:f269e3021894 345 typedef CallChainOfFunctionPointersWithContext<const Gap *> GapShutdownCallbackChain_t;
elessair 0:f269e3021894 346
elessair 0:f269e3021894 347 /*
elessair 0:f269e3021894 348 * The following functions are meant to be overridden in the platform-specific sub-class.
elessair 0:f269e3021894 349 */
elessair 0:f269e3021894 350 public:
elessair 0:f269e3021894 351 /**
elessair 0:f269e3021894 352 * Set the BTLE MAC address and type. Please note that the address format is
elessair 0:f269e3021894 353 * least significant byte first (LSB). Please refer to BLEProtocol::AddressBytes_t.
elessair 0:f269e3021894 354 *
elessair 0:f269e3021894 355 * @param[in] type
elessair 0:f269e3021894 356 * The type of the BLE address to set.
elessair 0:f269e3021894 357 * @param[in] address
elessair 0:f269e3021894 358 * The BLE address to set.
elessair 0:f269e3021894 359 *
elessair 0:f269e3021894 360 * @return BLE_ERROR_NONE on success.
elessair 0:f269e3021894 361 */
elessair 0:f269e3021894 362 virtual ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
elessair 0:f269e3021894 363 /* avoid compiler warnings about unused variables */
elessair 0:f269e3021894 364 (void)type;
elessair 0:f269e3021894 365 (void)address;
elessair 0:f269e3021894 366
elessair 0:f269e3021894 367 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 368 }
elessair 0:f269e3021894 369
elessair 0:f269e3021894 370 /**
elessair 0:f269e3021894 371 * Fetch the BTLE MAC address and type.
elessair 0:f269e3021894 372 *
elessair 0:f269e3021894 373 * @param[out] typeP
elessair 0:f269e3021894 374 * The current BLE address type.
elessair 0:f269e3021894 375 * @param[out] address
elessair 0:f269e3021894 376 * The current BLE address.
elessair 0:f269e3021894 377 *
elessair 0:f269e3021894 378 * @return BLE_ERROR_NONE on success.
elessair 0:f269e3021894 379 */
elessair 0:f269e3021894 380 virtual ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
elessair 0:f269e3021894 381 /* Avoid compiler warnings about unused variables. */
elessair 0:f269e3021894 382 (void)typeP;
elessair 0:f269e3021894 383 (void)address;
elessair 0:f269e3021894 384
elessair 0:f269e3021894 385 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 386 }
elessair 0:f269e3021894 387
elessair 0:f269e3021894 388 /**
elessair 0:f269e3021894 389 * Get the minimum advertising interval in milliseconds for connectable
elessair 0:f269e3021894 390 * undirected and connectable directed event types supported by the
elessair 0:f269e3021894 391 * underlying BLE stack.
elessair 0:f269e3021894 392 *
elessair 0:f269e3021894 393 * @return Minimum Advertising interval in milliseconds for connectable
elessair 0:f269e3021894 394 * undirected and connectable directed event types.
elessair 0:f269e3021894 395 */
elessair 0:f269e3021894 396 virtual uint16_t getMinAdvertisingInterval(void) const {
elessair 0:f269e3021894 397 return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 398 }
elessair 0:f269e3021894 399
elessair 0:f269e3021894 400 /**
elessair 0:f269e3021894 401 * Get the minimum advertising interval in milliseconds for scannable
elessair 0:f269e3021894 402 * undirected and non-connectable undirected even types supported by the
elessair 0:f269e3021894 403 * underlying BLE stack.
elessair 0:f269e3021894 404 *
elessair 0:f269e3021894 405 * @return Minimum Advertising interval in milliseconds for scannable
elessair 0:f269e3021894 406 * undirected and non-connectable undirected event types.
elessair 0:f269e3021894 407 */
elessair 0:f269e3021894 408 virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const {
elessair 0:f269e3021894 409 return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 410 }
elessair 0:f269e3021894 411
elessair 0:f269e3021894 412 /**
elessair 0:f269e3021894 413 * Get the maximum advertising interval in milliseconds for all event types
elessair 0:f269e3021894 414 * supported by the underlying BLE stack.
elessair 0:f269e3021894 415 *
elessair 0:f269e3021894 416 * @return Maximum Advertising interval in milliseconds.
elessair 0:f269e3021894 417 */
elessair 0:f269e3021894 418 virtual uint16_t getMaxAdvertisingInterval(void) const {
elessair 0:f269e3021894 419 return 0xFFFF; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 420 }
elessair 0:f269e3021894 421
elessair 0:f269e3021894 422 /**
elessair 0:f269e3021894 423 * Stop advertising. The current advertising parameters remain in effect.
elessair 0:f269e3021894 424 *
elessair 0:f269e3021894 425 * @retval BLE_ERROR_NONE if successfully stopped advertising procedure.
elessair 0:f269e3021894 426 */
elessair 0:f269e3021894 427 virtual ble_error_t stopAdvertising(void) {
elessair 0:f269e3021894 428 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 429 }
elessair 0:f269e3021894 430
elessair 0:f269e3021894 431 /**
elessair 0:f269e3021894 432 * Stop scanning. The current scanning parameters remain in effect.
elessair 0:f269e3021894 433 *
elessair 0:f269e3021894 434 * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
elessair 0:f269e3021894 435 */
elessair 0:f269e3021894 436 virtual ble_error_t stopScan() {
elessair 0:f269e3021894 437 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 438 }
elessair 0:f269e3021894 439
elessair 0:f269e3021894 440 /**
elessair 0:f269e3021894 441 * Create a connection (GAP Link Establishment).
elessair 0:f269e3021894 442 *
elessair 0:f269e3021894 443 * @param[in] peerAddr
elessair 0:f269e3021894 444 * 48-bit address, LSB format.
elessair 0:f269e3021894 445 * @param[in] peerAddrType
elessair 0:f269e3021894 446 * Address type of the peer.
elessair 0:f269e3021894 447 * @param[in] connectionParams
elessair 0:f269e3021894 448 * Connection parameters.
elessair 0:f269e3021894 449 * @param[in] scanParams
elessair 0:f269e3021894 450 * Paramters to be used while scanning for the peer.
elessair 0:f269e3021894 451 *
elessair 0:f269e3021894 452 * @return BLE_ERROR_NONE if connection establishment procedure is started
elessair 0:f269e3021894 453 * successfully. The connectionCallChain (if set) will be invoked upon
elessair 0:f269e3021894 454 * a connection event.
elessair 0:f269e3021894 455 */
elessair 0:f269e3021894 456 virtual ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
elessair 0:f269e3021894 457 BLEProtocol::AddressType_t peerAddrType,
elessair 0:f269e3021894 458 const ConnectionParams_t *connectionParams,
elessair 0:f269e3021894 459 const GapScanningParams *scanParams) {
elessair 0:f269e3021894 460 /* Avoid compiler warnings about unused variables. */
elessair 0:f269e3021894 461 (void)peerAddr;
elessair 0:f269e3021894 462 (void)peerAddrType;
elessair 0:f269e3021894 463 (void)connectionParams;
elessair 0:f269e3021894 464 (void)scanParams;
elessair 0:f269e3021894 465
elessair 0:f269e3021894 466 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 467 }
elessair 0:f269e3021894 468
elessair 0:f269e3021894 469 /**
elessair 0:f269e3021894 470 * Create a connection (GAP Link Establishment).
elessair 0:f269e3021894 471 *
elessair 0:f269e3021894 472 * @deprecated This funtion overloads Gap::connect(const BLEProtocol::Address_t peerAddr,
elessair 0:f269e3021894 473 * BLEProtocol::AddressType_t peerAddrType,
elessair 0:f269e3021894 474 * const ConnectionParams_t *connectionParams,
elessair 0:f269e3021894 475 * const GapScanningParams *scanParams)
elessair 0:f269e3021894 476 * to maintain backward compatibility for change from Gap::AddressType_t to
elessair 0:f269e3021894 477 * BLEProtocol::AddressType_t.
elessair 0:f269e3021894 478 */
elessair 0:f269e3021894 479 ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
elessair 0:f269e3021894 480 DeprecatedAddressType_t peerAddrType,
elessair 0:f269e3021894 481 const ConnectionParams_t *connectionParams,
elessair 0:f269e3021894 482 const GapScanningParams *scanParams)
elessair 0:f269e3021894 483 __deprecated_message("Gap::DeprecatedAddressType_t is deprecated, use BLEProtocol::AddressType_t instead") {
elessair 0:f269e3021894 484 return connect(peerAddr, (BLEProtocol::AddressType_t) peerAddrType, connectionParams, scanParams);
elessair 0:f269e3021894 485 }
elessair 0:f269e3021894 486
elessair 0:f269e3021894 487 /**
elessair 0:f269e3021894 488 * This call initiates the disconnection procedure, and its completion will
elessair 0:f269e3021894 489 * be communicated to the application with an invocation of the
elessair 0:f269e3021894 490 * disconnectionCallback.
elessair 0:f269e3021894 491 *
elessair 0:f269e3021894 492 * @param[in] reason
elessair 0:f269e3021894 493 * The reason for disconnection; to be sent back to the peer.
elessair 0:f269e3021894 494 * @param[in] connectionHandle
elessair 0:f269e3021894 495 * The handle of the connection to disconnect from.
elessair 0:f269e3021894 496 *
elessair 0:f269e3021894 497 * @return BLE_ERROR_NONE if disconnection was successful.
elessair 0:f269e3021894 498 */
elessair 0:f269e3021894 499 virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
elessair 0:f269e3021894 500 /* avoid compiler warnings about unused variables */
elessair 0:f269e3021894 501 (void)connectionHandle;
elessair 0:f269e3021894 502 (void)reason;
elessair 0:f269e3021894 503
elessair 0:f269e3021894 504 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 505 }
elessair 0:f269e3021894 506
elessair 0:f269e3021894 507 /**
elessair 0:f269e3021894 508 * This call initiates the disconnection procedure, and its completion will
elessair 0:f269e3021894 509 * be communicated to the application with an invocation of the
elessair 0:f269e3021894 510 * disconnectionCallback.
elessair 0:f269e3021894 511 *
elessair 0:f269e3021894 512 * @param[in] reason
elessair 0:f269e3021894 513 * The reason for disconnection; to be sent back to the peer.
elessair 0:f269e3021894 514 *
elessair 0:f269e3021894 515 * @return BLE_ERROR_NONE if disconnection was successful.
elessair 0:f269e3021894 516 *
elessair 0:f269e3021894 517 * @deprecated This version of disconnect() doesn't take a connection handle. It
elessair 0:f269e3021894 518 * works reliably only for stacks that are limited to a single
elessair 0:f269e3021894 519 * connection. Use instead Gap::disconnect(Handle_t connectionHandle,
elessair 0:f269e3021894 520 * DisconnectionReason_t reason) instead.
elessair 0:f269e3021894 521 */
elessair 0:f269e3021894 522 virtual ble_error_t disconnect(DisconnectionReason_t reason) {
elessair 0:f269e3021894 523 /* Avoid compiler warnings about unused variables. */
elessair 0:f269e3021894 524 (void)reason;
elessair 0:f269e3021894 525
elessair 0:f269e3021894 526 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 527 }
elessair 0:f269e3021894 528
elessair 0:f269e3021894 529 /**
elessair 0:f269e3021894 530 * Get the GAP peripheral preferred connection parameters. These are the
elessair 0:f269e3021894 531 * defaults that the peripheral would like to have in a connection. The
elessair 0:f269e3021894 532 * choice of the connection parameters is eventually up to the central.
elessair 0:f269e3021894 533 *
elessair 0:f269e3021894 534 * @param[out] params
elessair 0:f269e3021894 535 * The structure where the parameters will be stored. Memory
elessair 0:f269e3021894 536 * for this is owned by the caller.
elessair 0:f269e3021894 537 *
elessair 0:f269e3021894 538 * @return BLE_ERROR_NONE if the parameters were successfully filled into
elessair 0:f269e3021894 539 * the given structure pointed to by params.
elessair 0:f269e3021894 540 */
elessair 0:f269e3021894 541 virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
elessair 0:f269e3021894 542 /* Avoid compiler warnings about unused variables. */
elessair 0:f269e3021894 543 (void)params;
elessair 0:f269e3021894 544
elessair 0:f269e3021894 545 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 546 }
elessair 0:f269e3021894 547
elessair 0:f269e3021894 548 /**
elessair 0:f269e3021894 549 * Set the GAP peripheral preferred connection parameters. These are the
elessair 0:f269e3021894 550 * defaults that the peripheral would like to have in a connection. The
elessair 0:f269e3021894 551 * choice of the connection parameters is eventually up to the central.
elessair 0:f269e3021894 552 *
elessair 0:f269e3021894 553 * @param[in] params
elessair 0:f269e3021894 554 * The structure containing the desired parameters.
elessair 0:f269e3021894 555 *
elessair 0:f269e3021894 556 * @return BLE_ERROR_NONE if the preferred connection params were set
elessair 0:f269e3021894 557 * correctly.
elessair 0:f269e3021894 558 */
elessair 0:f269e3021894 559 virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
elessair 0:f269e3021894 560 /* Avoid compiler warnings about unused variables. */
elessair 0:f269e3021894 561 (void)params;
elessair 0:f269e3021894 562
elessair 0:f269e3021894 563 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 564 }
elessair 0:f269e3021894 565
elessair 0:f269e3021894 566 /**
elessair 0:f269e3021894 567 * Update connection parameters. In the central role this will initiate a
elessair 0:f269e3021894 568 * Link Layer connection parameter update procedure. In the peripheral role,
elessair 0:f269e3021894 569 * this will send the corresponding L2CAP request and wait for the central
elessair 0:f269e3021894 570 * to perform the procedure.
elessair 0:f269e3021894 571 *
elessair 0:f269e3021894 572 * @param[in] handle
elessair 0:f269e3021894 573 * Connection Handle.
elessair 0:f269e3021894 574 * @param[in] params
elessair 0:f269e3021894 575 * Pointer to desired connection parameters. If NULL is provided on a peripheral role,
elessair 0:f269e3021894 576 * the parameters in the PPCP characteristic of the GAP service will be used instead.
elessair 0:f269e3021894 577 *
elessair 0:f269e3021894 578 * @return BLE_ERROR_NONE if the connection parameters were updated correctly.
elessair 0:f269e3021894 579 */
elessair 0:f269e3021894 580 virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) {
elessair 0:f269e3021894 581 /* avoid compiler warnings about unused variables */
elessair 0:f269e3021894 582 (void)handle;
elessair 0:f269e3021894 583 (void)params;
elessair 0:f269e3021894 584
elessair 0:f269e3021894 585 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 586 }
elessair 0:f269e3021894 587
elessair 0:f269e3021894 588 /**
elessair 0:f269e3021894 589 * Set the device name characteristic in the GAP service.
elessair 0:f269e3021894 590 *
elessair 0:f269e3021894 591 * @param[in] deviceName
elessair 0:f269e3021894 592 * The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
elessair 0:f269e3021894 593 *
elessair 0:f269e3021894 594 * @return BLE_ERROR_NONE if the device name was set correctly.
elessair 0:f269e3021894 595 */
elessair 0:f269e3021894 596 virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
elessair 0:f269e3021894 597 /* Avoid compiler warnings about unused variables. */
elessair 0:f269e3021894 598 (void)deviceName;
elessair 0:f269e3021894 599
elessair 0:f269e3021894 600 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 601 }
elessair 0:f269e3021894 602
elessair 0:f269e3021894 603 /**
elessair 0:f269e3021894 604 * Get the value of the device name characteristic in the GAP service.
elessair 0:f269e3021894 605 *
elessair 0:f269e3021894 606 * @param[out] deviceName
elessair 0:f269e3021894 607 * Pointer to an empty buffer where the UTF-8 *non NULL-
elessair 0:f269e3021894 608 * terminated* string will be placed. Set this
elessair 0:f269e3021894 609 * value to NULL in order to obtain the deviceName-length
elessair 0:f269e3021894 610 * from the 'length' parameter.
elessair 0:f269e3021894 611 *
elessair 0:f269e3021894 612 * @param[in,out] lengthP
elessair 0:f269e3021894 613 * (on input) Length of the buffer pointed to by deviceName;
elessair 0:f269e3021894 614 * (on output) the complete device name length (without the
elessair 0:f269e3021894 615 * null terminator).
elessair 0:f269e3021894 616 *
elessair 0:f269e3021894 617 * @return BLE_ERROR_NONE if the device name was fetched correctly from the
elessair 0:f269e3021894 618 * underlying BLE stack.
elessair 0:f269e3021894 619 *
elessair 0:f269e3021894 620 * @note If the device name is longer than the size of the supplied buffer,
elessair 0:f269e3021894 621 * length will return the complete device name length, and not the
elessair 0:f269e3021894 622 * number of bytes actually returned in deviceName. The application may
elessair 0:f269e3021894 623 * use this information to retry with a suitable buffer size.
elessair 0:f269e3021894 624 */
elessair 0:f269e3021894 625 virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
elessair 0:f269e3021894 626 /* avoid compiler warnings about unused variables */
elessair 0:f269e3021894 627 (void)deviceName;
elessair 0:f269e3021894 628 (void)lengthP;
elessair 0:f269e3021894 629
elessair 0:f269e3021894 630 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 631 }
elessair 0:f269e3021894 632
elessair 0:f269e3021894 633 /**
elessair 0:f269e3021894 634 * Set the appearance characteristic in the GAP service.
elessair 0:f269e3021894 635 *
elessair 0:f269e3021894 636 * @param[in] appearance
elessair 0:f269e3021894 637 * The new value for the device-appearance.
elessair 0:f269e3021894 638 *
elessair 0:f269e3021894 639 * @return BLE_ERROR_NONE if the new appearance was set correctly.
elessair 0:f269e3021894 640 */
elessair 0:f269e3021894 641 virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
elessair 0:f269e3021894 642 /* Avoid compiler warnings about unused variables. */
elessair 0:f269e3021894 643 (void)appearance;
elessair 0:f269e3021894 644
elessair 0:f269e3021894 645 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 646 }
elessair 0:f269e3021894 647
elessair 0:f269e3021894 648 /**
elessair 0:f269e3021894 649 * Get the appearance characteristic in the GAP service.
elessair 0:f269e3021894 650 *
elessair 0:f269e3021894 651 * @param[out] appearance
elessair 0:f269e3021894 652 * The current device-appearance value.
elessair 0:f269e3021894 653 *
elessair 0:f269e3021894 654 * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
elessair 0:f269e3021894 655 * from the underlying BLE stack.
elessair 0:f269e3021894 656 */
elessair 0:f269e3021894 657 virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
elessair 0:f269e3021894 658 /* Avoid compiler warnings about unused variables. */
elessair 0:f269e3021894 659 (void)appearanceP;
elessair 0:f269e3021894 660
elessair 0:f269e3021894 661 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 662 }
elessair 0:f269e3021894 663
elessair 0:f269e3021894 664 /**
elessair 0:f269e3021894 665 * Set the radio's transmit power.
elessair 0:f269e3021894 666 *
elessair 0:f269e3021894 667 * @param[in] txPower
elessair 0:f269e3021894 668 * Radio's transmit power in dBm.
elessair 0:f269e3021894 669 *
elessair 0:f269e3021894 670 * @return BLE_ERROR_NONE if the new radio's transmit power was set
elessair 0:f269e3021894 671 * correctly.
elessair 0:f269e3021894 672 */
elessair 0:f269e3021894 673 virtual ble_error_t setTxPower(int8_t txPower) {
elessair 0:f269e3021894 674 /* Avoid compiler warnings about unused variables. */
elessair 0:f269e3021894 675 (void)txPower;
elessair 0:f269e3021894 676
elessair 0:f269e3021894 677 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 678 }
elessair 0:f269e3021894 679
elessair 0:f269e3021894 680 /**
elessair 0:f269e3021894 681 * Query the underlying stack for permitted arguments for setTxPower().
elessair 0:f269e3021894 682 *
elessair 0:f269e3021894 683 * @param[out] valueArrayPP
elessair 0:f269e3021894 684 * Out parameter to receive the immutable array of Tx values.
elessair 0:f269e3021894 685 * @param[out] countP
elessair 0:f269e3021894 686 * Out parameter to receive the array's size.
elessair 0:f269e3021894 687 */
elessair 0:f269e3021894 688 virtual void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
elessair 0:f269e3021894 689 /* Avoid compiler warnings about unused variables. */
elessair 0:f269e3021894 690 (void)valueArrayPP;
elessair 0:f269e3021894 691 (void)countP;
elessair 0:f269e3021894 692
elessair 0:f269e3021894 693 *countP = 0; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 694 }
elessair 0:f269e3021894 695
elessair 0:f269e3021894 696 /**
elessair 0:f269e3021894 697 * Get the maximum size of the whitelist.
elessair 0:f269e3021894 698 *
elessair 0:f269e3021894 699 * @return Maximum size of the whitelist.
elessair 0:f269e3021894 700 *
elessair 0:f269e3021894 701 * @note If using mbed OS the size of the whitelist can be configured by
elessair 0:f269e3021894 702 * setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta
elessair 0:f269e3021894 703 * config file.
elessair 0:f269e3021894 704 *
elessair 0:f269e3021894 705 * @experimental
elessair 0:f269e3021894 706 */
elessair 0:f269e3021894 707 virtual uint8_t getMaxWhitelistSize(void) const
elessair 0:f269e3021894 708 {
elessair 0:f269e3021894 709 return 0;
elessair 0:f269e3021894 710 }
elessair 0:f269e3021894 711
elessair 0:f269e3021894 712 /**
elessair 0:f269e3021894 713 * Get the internal whitelist to be used by the Link Layer when scanning,
elessair 0:f269e3021894 714 * advertising or initiating a connection depending on the filter policies.
elessair 0:f269e3021894 715 *
elessair 0:f269e3021894 716 * @param[in,out] whitelist
elessair 0:f269e3021894 717 * (on input) whitelist.capacity contains the maximum number
elessair 0:f269e3021894 718 * of addresses to be returned.
elessair 0:f269e3021894 719 * (on output) The populated whitelist with copies of the
elessair 0:f269e3021894 720 * addresses in the implementation's whitelist.
elessair 0:f269e3021894 721 *
elessair 0:f269e3021894 722 * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
elessair 0:f269e3021894 723 * copied into the supplied reference.
elessair 0:f269e3021894 724 *
elessair 0:f269e3021894 725 * @experimental
elessair 0:f269e3021894 726 */
elessair 0:f269e3021894 727 virtual ble_error_t getWhitelist(Whitelist_t &whitelist) const
elessair 0:f269e3021894 728 {
elessair 0:f269e3021894 729 (void) whitelist;
elessair 0:f269e3021894 730 return BLE_ERROR_NOT_IMPLEMENTED;
elessair 0:f269e3021894 731 }
elessair 0:f269e3021894 732
elessair 0:f269e3021894 733 /**
elessair 0:f269e3021894 734 * Set the internal whitelist to be used by the Link Layer when scanning,
elessair 0:f269e3021894 735 * advertising or initiating a connection depending on the filter policies.
elessair 0:f269e3021894 736 *
elessair 0:f269e3021894 737 * @param[in] whitelist
elessair 0:f269e3021894 738 * A reference to a whitelist containing the addresses to
elessair 0:f269e3021894 739 * be added to the internal whitelist.
elessair 0:f269e3021894 740 *
elessair 0:f269e3021894 741 * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
elessair 0:f269e3021894 742 * populated with the addresses in the given whitelist.
elessair 0:f269e3021894 743 *
elessair 0:f269e3021894 744 * @note The whitelist must not contain addresses of type @ref
elessair 0:f269e3021894 745 * BLEProtocol::AddressType_t::RANDOM_PRIVATE_NON_RESOLVABLE, this
elessair 0:f269e3021894 746 * this will result in a @ref BLE_ERROR_INVALID_PARAM since the
elessair 0:f269e3021894 747 * remote peer might change its private address at any time and it
elessair 0:f269e3021894 748 * is not possible to resolve it.
elessair 0:f269e3021894 749 * @note If the input whitelist is larger than @ref getMaxWhitelistSize()
elessair 0:f269e3021894 750 * the @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned.
elessair 0:f269e3021894 751 *
elessair 0:f269e3021894 752 * @experimental
elessair 0:f269e3021894 753 */
elessair 0:f269e3021894 754 virtual ble_error_t setWhitelist(const Whitelist_t &whitelist)
elessair 0:f269e3021894 755 {
elessair 0:f269e3021894 756 (void) whitelist;
elessair 0:f269e3021894 757 return BLE_ERROR_NOT_IMPLEMENTED;
elessair 0:f269e3021894 758 }
elessair 0:f269e3021894 759
elessair 0:f269e3021894 760 /**
elessair 0:f269e3021894 761 * Set the advertising policy filter mode to be used in the next call
elessair 0:f269e3021894 762 * to startAdvertising().
elessair 0:f269e3021894 763 *
elessair 0:f269e3021894 764 * @param[in] mode
elessair 0:f269e3021894 765 * The new advertising policy filter mode.
elessair 0:f269e3021894 766 *
elessair 0:f269e3021894 767 * @return BLE_ERROR_NONE if the specified policy filter mode was set
elessair 0:f269e3021894 768 * successfully.
elessair 0:f269e3021894 769 *
elessair 0:f269e3021894 770 * @experimental
elessair 0:f269e3021894 771 */
elessair 0:f269e3021894 772 virtual ble_error_t setAdvertisingPolicyMode(AdvertisingPolicyMode_t mode)
elessair 0:f269e3021894 773 {
elessair 0:f269e3021894 774 (void) mode;
elessair 0:f269e3021894 775 return BLE_ERROR_NOT_IMPLEMENTED;
elessair 0:f269e3021894 776 }
elessair 0:f269e3021894 777
elessair 0:f269e3021894 778 /**
elessair 0:f269e3021894 779 * Set the scan policy filter mode to be used in the next call
elessair 0:f269e3021894 780 * to startScan().
elessair 0:f269e3021894 781 *
elessair 0:f269e3021894 782 * @param[in] mode
elessair 0:f269e3021894 783 * The new scan policy filter mode.
elessair 0:f269e3021894 784 *
elessair 0:f269e3021894 785 * @return BLE_ERROR_NONE if the specified policy filter mode was set
elessair 0:f269e3021894 786 * successfully.
elessair 0:f269e3021894 787 *
elessair 0:f269e3021894 788 * @experimental
elessair 0:f269e3021894 789 */
elessair 0:f269e3021894 790 virtual ble_error_t setScanningPolicyMode(ScanningPolicyMode_t mode)
elessair 0:f269e3021894 791 {
elessair 0:f269e3021894 792 (void) mode;
elessair 0:f269e3021894 793 return BLE_ERROR_NOT_IMPLEMENTED;
elessair 0:f269e3021894 794 }
elessair 0:f269e3021894 795
elessair 0:f269e3021894 796 /**
elessair 0:f269e3021894 797 * Set the initiator policy filter mode to be used.
elessair 0:f269e3021894 798 *
elessair 0:f269e3021894 799 * @param[in] mode
elessair 0:f269e3021894 800 * The new initiator policy filter mode.
elessair 0:f269e3021894 801 *
elessair 0:f269e3021894 802 * @return BLE_ERROR_NONE if the specified policy filter mode was set
elessair 0:f269e3021894 803 * successfully.
elessair 0:f269e3021894 804 *
elessair 0:f269e3021894 805 * @experimental
elessair 0:f269e3021894 806 */
elessair 0:f269e3021894 807 virtual ble_error_t setInitiatorPolicyMode(InitiatorPolicyMode_t mode)
elessair 0:f269e3021894 808 {
elessair 0:f269e3021894 809 (void) mode;
elessair 0:f269e3021894 810 return BLE_ERROR_NOT_IMPLEMENTED;
elessair 0:f269e3021894 811 }
elessair 0:f269e3021894 812
elessair 0:f269e3021894 813 /**
elessair 0:f269e3021894 814 * Get the advertising policy filter mode that will be used in the next
elessair 0:f269e3021894 815 * call to startAdvertising().
elessair 0:f269e3021894 816 *
elessair 0:f269e3021894 817 * @return The set advertising policy filter mode.
elessair 0:f269e3021894 818 *
elessair 0:f269e3021894 819 * @experimental
elessair 0:f269e3021894 820 */
elessair 0:f269e3021894 821 virtual AdvertisingPolicyMode_t getAdvertisingPolicyMode(void) const
elessair 0:f269e3021894 822 {
elessair 0:f269e3021894 823 return ADV_POLICY_IGNORE_WHITELIST;
elessair 0:f269e3021894 824 }
elessair 0:f269e3021894 825
elessair 0:f269e3021894 826 /**
elessair 0:f269e3021894 827 * Get the scan policy filter mode that will be used in the next
elessair 0:f269e3021894 828 * call to startScan().
elessair 0:f269e3021894 829 *
elessair 0:f269e3021894 830 * @return The set scan policy filter mode.
elessair 0:f269e3021894 831 *
elessair 0:f269e3021894 832 * @experimental
elessair 0:f269e3021894 833 */
elessair 0:f269e3021894 834 virtual ScanningPolicyMode_t getScanningPolicyMode(void) const
elessair 0:f269e3021894 835 {
elessair 0:f269e3021894 836 return SCAN_POLICY_IGNORE_WHITELIST;
elessair 0:f269e3021894 837 }
elessair 0:f269e3021894 838
elessair 0:f269e3021894 839 /**
elessair 0:f269e3021894 840 * Get the initiator policy filter mode that will be used.
elessair 0:f269e3021894 841 *
elessair 0:f269e3021894 842 * @return The set scan policy filter mode.
elessair 0:f269e3021894 843 *
elessair 0:f269e3021894 844 * @experimental
elessair 0:f269e3021894 845 */
elessair 0:f269e3021894 846 virtual InitiatorPolicyMode_t getInitiatorPolicyMode(void) const
elessair 0:f269e3021894 847 {
elessair 0:f269e3021894 848 return INIT_POLICY_IGNORE_WHITELIST;
elessair 0:f269e3021894 849 }
elessair 0:f269e3021894 850
elessair 0:f269e3021894 851 protected:
elessair 0:f269e3021894 852 /* Override the following in the underlying adaptation layer to provide the functionality of scanning. */
elessair 0:f269e3021894 853
elessair 0:f269e3021894 854 /**
elessair 0:f269e3021894 855 * Start scanning procedure in the underlying BLE stack.
elessair 0:f269e3021894 856 *
elessair 0:f269e3021894 857 * @param[in] scanningParams
elessair 0:f269e3021894 858 * The GAP scanning parameters.
elessair 0:f269e3021894 859 *
elessair 0:f269e3021894 860 * @return BLE_ERROR_NONE if the scan procedure started successfully.
elessair 0:f269e3021894 861 */
elessair 0:f269e3021894 862 virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams) {
elessair 0:f269e3021894 863 (void)scanningParams;
elessair 0:f269e3021894 864 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 865 }
elessair 0:f269e3021894 866
elessair 0:f269e3021894 867 /*
elessair 0:f269e3021894 868 * APIs with non-virtual implementations.
elessair 0:f269e3021894 869 */
elessair 0:f269e3021894 870 public:
elessair 0:f269e3021894 871 /**
elessair 0:f269e3021894 872 * Get the current GAP state of the device using a bitmask that
elessair 0:f269e3021894 873 * describes whether the device is advertising or connected.
elessair 0:f269e3021894 874 *
elessair 0:f269e3021894 875 * @return The current GAP state of the device.
elessair 0:f269e3021894 876 */
elessair 0:f269e3021894 877 GapState_t getState(void) const {
elessair 0:f269e3021894 878 return state;
elessair 0:f269e3021894 879 }
elessair 0:f269e3021894 880
elessair 0:f269e3021894 881 /**
elessair 0:f269e3021894 882 * Set the GAP advertising mode to use for this device.
elessair 0:f269e3021894 883 *
elessair 0:f269e3021894 884 * @param[in] advType
elessair 0:f269e3021894 885 * The new type of the advertising packets.
elessair 0:f269e3021894 886 */
elessair 0:f269e3021894 887 void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType) {
elessair 0:f269e3021894 888 _advParams.setAdvertisingType(advType);
elessair 0:f269e3021894 889 }
elessair 0:f269e3021894 890
elessair 0:f269e3021894 891 /**
elessair 0:f269e3021894 892 * Set the advertising interval.
elessair 0:f269e3021894 893 *
elessair 0:f269e3021894 894 * @param[in] interval
elessair 0:f269e3021894 895 * Advertising interval in units of milliseconds. Advertising
elessair 0:f269e3021894 896 * is disabled if interval is 0. If interval is smaller than
elessair 0:f269e3021894 897 * the minimum supported value, then the minimum supported
elessair 0:f269e3021894 898 * value is used instead. This minimum value can be discovered
elessair 0:f269e3021894 899 * using getMinAdvertisingInterval().
elessair 0:f269e3021894 900 *
elessair 0:f269e3021894 901 * This field must be set to 0 if connectionMode is equal
elessair 0:f269e3021894 902 * to ADV_CONNECTABLE_DIRECTED.
elessair 0:f269e3021894 903 *
elessair 0:f269e3021894 904 * @note Decreasing this value will allow central devices to detect a
elessair 0:f269e3021894 905 * peripheral faster, at the expense of more power being used by the radio
elessair 0:f269e3021894 906 * due to the higher data transmit rate.
elessair 0:f269e3021894 907 *
elessair 0:f269e3021894 908 * @note [WARNING] This API previously used 0.625ms as the unit for its
elessair 0:f269e3021894 909 * @p interval argument. That required an explicit conversion from
elessair 0:f269e3021894 910 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
elessair 0:f269e3021894 911 * no longer required as the new units are milliseconds. Any application
elessair 0:f269e3021894 912 * code depending on the old semantics needs to be updated accordingly.
elessair 0:f269e3021894 913 */
elessair 0:f269e3021894 914 void setAdvertisingInterval(uint16_t interval) {
elessair 0:f269e3021894 915 if (interval == 0) {
elessair 0:f269e3021894 916 stopAdvertising();
elessair 0:f269e3021894 917 } else if (interval < getMinAdvertisingInterval()) {
elessair 0:f269e3021894 918 interval = getMinAdvertisingInterval();
elessair 0:f269e3021894 919 }
elessair 0:f269e3021894 920 _advParams.setInterval(interval);
elessair 0:f269e3021894 921 }
elessair 0:f269e3021894 922
elessair 0:f269e3021894 923 /**
elessair 0:f269e3021894 924 * Set the advertising timeout. The length of time to advertise for before
elessair 0:f269e3021894 925 * a timeout event is generated.
elessair 0:f269e3021894 926 *
elessair 0:f269e3021894 927 * @param[in] timeout
elessair 0:f269e3021894 928 * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
elessair 0:f269e3021894 929 * and 16383). Use 0 to disable the advertising timeout.
elessair 0:f269e3021894 930 */
elessair 0:f269e3021894 931 void setAdvertisingTimeout(uint16_t timeout) {
elessair 0:f269e3021894 932 _advParams.setTimeout(timeout);
elessair 0:f269e3021894 933 }
elessair 0:f269e3021894 934
elessair 0:f269e3021894 935 /**
elessair 0:f269e3021894 936 * Start advertising.
elessair 0:f269e3021894 937 *
elessair 0:f269e3021894 938 * @return BLE_ERROR_NONE if the device started advertising successfully.
elessair 0:f269e3021894 939 */
elessair 0:f269e3021894 940 ble_error_t startAdvertising(void) {
elessair 0:f269e3021894 941 ble_error_t rc;
elessair 0:f269e3021894 942 if ((rc = startAdvertising(_advParams)) == BLE_ERROR_NONE) {
elessair 0:f269e3021894 943 state.advertising = 1;
elessair 0:f269e3021894 944 }
elessair 0:f269e3021894 945 return rc;
elessair 0:f269e3021894 946 }
elessair 0:f269e3021894 947
elessair 0:f269e3021894 948 /**
elessair 0:f269e3021894 949 * Reset any advertising payload prepared from prior calls to
elessair 0:f269e3021894 950 * accumulateAdvertisingPayload(). This automatically propagates the re-
elessair 0:f269e3021894 951 * initialized advertising payload to the underlying stack.
elessair 0:f269e3021894 952 */
elessair 0:f269e3021894 953 void clearAdvertisingPayload(void) {
elessair 0:f269e3021894 954 _advPayload.clear();
elessair 0:f269e3021894 955 setAdvertisingData(_advPayload, _scanResponse);
elessair 0:f269e3021894 956 }
elessair 0:f269e3021894 957
elessair 0:f269e3021894 958 /**
elessair 0:f269e3021894 959 * Accumulate an AD structure in the advertising payload. Please note that
elessair 0:f269e3021894 960 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
elessair 0:f269e3021894 961 * as an additional 31 bytes if the advertising payload is too
elessair 0:f269e3021894 962 * small.
elessair 0:f269e3021894 963 *
elessair 0:f269e3021894 964 * @param[in] flags
elessair 0:f269e3021894 965 * The flags to be added. Please refer to
elessair 0:f269e3021894 966 * GapAdvertisingData::Flags for valid flags. Multiple
elessair 0:f269e3021894 967 * flags may be specified in combination.
elessair 0:f269e3021894 968 *
elessair 0:f269e3021894 969 * @return BLE_ERROR_NONE if the data was successfully added to the
elessair 0:f269e3021894 970 * advertising payload.
elessair 0:f269e3021894 971 */
elessair 0:f269e3021894 972 ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
elessair 0:f269e3021894 973 GapAdvertisingData advPayloadCopy = _advPayload;
elessair 0:f269e3021894 974 ble_error_t rc;
elessair 0:f269e3021894 975 if ((rc = advPayloadCopy.addFlags(flags)) != BLE_ERROR_NONE) {
elessair 0:f269e3021894 976 return rc;
elessair 0:f269e3021894 977 }
elessair 0:f269e3021894 978
elessair 0:f269e3021894 979 rc = setAdvertisingData(advPayloadCopy, _scanResponse);
elessair 0:f269e3021894 980 if (rc == BLE_ERROR_NONE) {
elessair 0:f269e3021894 981 _advPayload = advPayloadCopy;
elessair 0:f269e3021894 982 }
elessair 0:f269e3021894 983
elessair 0:f269e3021894 984 return rc;
elessair 0:f269e3021894 985 }
elessair 0:f269e3021894 986
elessair 0:f269e3021894 987 /**
elessair 0:f269e3021894 988 * Accumulate an AD structure in the advertising payload. Please note that
elessair 0:f269e3021894 989 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
elessair 0:f269e3021894 990 * as an additional 31 bytes if the advertising payload is too
elessair 0:f269e3021894 991 * small.
elessair 0:f269e3021894 992 *
elessair 0:f269e3021894 993 * @param[in] app
elessair 0:f269e3021894 994 * The appearance of the peripheral.
elessair 0:f269e3021894 995 *
elessair 0:f269e3021894 996 * @return BLE_ERROR_NONE if the data was successfully added to the
elessair 0:f269e3021894 997 * advertising payload.
elessair 0:f269e3021894 998 */
elessair 0:f269e3021894 999 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
elessair 0:f269e3021894 1000 GapAdvertisingData advPayloadCopy = _advPayload;
elessair 0:f269e3021894 1001 ble_error_t rc;
elessair 0:f269e3021894 1002 if ((rc = advPayloadCopy.addAppearance(app)) != BLE_ERROR_NONE) {
elessair 0:f269e3021894 1003 return rc;
elessair 0:f269e3021894 1004 }
elessair 0:f269e3021894 1005
elessair 0:f269e3021894 1006 rc = setAdvertisingData(advPayloadCopy, _scanResponse);
elessair 0:f269e3021894 1007 if (rc == BLE_ERROR_NONE) {
elessair 0:f269e3021894 1008 _advPayload = advPayloadCopy;
elessair 0:f269e3021894 1009 }
elessair 0:f269e3021894 1010
elessair 0:f269e3021894 1011 return rc;
elessair 0:f269e3021894 1012 }
elessair 0:f269e3021894 1013
elessair 0:f269e3021894 1014 /**
elessair 0:f269e3021894 1015 * Accumulate an AD structure in the advertising payload. Please note that
elessair 0:f269e3021894 1016 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
elessair 0:f269e3021894 1017 * as an additional 31 bytes if the advertising payload is too
elessair 0:f269e3021894 1018 * small.
elessair 0:f269e3021894 1019 *
elessair 0:f269e3021894 1020 * @param[in] power
elessair 0:f269e3021894 1021 * The max transmit power to be used by the controller (in dBm).
elessair 0:f269e3021894 1022 *
elessair 0:f269e3021894 1023 * @return BLE_ERROR_NONE if the data was successfully added to the
elessair 0:f269e3021894 1024 * advertising payload.
elessair 0:f269e3021894 1025 */
elessair 0:f269e3021894 1026 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
elessair 0:f269e3021894 1027 GapAdvertisingData advPayloadCopy = _advPayload;
elessair 0:f269e3021894 1028 ble_error_t rc;
elessair 0:f269e3021894 1029 if ((rc = advPayloadCopy.addTxPower(power)) != BLE_ERROR_NONE) {
elessair 0:f269e3021894 1030 return rc;
elessair 0:f269e3021894 1031 }
elessair 0:f269e3021894 1032
elessair 0:f269e3021894 1033 rc = setAdvertisingData(advPayloadCopy, _scanResponse);
elessair 0:f269e3021894 1034 if (rc == BLE_ERROR_NONE) {
elessair 0:f269e3021894 1035 _advPayload = advPayloadCopy;
elessair 0:f269e3021894 1036 }
elessair 0:f269e3021894 1037
elessair 0:f269e3021894 1038 return rc;
elessair 0:f269e3021894 1039 }
elessair 0:f269e3021894 1040
elessair 0:f269e3021894 1041 /**
elessair 0:f269e3021894 1042 * Accumulate a variable length byte-stream as an AD structure in the
elessair 0:f269e3021894 1043 * advertising payload. Please note that the payload is limited to 31 bytes.
elessair 0:f269e3021894 1044 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
elessair 0:f269e3021894 1045 * advertising payload is too small.
elessair 0:f269e3021894 1046 *
elessair 0:f269e3021894 1047 * @param[in] type
elessair 0:f269e3021894 1048 * The type describing the variable length data.
elessair 0:f269e3021894 1049 * @param[in] data
elessair 0:f269e3021894 1050 * Data bytes.
elessair 0:f269e3021894 1051 * @param[in] len
elessair 0:f269e3021894 1052 * Length of data.
elessair 0:f269e3021894 1053 *
elessair 0:f269e3021894 1054 * @return BLE_ERROR_NONE if the advertisement payload was updated based on
elessair 0:f269e3021894 1055 * matching AD type; otherwise, an appropriate error.
elessair 0:f269e3021894 1056 *
elessair 0:f269e3021894 1057 * @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS,
elessair 0:f269e3021894 1058 * COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS,
elessair 0:f269e3021894 1059 * COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS,
elessair 0:f269e3021894 1060 * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the
elessair 0:f269e3021894 1061 * supplied value is appended to the values previously added to the
elessair 0:f269e3021894 1062 * payload.
elessair 0:f269e3021894 1063 */
elessair 0:f269e3021894 1064 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
elessair 0:f269e3021894 1065 GapAdvertisingData advPayloadCopy = _advPayload;
elessair 0:f269e3021894 1066 ble_error_t rc;
elessair 0:f269e3021894 1067 if ((rc = advPayloadCopy.addData(type, data, len)) != BLE_ERROR_NONE) {
elessair 0:f269e3021894 1068 return rc;
elessair 0:f269e3021894 1069 }
elessair 0:f269e3021894 1070
elessair 0:f269e3021894 1071 rc = setAdvertisingData(advPayloadCopy, _scanResponse);
elessair 0:f269e3021894 1072 if (rc == BLE_ERROR_NONE) {
elessair 0:f269e3021894 1073 _advPayload = advPayloadCopy;
elessair 0:f269e3021894 1074 }
elessair 0:f269e3021894 1075
elessair 0:f269e3021894 1076 return rc;
elessair 0:f269e3021894 1077 }
elessair 0:f269e3021894 1078
elessair 0:f269e3021894 1079 /**
elessair 0:f269e3021894 1080 * Update a particular ADV field in the advertising payload (based on
elessair 0:f269e3021894 1081 * matching type).
elessair 0:f269e3021894 1082 *
elessair 0:f269e3021894 1083 * @param[in] type
elessair 0:f269e3021894 1084 * The ADV type field describing the variable length data.
elessair 0:f269e3021894 1085 * @param[in] data
elessair 0:f269e3021894 1086 * Data bytes.
elessair 0:f269e3021894 1087 * @param[in] len
elessair 0:f269e3021894 1088 * Length of data.
elessair 0:f269e3021894 1089 *
elessair 0:f269e3021894 1090 * @note If advertisements are enabled, then the update will take effect immediately.
elessair 0:f269e3021894 1091 *
elessair 0:f269e3021894 1092 * @return BLE_ERROR_NONE if the advertisement payload was updated based on
elessair 0:f269e3021894 1093 * matching AD type; otherwise, an appropriate error.
elessair 0:f269e3021894 1094 */
elessair 0:f269e3021894 1095 ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
elessair 0:f269e3021894 1096 GapAdvertisingData advPayloadCopy = _advPayload;
elessair 0:f269e3021894 1097 ble_error_t rc;
elessair 0:f269e3021894 1098 if ((rc = advPayloadCopy.updateData(type, data, len)) != BLE_ERROR_NONE) {
elessair 0:f269e3021894 1099 return rc;
elessair 0:f269e3021894 1100 }
elessair 0:f269e3021894 1101
elessair 0:f269e3021894 1102 rc = setAdvertisingData(advPayloadCopy, _scanResponse);
elessair 0:f269e3021894 1103 if (rc == BLE_ERROR_NONE) {
elessair 0:f269e3021894 1104 _advPayload = advPayloadCopy;
elessair 0:f269e3021894 1105 }
elessair 0:f269e3021894 1106
elessair 0:f269e3021894 1107 return rc;
elessair 0:f269e3021894 1108 }
elessair 0:f269e3021894 1109
elessair 0:f269e3021894 1110 /**
elessair 0:f269e3021894 1111 * Set up a particular, user-constructed advertisement payload for the
elessair 0:f269e3021894 1112 * underlying stack. It would be uncommon for this API to be used directly;
elessair 0:f269e3021894 1113 * there are other APIs to build an advertisement payload (refer to
elessair 0:f269e3021894 1114 * Gap::accumulateAdvertisingPayload()).
elessair 0:f269e3021894 1115 *
elessair 0:f269e3021894 1116 * @param[in] payload
elessair 0:f269e3021894 1117 * A reference to a user constructed advertisement
elessair 0:f269e3021894 1118 * payload.
elessair 0:f269e3021894 1119 *
elessair 0:f269e3021894 1120 * @return BLE_ERROR_NONE if the advertisement payload was successfully
elessair 0:f269e3021894 1121 * set.
elessair 0:f269e3021894 1122 */
elessair 0:f269e3021894 1123 ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) {
elessair 0:f269e3021894 1124 ble_error_t rc = setAdvertisingData(payload, _scanResponse);
elessair 0:f269e3021894 1125 if (rc == BLE_ERROR_NONE) {
elessair 0:f269e3021894 1126 _advPayload = payload;
elessair 0:f269e3021894 1127 }
elessair 0:f269e3021894 1128
elessair 0:f269e3021894 1129 return rc;
elessair 0:f269e3021894 1130 }
elessair 0:f269e3021894 1131
elessair 0:f269e3021894 1132 /**
elessair 0:f269e3021894 1133 * Get a reference to the advertising payload.
elessair 0:f269e3021894 1134 *
elessair 0:f269e3021894 1135 * @return Read back advertising data.
elessair 0:f269e3021894 1136 *
elessair 0:f269e3021894 1137 * @note Useful for storing and restoring payload.
elessair 0:f269e3021894 1138 */
elessair 0:f269e3021894 1139 const GapAdvertisingData &getAdvertisingPayload(void) const {
elessair 0:f269e3021894 1140 return _advPayload;
elessair 0:f269e3021894 1141 }
elessair 0:f269e3021894 1142
elessair 0:f269e3021894 1143 /**
elessair 0:f269e3021894 1144 * Accumulate a variable length byte-stream as an AD structure in the
elessair 0:f269e3021894 1145 * scanResponse payload.
elessair 0:f269e3021894 1146 *
elessair 0:f269e3021894 1147 * @param[in] type
elessair 0:f269e3021894 1148 * The type describing the variable length data.
elessair 0:f269e3021894 1149 * @param[in] data
elessair 0:f269e3021894 1150 * Data bytes.
elessair 0:f269e3021894 1151 * @param[in] len
elessair 0:f269e3021894 1152 * Length of data.
elessair 0:f269e3021894 1153 *
elessair 0:f269e3021894 1154 * @return BLE_ERROR_NONE if the data was successfully added to the scan
elessair 0:f269e3021894 1155 * response payload.
elessair 0:f269e3021894 1156 */
elessair 0:f269e3021894 1157 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
elessair 0:f269e3021894 1158 GapAdvertisingData scanResponseCopy = _scanResponse;
elessair 0:f269e3021894 1159 ble_error_t rc;
elessair 0:f269e3021894 1160 if ((rc = scanResponseCopy.addData(type, data, len)) != BLE_ERROR_NONE) {
elessair 0:f269e3021894 1161 return rc;
elessair 0:f269e3021894 1162 }
elessair 0:f269e3021894 1163
elessair 0:f269e3021894 1164 rc = setAdvertisingData(_advPayload, scanResponseCopy);
elessair 0:f269e3021894 1165 if (rc == BLE_ERROR_NONE) {
elessair 0:f269e3021894 1166 _scanResponse = scanResponseCopy;
elessair 0:f269e3021894 1167 }
elessair 0:f269e3021894 1168
elessair 0:f269e3021894 1169 return rc;
elessair 0:f269e3021894 1170 }
elessair 0:f269e3021894 1171
elessair 0:f269e3021894 1172 /**
elessair 0:f269e3021894 1173 * Reset any scan response prepared from prior calls to
elessair 0:f269e3021894 1174 * Gap::accumulateScanResponse().
elessair 0:f269e3021894 1175 *
elessair 0:f269e3021894 1176 * @note This should be followed by a call to Gap::setAdvertisingPayload() or
elessair 0:f269e3021894 1177 * Gap::startAdvertising() before the update takes effect.
elessair 0:f269e3021894 1178 */
elessair 0:f269e3021894 1179 void clearScanResponse(void) {
elessair 0:f269e3021894 1180 _scanResponse.clear();
elessair 0:f269e3021894 1181 setAdvertisingData(_advPayload, _scanResponse);
elessair 0:f269e3021894 1182 }
elessair 0:f269e3021894 1183
elessair 0:f269e3021894 1184 /**
elessair 0:f269e3021894 1185 * Set up parameters for GAP scanning (observer mode).
elessair 0:f269e3021894 1186 *
elessair 0:f269e3021894 1187 * @param[in] interval
elessair 0:f269e3021894 1188 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
elessair 0:f269e3021894 1189 * @param[in] window
elessair 0:f269e3021894 1190 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
elessair 0:f269e3021894 1191 * @param[in] timeout
elessair 0:f269e3021894 1192 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
elessair 0:f269e3021894 1193 * @param[in] activeScanning
elessair 0:f269e3021894 1194 * Set to True if active-scanning is required. This is used to fetch the
elessair 0:f269e3021894 1195 * scan response from a peer if possible.
elessair 0:f269e3021894 1196 *
elessair 0:f269e3021894 1197 * @return BLE_ERROR_NONE if the scan parameters were correctly set.
elessair 0:f269e3021894 1198 *
elessair 0:f269e3021894 1199 * @note The scanning window divided by the interval determines the duty cycle for
elessair 0:f269e3021894 1200 * scanning. For example, if the interval is 100ms and the window is 10ms,
elessair 0:f269e3021894 1201 * then the controller will scan for 10 percent of the time. It is possible
elessair 0:f269e3021894 1202 * to have the interval and window set to the same value. In this case,
elessair 0:f269e3021894 1203 * scanning is continuous, with a change of scanning frequency once every
elessair 0:f269e3021894 1204 * interval.
elessair 0:f269e3021894 1205 *
elessair 0:f269e3021894 1206 * @note Once the scanning parameters have been configured, scanning can be
elessair 0:f269e3021894 1207 * enabled by using startScan().
elessair 0:f269e3021894 1208 *
elessair 0:f269e3021894 1209 * @note The scan interval and window are recommendations to the BLE stack.
elessair 0:f269e3021894 1210 */
elessair 0:f269e3021894 1211 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
elessair 0:f269e3021894 1212 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
elessair 0:f269e3021894 1213 uint16_t timeout = 0,
elessair 0:f269e3021894 1214 bool activeScanning = false) {
elessair 0:f269e3021894 1215 ble_error_t rc;
elessair 0:f269e3021894 1216 if (((rc = _scanningParams.setInterval(interval)) == BLE_ERROR_NONE) &&
elessair 0:f269e3021894 1217 ((rc = _scanningParams.setWindow(window)) == BLE_ERROR_NONE) &&
elessair 0:f269e3021894 1218 ((rc = _scanningParams.setTimeout(timeout)) == BLE_ERROR_NONE)) {
elessair 0:f269e3021894 1219 _scanningParams.setActiveScanning(activeScanning);
elessair 0:f269e3021894 1220 return BLE_ERROR_NONE;
elessair 0:f269e3021894 1221 }
elessair 0:f269e3021894 1222
elessair 0:f269e3021894 1223 return rc;
elessair 0:f269e3021894 1224 }
elessair 0:f269e3021894 1225
elessair 0:f269e3021894 1226 /**
elessair 0:f269e3021894 1227 * Set up the scanInterval parameter for GAP scanning (observer mode).
elessair 0:f269e3021894 1228 *
elessair 0:f269e3021894 1229 * @param[in] interval
elessair 0:f269e3021894 1230 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
elessair 0:f269e3021894 1231 *
elessair 0:f269e3021894 1232 * @return BLE_ERROR_NONE if the scan interval was correctly set.
elessair 0:f269e3021894 1233 *
elessair 0:f269e3021894 1234 * @note The scanning window divided by the interval determines the duty cycle for
elessair 0:f269e3021894 1235 * scanning. For example, if the interval is 100ms and the window is 10ms,
elessair 0:f269e3021894 1236 * then the controller will scan for 10 percent of the time. It is possible
elessair 0:f269e3021894 1237 * to have the interval and window set to the same value. In this case,
elessair 0:f269e3021894 1238 * scanning is continuous, with a change of scanning frequency once every
elessair 0:f269e3021894 1239 * interval.
elessair 0:f269e3021894 1240 *
elessair 0:f269e3021894 1241 * @note Once the scanning parameters have been configured, scanning can be
elessair 0:f269e3021894 1242 * enabled by using startScan().
elessair 0:f269e3021894 1243 */
elessair 0:f269e3021894 1244 ble_error_t setScanInterval(uint16_t interval) {
elessair 0:f269e3021894 1245 return _scanningParams.setInterval(interval);
elessair 0:f269e3021894 1246 }
elessair 0:f269e3021894 1247
elessair 0:f269e3021894 1248 /**
elessair 0:f269e3021894 1249 * Set up the scanWindow parameter for GAP scanning (observer mode).
elessair 0:f269e3021894 1250 *
elessair 0:f269e3021894 1251 * @param[in] window
elessair 0:f269e3021894 1252 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
elessair 0:f269e3021894 1253 *
elessair 0:f269e3021894 1254 * @return BLE_ERROR_NONE if the scan window was correctly set.
elessair 0:f269e3021894 1255 *
elessair 0:f269e3021894 1256 * @note The scanning window divided by the interval determines the duty cycle for
elessair 0:f269e3021894 1257 * scanning. For example, if the interval is 100ms and the window is 10ms,
elessair 0:f269e3021894 1258 * then the controller will scan for 10 percent of the time. It is possible
elessair 0:f269e3021894 1259 * to have the interval and window set to the same value. In this case,
elessair 0:f269e3021894 1260 * scanning is continuous, with a change of scanning frequency once every
elessair 0:f269e3021894 1261 * interval.
elessair 0:f269e3021894 1262 *
elessair 0:f269e3021894 1263 * @note Once the scanning parameters have been configured, scanning can be
elessair 0:f269e3021894 1264 * enabled by using startScan().
elessair 0:f269e3021894 1265 *
elessair 0:f269e3021894 1266 * @note If scanning is already active, the updated value of scanWindow will be
elessair 0:f269e3021894 1267 * propagated to the underlying BLE stack.
elessair 0:f269e3021894 1268 */
elessair 0:f269e3021894 1269 ble_error_t setScanWindow(uint16_t window) {
elessair 0:f269e3021894 1270 ble_error_t rc;
elessair 0:f269e3021894 1271 if ((rc = _scanningParams.setWindow(window)) != BLE_ERROR_NONE) {
elessair 0:f269e3021894 1272 return rc;
elessair 0:f269e3021894 1273 }
elessair 0:f269e3021894 1274
elessair 0:f269e3021894 1275 /* If scanning is already active, propagate the new setting to the stack. */
elessair 0:f269e3021894 1276 if (scanningActive) {
elessair 0:f269e3021894 1277 return startRadioScan(_scanningParams);
elessair 0:f269e3021894 1278 }
elessair 0:f269e3021894 1279
elessair 0:f269e3021894 1280 return BLE_ERROR_NONE;
elessair 0:f269e3021894 1281 }
elessair 0:f269e3021894 1282
elessair 0:f269e3021894 1283 /**
elessair 0:f269e3021894 1284 * Set up parameters for GAP scanning (observer mode).
elessair 0:f269e3021894 1285 *
elessair 0:f269e3021894 1286 * @param[in] timeout
elessair 0:f269e3021894 1287 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
elessair 0:f269e3021894 1288 *
elessair 0:f269e3021894 1289 * @return BLE_ERROR_NONE if the scan timeout was correctly set.
elessair 0:f269e3021894 1290 *
elessair 0:f269e3021894 1291 * @note Once the scanning parameters have been configured, scanning can be
elessair 0:f269e3021894 1292 * enabled by using startScan().
elessair 0:f269e3021894 1293 *
elessair 0:f269e3021894 1294 * @note If scanning is already active, the updated value of scanTimeout will be
elessair 0:f269e3021894 1295 * propagated to the underlying BLE stack.
elessair 0:f269e3021894 1296 */
elessair 0:f269e3021894 1297 ble_error_t setScanTimeout(uint16_t timeout) {
elessair 0:f269e3021894 1298 ble_error_t rc;
elessair 0:f269e3021894 1299 if ((rc = _scanningParams.setTimeout(timeout)) != BLE_ERROR_NONE) {
elessair 0:f269e3021894 1300 return rc;
elessair 0:f269e3021894 1301 }
elessair 0:f269e3021894 1302
elessair 0:f269e3021894 1303 /* If scanning is already active, propagate the new settings to the stack. */
elessair 0:f269e3021894 1304 if (scanningActive) {
elessair 0:f269e3021894 1305 return startRadioScan(_scanningParams);
elessair 0:f269e3021894 1306 }
elessair 0:f269e3021894 1307
elessair 0:f269e3021894 1308 return BLE_ERROR_NONE;
elessair 0:f269e3021894 1309 }
elessair 0:f269e3021894 1310
elessair 0:f269e3021894 1311 /**
elessair 0:f269e3021894 1312 * Modify the active scanning parameter for GAP scanning (observer mode).
elessair 0:f269e3021894 1313 * This is used to fetch the scan response from a peer if possible.
elessair 0:f269e3021894 1314 *
elessair 0:f269e3021894 1315 * @param[in] activeScanning
elessair 0:f269e3021894 1316 * Set to True if active-scanning is required.
elessair 0:f269e3021894 1317 *
elessair 0:f269e3021894 1318 * @return BLE_ERROR_NONE if active scanning was successfully set.
elessair 0:f269e3021894 1319 *
elessair 0:f269e3021894 1320 * @note Once the scanning parameters have been configured, scanning can be
elessair 0:f269e3021894 1321 * enabled by using startScan().
elessair 0:f269e3021894 1322 *
elessair 0:f269e3021894 1323 * @note If scanning is already in progress, then active-scanning will be enabled
elessair 0:f269e3021894 1324 * for the underlying BLE stack.
elessair 0:f269e3021894 1325 */
elessair 0:f269e3021894 1326 ble_error_t setActiveScanning(bool activeScanning) {
elessair 0:f269e3021894 1327 _scanningParams.setActiveScanning(activeScanning);
elessair 0:f269e3021894 1328
elessair 0:f269e3021894 1329 /* If scanning is already active, propagate the new settings to the stack. */
elessair 0:f269e3021894 1330 if (scanningActive) {
elessair 0:f269e3021894 1331 return startRadioScan(_scanningParams);
elessair 0:f269e3021894 1332 }
elessair 0:f269e3021894 1333
elessair 0:f269e3021894 1334 return BLE_ERROR_NONE;
elessair 0:f269e3021894 1335 }
elessair 0:f269e3021894 1336
elessair 0:f269e3021894 1337 /**
elessair 0:f269e3021894 1338 * Start scanning (Observer Procedure) based on the parameters currently in
elessair 0:f269e3021894 1339 * effect.
elessair 0:f269e3021894 1340 *
elessair 0:f269e3021894 1341 * @param[in] callback
elessair 0:f269e3021894 1342 * The application-specific callback to be invoked upon
elessair 0:f269e3021894 1343 * receiving every advertisement report. This can be passed in
elessair 0:f269e3021894 1344 * as NULL, in which case scanning may not be enabled at all.
elessair 0:f269e3021894 1345 *
elessair 0:f269e3021894 1346 * @return BLE_ERROR_NONE if the device successfully started the scan
elessair 0:f269e3021894 1347 * procedure.
elessair 0:f269e3021894 1348 */
elessair 0:f269e3021894 1349 ble_error_t startScan(void (*callback)(const AdvertisementCallbackParams_t *params)) {
elessair 0:f269e3021894 1350 ble_error_t err = BLE_ERROR_NONE;
elessair 0:f269e3021894 1351 if (callback) {
elessair 0:f269e3021894 1352 if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
elessair 0:f269e3021894 1353 scanningActive = true;
elessair 0:f269e3021894 1354 onAdvertisementReport.attach(callback);
elessair 0:f269e3021894 1355 }
elessair 0:f269e3021894 1356 }
elessair 0:f269e3021894 1357
elessair 0:f269e3021894 1358 return err;
elessair 0:f269e3021894 1359 }
elessair 0:f269e3021894 1360
elessair 0:f269e3021894 1361 /**
elessair 0:f269e3021894 1362 * Same as Gap::startScan(), but allows the possibility to add an object
elessair 0:f269e3021894 1363 * reference and member function as handler for advertisement event
elessair 0:f269e3021894 1364 * callbacks.
elessair 0:f269e3021894 1365 *
elessair 0:f269e3021894 1366 * @param[in] object
elessair 0:f269e3021894 1367 * Pointer to the object of a class defining the member callback
elessair 0:f269e3021894 1368 * function (@p callbackMember).
elessair 0:f269e3021894 1369 * @param[in] callbackMember
elessair 0:f269e3021894 1370 * The member callback (within the context of an object) to be
elessair 0:f269e3021894 1371 * invoked.
elessair 0:f269e3021894 1372 *
elessair 0:f269e3021894 1373 * @return BLE_ERROR_NONE if the device successfully started the scan
elessair 0:f269e3021894 1374 * procedure.
elessair 0:f269e3021894 1375 */
elessair 0:f269e3021894 1376 template<typename T>
elessair 0:f269e3021894 1377 ble_error_t startScan(T *object, void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)) {
elessair 0:f269e3021894 1378 ble_error_t err = BLE_ERROR_NONE;
elessair 0:f269e3021894 1379 if (object && callbackMember) {
elessair 0:f269e3021894 1380 if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
elessair 0:f269e3021894 1381 scanningActive = true;
elessair 0:f269e3021894 1382 onAdvertisementReport.attach(object, callbackMember);
elessair 0:f269e3021894 1383 }
elessair 0:f269e3021894 1384 }
elessair 0:f269e3021894 1385
elessair 0:f269e3021894 1386 return err;
elessair 0:f269e3021894 1387 }
elessair 0:f269e3021894 1388
elessair 0:f269e3021894 1389 /**
elessair 0:f269e3021894 1390 * Initialize radio-notification events to be generated from the stack.
elessair 0:f269e3021894 1391 * This API doesn't need to be called directly.
elessair 0:f269e3021894 1392 *
elessair 0:f269e3021894 1393 * Radio Notification is a feature that enables ACTIVE and INACTIVE
elessair 0:f269e3021894 1394 * (nACTIVE) signals from the stack that notify the application when the
elessair 0:f269e3021894 1395 * radio is in use.
elessair 0:f269e3021894 1396 *
elessair 0:f269e3021894 1397 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
elessair 0:f269e3021894 1398 * signal is sent at the end of the radio event. These signals can be used
elessair 0:f269e3021894 1399 * by the application programmer to synchronize application logic with radio
elessair 0:f269e3021894 1400 * activity. For example, the ACTIVE signal can be used to shut off external
elessair 0:f269e3021894 1401 * devices, to manage peak current drawn during periods when the radio is on,
elessair 0:f269e3021894 1402 * or to trigger sensor data collection for transmission in the Radio Event.
elessair 0:f269e3021894 1403 *
elessair 0:f269e3021894 1404 * @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
elessair 0:f269e3021894 1405 */
elessair 0:f269e3021894 1406 virtual ble_error_t initRadioNotification(void) {
elessair 0:f269e3021894 1407 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
elessair 0:f269e3021894 1408 }
elessair 0:f269e3021894 1409
elessair 0:f269e3021894 1410 private:
elessair 0:f269e3021894 1411 /**
elessair 0:f269e3021894 1412 * Functionality that is BLE stack-dependent and must be implemented by the
elessair 0:f269e3021894 1413 * ported. This is a helper function to set the advertising data in the
elessair 0:f269e3021894 1414 * BLE stack.
elessair 0:f269e3021894 1415 *
elessair 0:f269e3021894 1416 * @param[in] advData
elessair 0:f269e3021894 1417 * The new advertising data.
elessair 0:f269e3021894 1418 * @param[in] scanResponse
elessair 0:f269e3021894 1419 * The new scan response data.
elessair 0:f269e3021894 1420 *
elessair 0:f269e3021894 1421 * @return BLE_ERROR_NONE if the advertising data was set successfully.
elessair 0:f269e3021894 1422 */
elessair 0:f269e3021894 1423 virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0;
elessair 0:f269e3021894 1424
elessair 0:f269e3021894 1425 /**
elessair 0:f269e3021894 1426 * Functionality that is BLE stack-dependent and must be implemented by the
elessair 0:f269e3021894 1427 * ported. This is a helper function to start the advertising procedure in
elessair 0:f269e3021894 1428 * the underlying BLE stack.
elessair 0:f269e3021894 1429 *
elessair 0:f269e3021894 1430 * @param[in]
elessair 0:f269e3021894 1431 * The advertising parameters.
elessair 0:f269e3021894 1432 *
elessair 0:f269e3021894 1433 * @return BLE_ERROR_NONE if the advertising procedure was successfully
elessair 0:f269e3021894 1434 * started.
elessair 0:f269e3021894 1435 */
elessair 0:f269e3021894 1436 virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
elessair 0:f269e3021894 1437
elessair 0:f269e3021894 1438 public:
elessair 0:f269e3021894 1439 /**
elessair 0:f269e3021894 1440 * Accessor to read back currently active advertising parameters.
elessair 0:f269e3021894 1441 *
elessair 0:f269e3021894 1442 * @return A reference to the current advertising parameters.
elessair 0:f269e3021894 1443 */
elessair 0:f269e3021894 1444 GapAdvertisingParams &getAdvertisingParams(void) {
elessair 0:f269e3021894 1445 return _advParams;
elessair 0:f269e3021894 1446 }
elessair 0:f269e3021894 1447
elessair 0:f269e3021894 1448 /**
elessair 0:f269e3021894 1449 * A const alternative to Gap::getAdvertisingParams().
elessair 0:f269e3021894 1450 *
elessair 0:f269e3021894 1451 * @return A const reference to the current advertising parameters.
elessair 0:f269e3021894 1452 */
elessair 0:f269e3021894 1453 const GapAdvertisingParams &getAdvertisingParams(void) const {
elessair 0:f269e3021894 1454 return _advParams;
elessair 0:f269e3021894 1455 }
elessair 0:f269e3021894 1456
elessair 0:f269e3021894 1457 /**
elessair 0:f269e3021894 1458 * Set up a particular, user-constructed set of advertisement parameters for
elessair 0:f269e3021894 1459 * the underlying stack. It would be uncommon for this API to be used
elessair 0:f269e3021894 1460 * directly; there are other APIs to tweak advertisement parameters
elessair 0:f269e3021894 1461 * individually.
elessair 0:f269e3021894 1462 *
elessair 0:f269e3021894 1463 * @param[in] newParams
elessair 0:f269e3021894 1464 * The new advertising parameters.
elessair 0:f269e3021894 1465 */
elessair 0:f269e3021894 1466 void setAdvertisingParams(const GapAdvertisingParams &newParams) {
elessair 0:f269e3021894 1467 _advParams = newParams;
elessair 0:f269e3021894 1468 }
elessair 0:f269e3021894 1469
elessair 0:f269e3021894 1470 /* Event callback handlers. */
elessair 0:f269e3021894 1471 public:
elessair 0:f269e3021894 1472 /**
elessair 0:f269e3021894 1473 * Set up a callback for timeout events. Refer to TimeoutSource_t for
elessair 0:f269e3021894 1474 * possible event types.
elessair 0:f269e3021894 1475 *
elessair 0:f269e3021894 1476 * @param[in] callback
elessair 0:f269e3021894 1477 * Event handler being registered.
elessair 0:f269e3021894 1478 *
elessair 0:f269e3021894 1479 * @note It is possible to unregister callbacks using onTimeout().detach(callback).
elessair 0:f269e3021894 1480 */
elessair 0:f269e3021894 1481 void onTimeout(TimeoutEventCallback_t callback) {
elessair 0:f269e3021894 1482 timeoutCallbackChain.add(callback);
elessair 0:f269e3021894 1483 }
elessair 0:f269e3021894 1484
elessair 0:f269e3021894 1485 /**
elessair 0:f269e3021894 1486 * @brief Provide access to the callchain of timeout event callbacks.
elessair 0:f269e3021894 1487 *
elessair 0:f269e3021894 1488 * @note It is possible to register callbacks using onTimeout().add(callback).
elessair 0:f269e3021894 1489 *
elessair 0:f269e3021894 1490 * @note It is possible to unregister callbacks using onTimeout().detach(callback).
elessair 0:f269e3021894 1491 *
elessair 0:f269e3021894 1492 * @return A reference to the timeout event callbacks chain.
elessair 0:f269e3021894 1493 */
elessair 0:f269e3021894 1494 TimeoutEventCallbackChain_t& onTimeout() {
elessair 0:f269e3021894 1495 return timeoutCallbackChain;
elessair 0:f269e3021894 1496 }
elessair 0:f269e3021894 1497
elessair 0:f269e3021894 1498 /**
elessair 0:f269e3021894 1499 * Append to a chain of callbacks to be invoked upon GAP connection.
elessair 0:f269e3021894 1500 *
elessair 0:f269e3021894 1501 * @param[in] callback
elessair 0:f269e3021894 1502 * Event handler being registered.
elessair 0:f269e3021894 1503 *
elessair 0:f269e3021894 1504 * @note It is possible to unregister callbacks using onConnection().detach(callback)
elessair 0:f269e3021894 1505 */
elessair 0:f269e3021894 1506 void onConnection(ConnectionEventCallback_t callback) {
elessair 0:f269e3021894 1507 connectionCallChain.add(callback);
elessair 0:f269e3021894 1508 }
elessair 0:f269e3021894 1509
elessair 0:f269e3021894 1510 /**
elessair 0:f269e3021894 1511 * Same as Gap::onConnection(), but allows the possibility to add an object
elessair 0:f269e3021894 1512 * reference and member function as handler for connection event
elessair 0:f269e3021894 1513 * callbacks.
elessair 0:f269e3021894 1514 *
elessair 0:f269e3021894 1515 * @param[in] tptr
elessair 0:f269e3021894 1516 * Pointer to the object of a class defining the member callback
elessair 0:f269e3021894 1517 * function (@p mptr).
elessair 0:f269e3021894 1518 * @param[in] mptr
elessair 0:f269e3021894 1519 * The member callback (within the context of an object) to be
elessair 0:f269e3021894 1520 * invoked.
elessair 0:f269e3021894 1521 */
elessair 0:f269e3021894 1522 template<typename T>
elessair 0:f269e3021894 1523 void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {
elessair 0:f269e3021894 1524 connectionCallChain.add(tptr, mptr);
elessair 0:f269e3021894 1525 }
elessair 0:f269e3021894 1526
elessair 0:f269e3021894 1527 /**
elessair 0:f269e3021894 1528 * @brief Provide access to the callchain of connection event callbacks.
elessair 0:f269e3021894 1529 *
elessair 0:f269e3021894 1530 * @return A reference to the connection event callbacks chain.
elessair 0:f269e3021894 1531 *
elessair 0:f269e3021894 1532 * @note It is possible to register callbacks using onConnection().add(callback).
elessair 0:f269e3021894 1533 *
elessair 0:f269e3021894 1534 * @note It is possible to unregister callbacks using onConnection().detach(callback).
elessair 0:f269e3021894 1535 */
elessair 0:f269e3021894 1536 ConnectionEventCallbackChain_t& onConnection() {
elessair 0:f269e3021894 1537 return connectionCallChain;
elessair 0:f269e3021894 1538 }
elessair 0:f269e3021894 1539
elessair 0:f269e3021894 1540 /**
elessair 0:f269e3021894 1541 * Append to a chain of callbacks to be invoked upon GAP disconnection.
elessair 0:f269e3021894 1542 *
elessair 0:f269e3021894 1543 * @param[in] callback
elessair 0:f269e3021894 1544 Event handler being registered.
elessair 0:f269e3021894 1545 *
elessair 0:f269e3021894 1546 * @note It is possible to unregister callbacks using onDisconnection().detach(callback).
elessair 0:f269e3021894 1547 */
elessair 0:f269e3021894 1548 void onDisconnection(DisconnectionEventCallback_t callback) {
elessair 0:f269e3021894 1549 disconnectionCallChain.add(callback);
elessair 0:f269e3021894 1550 }
elessair 0:f269e3021894 1551
elessair 0:f269e3021894 1552 /**
elessair 0:f269e3021894 1553 * Same as Gap::onDisconnection(), but allows the possibility to add an object
elessair 0:f269e3021894 1554 * reference and member function as handler for disconnection event
elessair 0:f269e3021894 1555 * callbacks.
elessair 0:f269e3021894 1556 *
elessair 0:f269e3021894 1557 * @param[in] tptr
elessair 0:f269e3021894 1558 * Pointer to the object of a class defining the member callback
elessair 0:f269e3021894 1559 * function (@p mptr).
elessair 0:f269e3021894 1560 * @param[in] mptr
elessair 0:f269e3021894 1561 * The member callback (within the context of an object) to be
elessair 0:f269e3021894 1562 * invoked.
elessair 0:f269e3021894 1563 */
elessair 0:f269e3021894 1564 template<typename T>
elessair 0:f269e3021894 1565 void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {
elessair 0:f269e3021894 1566 disconnectionCallChain.add(tptr, mptr);
elessair 0:f269e3021894 1567 }
elessair 0:f269e3021894 1568
elessair 0:f269e3021894 1569 /**
elessair 0:f269e3021894 1570 * @brief Provide access to the callchain of disconnection event callbacks.
elessair 0:f269e3021894 1571 *
elessair 0:f269e3021894 1572 * @return A reference to the disconnection event callback chain.
elessair 0:f269e3021894 1573 *
elessair 0:f269e3021894 1574 * @note It is possible to register callbacks using onDisconnection().add(callback).
elessair 0:f269e3021894 1575 *
elessair 0:f269e3021894 1576 * @note It is possible to unregister callbacks using onDisconnection().detach(callback).
elessair 0:f269e3021894 1577 */
elessair 0:f269e3021894 1578 DisconnectionEventCallbackChain_t& onDisconnection() {
elessair 0:f269e3021894 1579 return disconnectionCallChain;
elessair 0:f269e3021894 1580 }
elessair 0:f269e3021894 1581
elessair 0:f269e3021894 1582 /**
elessair 0:f269e3021894 1583 * Set the application callback for radio-notification events.
elessair 0:f269e3021894 1584 *
elessair 0:f269e3021894 1585 * Radio Notification is a feature that enables ACTIVE and INACTIVE
elessair 0:f269e3021894 1586 * (nACTIVE) signals from the stack that notify the application when the
elessair 0:f269e3021894 1587 * radio is in use.
elessair 0:f269e3021894 1588 *
elessair 0:f269e3021894 1589 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
elessair 0:f269e3021894 1590 * signal is sent at the end of the radio event. These signals can be used
elessair 0:f269e3021894 1591 * by the application programmer to synchronize application logic with radio
elessair 0:f269e3021894 1592 * activity. For example, the ACTIVE signal can be used to shut off external
elessair 0:f269e3021894 1593 * devices, to manage peak current drawn during periods when the radio is on,
elessair 0:f269e3021894 1594 * or to trigger sensor data collection for transmission in the Radio Event.
elessair 0:f269e3021894 1595 *
elessair 0:f269e3021894 1596 * @param[in] callback
elessair 0:f269e3021894 1597 * The application handler to be invoked in response to a radio
elessair 0:f269e3021894 1598 * ACTIVE/INACTIVE event.
elessair 0:f269e3021894 1599 */
elessair 0:f269e3021894 1600 void onRadioNotification(void (*callback)(bool param)) {
elessair 0:f269e3021894 1601 radioNotificationCallback.attach(callback);
elessair 0:f269e3021894 1602 }
elessair 0:f269e3021894 1603
elessair 0:f269e3021894 1604 /**
elessair 0:f269e3021894 1605 * Same as Gap::onRadioNotification(), but allows the posibility to
elessair 0:f269e3021894 1606 * register an object reference and member function as handler for radio
elessair 0:f269e3021894 1607 * notification events.
elessair 0:f269e3021894 1608 *
elessair 0:f269e3021894 1609 * @param[in] tptr
elessair 0:f269e3021894 1610 * Pointer to the object of a class defining the member callback
elessair 0:f269e3021894 1611 * function (@p mptr).
elessair 0:f269e3021894 1612 * @param[in] mptr
elessair 0:f269e3021894 1613 * The member callback (within the context of an object) to be
elessair 0:f269e3021894 1614 * invoked in response to a radio ACTIVE/INACTIVE event.
elessair 0:f269e3021894 1615 */
elessair 0:f269e3021894 1616 template <typename T>
elessair 0:f269e3021894 1617 void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
elessair 0:f269e3021894 1618 radioNotificationCallback.attach(tptr, mptr);
elessair 0:f269e3021894 1619 }
elessair 0:f269e3021894 1620
elessair 0:f269e3021894 1621 /**
elessair 0:f269e3021894 1622 * Setup a callback to be invoked to notify the user application that the
elessair 0:f269e3021894 1623 * Gap instance is about to shutdown (possibly as a result of a call
elessair 0:f269e3021894 1624 * to BLE::shutdown()).
elessair 0:f269e3021894 1625 *
elessair 0:f269e3021894 1626 * @param[in] callback
elessair 0:f269e3021894 1627 * The handler that is being registered to be notified of
elessair 0:f269e3021894 1628 * shutdown events.
elessair 0:f269e3021894 1629 *
elessair 0:f269e3021894 1630 * @note It is possible to chain together multiple onShutdown callbacks
elessair 0:f269e3021894 1631 * (potentially from different modules of an application) to be notified
elessair 0:f269e3021894 1632 * before the Gap instance is shutdown.
elessair 0:f269e3021894 1633 *
elessair 0:f269e3021894 1634 * @note It is also possible to set up a callback into a member function of
elessair 0:f269e3021894 1635 * some object.
elessair 0:f269e3021894 1636 *
elessair 0:f269e3021894 1637 * @note It is possible to unregister a callback using onShutdown().detach(callback)
elessair 0:f269e3021894 1638 */
elessair 0:f269e3021894 1639 void onShutdown(const GapShutdownCallback_t& callback) {
elessair 0:f269e3021894 1640 shutdownCallChain.add(callback);
elessair 0:f269e3021894 1641 }
elessair 0:f269e3021894 1642
elessair 0:f269e3021894 1643 /**
elessair 0:f269e3021894 1644 * Same as Gap::onShutdown(), but allows the posibility to
elessair 0:f269e3021894 1645 * register an object reference and member function as handler for shutdown
elessair 0:f269e3021894 1646 * events.
elessair 0:f269e3021894 1647 *
elessair 0:f269e3021894 1648 * @param[in] objPtr
elessair 0:f269e3021894 1649 * Pointer to the object of a class defining the member callback
elessair 0:f269e3021894 1650 * function (@p memberPtr).
elessair 0:f269e3021894 1651 * @param[in] memberPtr
elessair 0:f269e3021894 1652 * The member callback (within the context of an object) to be
elessair 0:f269e3021894 1653 * invoked in response to a shutdown event.
elessair 0:f269e3021894 1654 */
elessair 0:f269e3021894 1655 template <typename T>
elessair 0:f269e3021894 1656 void onShutdown(T *objPtr, void (T::*memberPtr)(const Gap *)) {
elessair 0:f269e3021894 1657 shutdownCallChain.add(objPtr, memberPtr);
elessair 0:f269e3021894 1658 }
elessair 0:f269e3021894 1659
elessair 0:f269e3021894 1660 /**
elessair 0:f269e3021894 1661 * @brief Provide access to the callchain of shutdown event callbacks.
elessair 0:f269e3021894 1662 *
elessair 0:f269e3021894 1663 * @return A reference to the shutdown event callback chain.
elessair 0:f269e3021894 1664 *
elessair 0:f269e3021894 1665 * @note It is possible to register callbacks using onShutdown().add(callback).
elessair 0:f269e3021894 1666 *
elessair 0:f269e3021894 1667 * @note It is possible to unregister callbacks using onShutdown().detach(callback).
elessair 0:f269e3021894 1668 */
elessair 0:f269e3021894 1669 GapShutdownCallbackChain_t& onShutdown() {
elessair 0:f269e3021894 1670 return shutdownCallChain;
elessair 0:f269e3021894 1671 }
elessair 0:f269e3021894 1672
elessair 0:f269e3021894 1673 public:
elessair 0:f269e3021894 1674 /**
elessair 0:f269e3021894 1675 * Notify all registered onShutdown callbacks that the Gap instance is
elessair 0:f269e3021894 1676 * about to be shutdown and clear all Gap state of the
elessair 0:f269e3021894 1677 * associated object.
elessair 0:f269e3021894 1678 *
elessair 0:f269e3021894 1679 * This function is meant to be overridden in the platform-specific
elessair 0:f269e3021894 1680 * sub-class. Nevertheless, the sub-class is only expected to reset its
elessair 0:f269e3021894 1681 * state and not the data held in Gap members. This shall be achieved by a
elessair 0:f269e3021894 1682 * call to Gap::reset() from the sub-class' reset() implementation.
elessair 0:f269e3021894 1683 *
elessair 0:f269e3021894 1684 * @return BLE_ERROR_NONE on success.
elessair 0:f269e3021894 1685 *
elessair 0:f269e3021894 1686 * @note Currently a call to reset() does not reset the advertising and
elessair 0:f269e3021894 1687 * scan parameters to default values.
elessair 0:f269e3021894 1688 */
elessair 0:f269e3021894 1689 virtual ble_error_t reset(void) {
elessair 0:f269e3021894 1690 /* Notify that the instance is about to shutdown */
elessair 0:f269e3021894 1691 shutdownCallChain.call(this);
elessair 0:f269e3021894 1692 shutdownCallChain.clear();
elessair 0:f269e3021894 1693
elessair 0:f269e3021894 1694 /* Clear Gap state */
elessair 0:f269e3021894 1695 state.advertising = 0;
elessair 0:f269e3021894 1696 state.connected = 0;
elessair 0:f269e3021894 1697 connectionCount = 0;
elessair 0:f269e3021894 1698
elessair 0:f269e3021894 1699 /* Clear scanning state */
elessair 0:f269e3021894 1700 scanningActive = false;
elessair 0:f269e3021894 1701
elessair 0:f269e3021894 1702 /* Clear advertising and scanning data */
elessair 0:f269e3021894 1703 _advPayload.clear();
elessair 0:f269e3021894 1704 _scanResponse.clear();
elessair 0:f269e3021894 1705
elessair 0:f269e3021894 1706 /* Clear callbacks */
elessair 0:f269e3021894 1707 timeoutCallbackChain.clear();
elessair 0:f269e3021894 1708 connectionCallChain.clear();
elessair 0:f269e3021894 1709 disconnectionCallChain.clear();
elessair 0:f269e3021894 1710 radioNotificationCallback = NULL;
elessair 0:f269e3021894 1711 onAdvertisementReport = NULL;
elessair 0:f269e3021894 1712
elessair 0:f269e3021894 1713 return BLE_ERROR_NONE;
elessair 0:f269e3021894 1714 }
elessair 0:f269e3021894 1715
elessair 0:f269e3021894 1716 protected:
elessair 0:f269e3021894 1717 /**
elessair 0:f269e3021894 1718 * Construct a Gap instance.
elessair 0:f269e3021894 1719 */
elessair 0:f269e3021894 1720 Gap() :
elessair 0:f269e3021894 1721 _advParams(),
elessair 0:f269e3021894 1722 _advPayload(),
elessair 0:f269e3021894 1723 _scanningParams(),
elessair 0:f269e3021894 1724 _scanResponse(),
elessair 0:f269e3021894 1725 connectionCount(0),
elessair 0:f269e3021894 1726 state(),
elessair 0:f269e3021894 1727 scanningActive(false),
elessair 0:f269e3021894 1728 timeoutCallbackChain(),
elessair 0:f269e3021894 1729 radioNotificationCallback(),
elessair 0:f269e3021894 1730 onAdvertisementReport(),
elessair 0:f269e3021894 1731 connectionCallChain(),
elessair 0:f269e3021894 1732 disconnectionCallChain() {
elessair 0:f269e3021894 1733 _advPayload.clear();
elessair 0:f269e3021894 1734 _scanResponse.clear();
elessair 0:f269e3021894 1735 }
elessair 0:f269e3021894 1736
elessair 0:f269e3021894 1737 /* Entry points for the underlying stack to report events back to the user. */
elessair 0:f269e3021894 1738 public:
elessair 0:f269e3021894 1739 /**
elessair 0:f269e3021894 1740 * Helper function that notifies all registered handlers of an occurrence
elessair 0:f269e3021894 1741 * of a connection event. This function is meant to be called from the
elessair 0:f269e3021894 1742 * BLE stack specific implementation when a connection event occurs.
elessair 0:f269e3021894 1743 *
elessair 0:f269e3021894 1744 * @param[in] handle
elessair 0:f269e3021894 1745 * The ID of the connection that generated the event.
elessair 0:f269e3021894 1746 * @param[in] role
elessair 0:f269e3021894 1747 * The role of this BLE device in the connection.
elessair 0:f269e3021894 1748 * @param[in] peerAddrType
elessair 0:f269e3021894 1749 * The peer's BLE address type.
elessair 0:f269e3021894 1750 * @param[in] peerAddr
elessair 0:f269e3021894 1751 * The peer's BLE address.
elessair 0:f269e3021894 1752 * @param[in] ownAddrType
elessair 0:f269e3021894 1753 * This device's BLE address type.
elessair 0:f269e3021894 1754 * @param[in] ownAddr
elessair 0:f269e3021894 1755 * This device's BLE address.
elessair 0:f269e3021894 1756 * @param[in] connectionParams
elessair 0:f269e3021894 1757 * The parameters configured for this connection.
elessair 0:f269e3021894 1758 */
elessair 0:f269e3021894 1759 void processConnectionEvent(Handle_t handle,
elessair 0:f269e3021894 1760 Role_t role,
elessair 0:f269e3021894 1761 BLEProtocol::AddressType_t peerAddrType,
elessair 0:f269e3021894 1762 const BLEProtocol::AddressBytes_t peerAddr,
elessair 0:f269e3021894 1763 BLEProtocol::AddressType_t ownAddrType,
elessair 0:f269e3021894 1764 const BLEProtocol::AddressBytes_t ownAddr,
elessair 0:f269e3021894 1765 const ConnectionParams_t *connectionParams) {
elessair 0:f269e3021894 1766 /* Update Gap state */
elessair 0:f269e3021894 1767 state.advertising = 0;
elessair 0:f269e3021894 1768 state.connected = 1;
elessair 0:f269e3021894 1769 ++connectionCount;
elessair 0:f269e3021894 1770
elessair 0:f269e3021894 1771 ConnectionCallbackParams_t callbackParams(handle, role, peerAddrType, peerAddr, ownAddrType, ownAddr, connectionParams);
elessair 0:f269e3021894 1772 connectionCallChain.call(&callbackParams);
elessair 0:f269e3021894 1773 }
elessair 0:f269e3021894 1774
elessair 0:f269e3021894 1775 /**
elessair 0:f269e3021894 1776 * Helper function that notifies all registered handlers of an occurrence
elessair 0:f269e3021894 1777 * of a disconnection event. This function is meant to be called from the
elessair 0:f269e3021894 1778 * BLE stack specific implementation when a disconnection event occurs.
elessair 0:f269e3021894 1779 *
elessair 0:f269e3021894 1780 * @param[in] handle
elessair 0:f269e3021894 1781 * The ID of the connection that generated the event.
elessair 0:f269e3021894 1782 * @param[in] reason
elessair 0:f269e3021894 1783 * The reason for disconnection.
elessair 0:f269e3021894 1784 */
elessair 0:f269e3021894 1785 void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
elessair 0:f269e3021894 1786 /* Update Gap state */
elessair 0:f269e3021894 1787 --connectionCount;
elessair 0:f269e3021894 1788 if (!connectionCount) {
elessair 0:f269e3021894 1789 state.connected = 0;
elessair 0:f269e3021894 1790 }
elessair 0:f269e3021894 1791
elessair 0:f269e3021894 1792 DisconnectionCallbackParams_t callbackParams(handle, reason);
elessair 0:f269e3021894 1793 disconnectionCallChain.call(&callbackParams);
elessair 0:f269e3021894 1794 }
elessair 0:f269e3021894 1795
elessair 0:f269e3021894 1796 /**
elessair 0:f269e3021894 1797 * Helper function that notifies the registered handler of a scanned
elessair 0:f269e3021894 1798 * advertisement packet. This function is meant to be called from the
elessair 0:f269e3021894 1799 * BLE stack specific implementation when a such event occurs.
elessair 0:f269e3021894 1800 *
elessair 0:f269e3021894 1801 * @param[in] peerAddr
elessair 0:f269e3021894 1802 * The peer's BLE address.
elessair 0:f269e3021894 1803 * @param[in] rssi
elessair 0:f269e3021894 1804 * The advertisement packet RSSI value.
elessair 0:f269e3021894 1805 * @param[in] isScanReponse
elessair 0:f269e3021894 1806 * Whether this packet is the response to a scan request.
elessair 0:f269e3021894 1807 * @param[in] type
elessair 0:f269e3021894 1808 * The type of advertisement.
elessair 0:f269e3021894 1809 * @param[in] advertisingDataLen
elessair 0:f269e3021894 1810 * Length of the advertisement data.
elessair 0:f269e3021894 1811 * @param[in] advertisingData
elessair 0:f269e3021894 1812 * Pointer to the advertisement packet's data.
elessair 0:f269e3021894 1813 */
elessair 0:f269e3021894 1814 void processAdvertisementReport(const BLEProtocol::AddressBytes_t peerAddr,
elessair 0:f269e3021894 1815 int8_t rssi,
elessair 0:f269e3021894 1816 bool isScanResponse,
elessair 0:f269e3021894 1817 GapAdvertisingParams::AdvertisingType_t type,
elessair 0:f269e3021894 1818 uint8_t advertisingDataLen,
elessair 0:f269e3021894 1819 const uint8_t *advertisingData) {
elessair 0:f269e3021894 1820 AdvertisementCallbackParams_t params;
elessair 0:f269e3021894 1821 memcpy(params.peerAddr, peerAddr, ADDR_LEN);
elessair 0:f269e3021894 1822 params.rssi = rssi;
elessair 0:f269e3021894 1823 params.isScanResponse = isScanResponse;
elessair 0:f269e3021894 1824 params.type = type;
elessair 0:f269e3021894 1825 params.advertisingDataLen = advertisingDataLen;
elessair 0:f269e3021894 1826 params.advertisingData = advertisingData;
elessair 0:f269e3021894 1827 onAdvertisementReport.call(&params);
elessair 0:f269e3021894 1828 }
elessair 0:f269e3021894 1829
elessair 0:f269e3021894 1830 /**
elessair 0:f269e3021894 1831 * Helper function that notifies all registered handlers of an occurrence
elessair 0:f269e3021894 1832 * of a timeout event. This function is meant to be called from the
elessair 0:f269e3021894 1833 * BLE stack specific implementation when a timeout event occurs.
elessair 0:f269e3021894 1834 *
elessair 0:f269e3021894 1835 * @param[in] source
elessair 0:f269e3021894 1836 * The source of the timout event.
elessair 0:f269e3021894 1837 */
elessair 0:f269e3021894 1838 void processTimeoutEvent(TimeoutSource_t source) {
elessair 0:f269e3021894 1839 if (source == TIMEOUT_SRC_ADVERTISING) {
elessair 0:f269e3021894 1840 /* Update gap state if the source is an advertising timeout */
elessair 0:f269e3021894 1841 state.advertising = 0;
elessair 0:f269e3021894 1842 }
elessair 0:f269e3021894 1843 if (timeoutCallbackChain) {
elessair 0:f269e3021894 1844 timeoutCallbackChain(source);
elessair 0:f269e3021894 1845 }
elessair 0:f269e3021894 1846 }
elessair 0:f269e3021894 1847
elessair 0:f269e3021894 1848 protected:
elessair 0:f269e3021894 1849 /**
elessair 0:f269e3021894 1850 * Currently set advertising parameters.
elessair 0:f269e3021894 1851 */
elessair 0:f269e3021894 1852 GapAdvertisingParams _advParams;
elessair 0:f269e3021894 1853 /**
elessair 0:f269e3021894 1854 * Currently set advertising data.
elessair 0:f269e3021894 1855 */
elessair 0:f269e3021894 1856 GapAdvertisingData _advPayload;
elessair 0:f269e3021894 1857 /**
elessair 0:f269e3021894 1858 * Currently set scanning parameters.
elessair 0:f269e3021894 1859 */
elessair 0:f269e3021894 1860 GapScanningParams _scanningParams;
elessair 0:f269e3021894 1861 /**
elessair 0:f269e3021894 1862 * Currently set scan response data.
elessair 0:f269e3021894 1863 */
elessair 0:f269e3021894 1864 GapAdvertisingData _scanResponse;
elessair 0:f269e3021894 1865
elessair 0:f269e3021894 1866 /**
elessair 0:f269e3021894 1867 * Total number of open connections.
elessair 0:f269e3021894 1868 */
elessair 0:f269e3021894 1869 uint8_t connectionCount;
elessair 0:f269e3021894 1870 /**
elessair 0:f269e3021894 1871 * The current GAP state.
elessair 0:f269e3021894 1872 */
elessair 0:f269e3021894 1873 GapState_t state;
elessair 0:f269e3021894 1874 /**
elessair 0:f269e3021894 1875 * Whether active scanning is set. This is used to fetch the scan response
elessair 0:f269e3021894 1876 * from a peer if possible.
elessair 0:f269e3021894 1877 */
elessair 0:f269e3021894 1878 bool scanningActive;
elessair 0:f269e3021894 1879
elessair 0:f269e3021894 1880 protected:
elessair 0:f269e3021894 1881 /**
elessair 0:f269e3021894 1882 * Callchain containing all registered callback handlers for timeout
elessair 0:f269e3021894 1883 * events.
elessair 0:f269e3021894 1884 */
elessair 0:f269e3021894 1885 TimeoutEventCallbackChain_t timeoutCallbackChain;
elessair 0:f269e3021894 1886 /**
elessair 0:f269e3021894 1887 * The registered callback handler for radio notification events.
elessair 0:f269e3021894 1888 */
elessair 0:f269e3021894 1889 RadioNotificationEventCallback_t radioNotificationCallback;
elessair 0:f269e3021894 1890 /**
elessair 0:f269e3021894 1891 * The registered callback handler for scanned advertisement packet
elessair 0:f269e3021894 1892 * notifications.
elessair 0:f269e3021894 1893 */
elessair 0:f269e3021894 1894 AdvertisementReportCallback_t onAdvertisementReport;
elessair 0:f269e3021894 1895 /**
elessair 0:f269e3021894 1896 * Callchain containing all registered callback handlers for connection
elessair 0:f269e3021894 1897 * events.
elessair 0:f269e3021894 1898 */
elessair 0:f269e3021894 1899 ConnectionEventCallbackChain_t connectionCallChain;
elessair 0:f269e3021894 1900 /**
elessair 0:f269e3021894 1901 * Callchain containing all registered callback handlers for disconnection
elessair 0:f269e3021894 1902 * events.
elessair 0:f269e3021894 1903 */
elessair 0:f269e3021894 1904 DisconnectionEventCallbackChain_t disconnectionCallChain;
elessair 0:f269e3021894 1905
elessair 0:f269e3021894 1906 private:
elessair 0:f269e3021894 1907 /**
elessair 0:f269e3021894 1908 * Callchain containing all registered callback handlers for shutdown
elessair 0:f269e3021894 1909 * events.
elessair 0:f269e3021894 1910 */
elessair 0:f269e3021894 1911 GapShutdownCallbackChain_t shutdownCallChain;
elessair 0:f269e3021894 1912
elessair 0:f269e3021894 1913 private:
elessair 0:f269e3021894 1914 /* Disallow copy and assignment. */
elessair 0:f269e3021894 1915 Gap(const Gap &);
elessair 0:f269e3021894 1916 Gap& operator=(const Gap &);
elessair 0:f269e3021894 1917 };
elessair 0:f269e3021894 1918
elessair 0:f269e3021894 1919 #endif // ifndef __GAP_H__