Simon Cooksey / mbed-os

Pinned to some recent date

features/FEATURE_BLE/ble/Gap.h@0:fb7af294d5d9, 2016-11-17 (annotated)

Committer:
Simon Cooksey
Date:
Thu Nov 17 16:43:53 2016 +0000
Revision:
0:fb7af294d5d9
Initial commit

Who changed what in which revision?

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