Bluetooth Low Energy / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Dependents:   BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate BLE_ANCS_SDAPI_IRC ... more

Overview

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

Supported Services

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

ble/Gap.h@1208:65474dc93927, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:18:00 2016 +0100
Revision:
1208:65474dc93927
Parent:
1193:c8bbf3a6712d 
Sync with 8d97fced5440d78c9557693b6d1632f1ab5d77b7



2016-09-01 08:21:37+01:00: Vincent Coubard

version v2.7.0

Who changed what in which revision?

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