High level Bluetooth Low Energy API and radio abstraction layer

Fork of BLE_API by Bluetooth Low Energy

Committer:
vcoubard
Date:
Wed Apr 06 19:13:46 2016 +0100
Revision:
1131:692ddf04fc42
Parent:
1124:7ffed715734a
Child:
1132:6362b7c2fdff
Synchronized with git rev 13bf70b6
Author: Rohit Grover
Release 2.1.5
=============

A minor release to separate the concept of minlen and len in
GattCharacteristic. Also contains some improvements to documentation.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
vcoubard 1131:692ddf04fc42 1 /* mbed Microcontroller Library
vcoubard 1131:692ddf04fc42 2 * Copyright (c) 2006-2013 ARM Limited
vcoubard 1131:692ddf04fc42 3 *
vcoubard 1131:692ddf04fc42 4 * Licensed under the Apache License, Version 2.0 (the "License");
vcoubard 1131:692ddf04fc42 5 * you may not use this file except in compliance with the License.
vcoubard 1131:692ddf04fc42 6 * You may obtain a copy of the License at
vcoubard 1131:692ddf04fc42 7 *
vcoubard 1131:692ddf04fc42 8 * http://www.apache.org/licenses/LICENSE-2.0
vcoubard 1131:692ddf04fc42 9 *
vcoubard 1131:692ddf04fc42 10 * Unless required by applicable law or agreed to in writing, software
vcoubard 1131:692ddf04fc42 11 * distributed under the License is distributed on an "AS IS" BASIS,
vcoubard 1131:692ddf04fc42 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
vcoubard 1131:692ddf04fc42 13 * See the License for the specific language governing permissions and
vcoubard 1131:692ddf04fc42 14 * limitations under the License.
vcoubard 1131:692ddf04fc42 15 */
vcoubard 1131:692ddf04fc42 16
vcoubard 1131:692ddf04fc42 17 #ifndef __GAP_H__
vcoubard 1131:692ddf04fc42 18 #define __GAP_H__
vcoubard 1131:692ddf04fc42 19
vcoubard 1131:692ddf04fc42 20 #include "GapAdvertisingData.h"
vcoubard 1131:692ddf04fc42 21 #include "GapAdvertisingParams.h"
vcoubard 1131:692ddf04fc42 22 #include "GapScanningParams.h"
vcoubard 1131:692ddf04fc42 23 #include "GapEvents.h"
vcoubard 1131:692ddf04fc42 24 #include "CallChainOfFunctionPointersWithContext.h"
vcoubard 1131:692ddf04fc42 25 #include "FunctionPointerWithContext.h"
vcoubard 1131:692ddf04fc42 26
vcoubard 1131:692ddf04fc42 27 /* Forward declarations for classes that will only be used for pointers or references in the following. */
vcoubard 1131:692ddf04fc42 28 class GapAdvertisingParams;
vcoubard 1131:692ddf04fc42 29 class GapScanningParams;
vcoubard 1131:692ddf04fc42 30 class GapAdvertisingData;
vcoubard 1131:692ddf04fc42 31
vcoubard 1131:692ddf04fc42 32 class Gap {
vcoubard 1131:692ddf04fc42 33 public:
vcoubard 1131:692ddf04fc42 34 enum AddressType_t {
vcoubard 1131:692ddf04fc42 35 ADDR_TYPE_PUBLIC = 0,
vcoubard 1131:692ddf04fc42 36 ADDR_TYPE_RANDOM_STATIC,
vcoubard 1131:692ddf04fc42 37 ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE,
vcoubard 1131:692ddf04fc42 38 ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE
vcoubard 1131:692ddf04fc42 39 };
vcoubard 1131:692ddf04fc42 40 typedef enum AddressType_t addr_type_t; /* @Note: Deprecated. Use AddressType_t instead. */
vcoubard 1131:692ddf04fc42 41
vcoubard 1131:692ddf04fc42 42 static const unsigned ADDR_LEN = 6;
vcoubard 1131:692ddf04fc42 43 typedef uint8_t Address_t[ADDR_LEN]; /* 48-bit address, LSB format. */
vcoubard 1131:692ddf04fc42 44 typedef Address_t address_t; /* @Note: Deprecated. Use Address_t instead. */
vcoubard 1131:692ddf04fc42 45
vcoubard 1131:692ddf04fc42 46 enum TimeoutSource_t {
vcoubard 1131:692ddf04fc42 47 TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */
vcoubard 1131:692ddf04fc42 48 TIMEOUT_SRC_SECURITY_REQUEST = 0x01, /**< Security request timeout. */
vcoubard 1131:692ddf04fc42 49 TIMEOUT_SRC_SCAN = 0x02, /**< Scanning timeout. */
vcoubard 1131:692ddf04fc42 50 TIMEOUT_SRC_CONN = 0x03, /**< Connection timeout. */
vcoubard 1131:692ddf04fc42 51 };
vcoubard 1131:692ddf04fc42 52
vcoubard 1131:692ddf04fc42 53 /**
vcoubard 1131:692ddf04fc42 54 * Enumeration for disconnection reasons. The values for these reasons are
vcoubard 1131:692ddf04fc42 55 * derived from Nordic's implementation, but the reasons are meant to be
vcoubard 1131:692ddf04fc42 56 * independent of the transport. If you are returned a reason that is not
vcoubard 1131:692ddf04fc42 57 * covered by this enumeration, please refer to the underlying
vcoubard 1131:692ddf04fc42 58 * transport library.
vcoubard 1131:692ddf04fc42 59 */
vcoubard 1131:692ddf04fc42 60 enum DisconnectionReason_t {
vcoubard 1131:692ddf04fc42 61 CONNECTION_TIMEOUT = 0x08,
vcoubard 1131:692ddf04fc42 62 REMOTE_USER_TERMINATED_CONNECTION = 0x13,
vcoubard 1131:692ddf04fc42 63 REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, /**< Remote device terminated connection due to low resources.*/
vcoubard 1131:692ddf04fc42 64 REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /**< Remote device terminated connection due to power off. */
vcoubard 1131:692ddf04fc42 65 LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
vcoubard 1131:692ddf04fc42 66 CONN_INTERVAL_UNACCEPTABLE = 0x3B,
vcoubard 1131:692ddf04fc42 67 };
vcoubard 1131:692ddf04fc42 68
vcoubard 1131:692ddf04fc42 69 /* Describes the current state of the device (more than one bit can be set). */
vcoubard 1131:692ddf04fc42 70 struct GapState_t {
vcoubard 1131:692ddf04fc42 71 unsigned advertising : 1; /**< Peripheral is currently advertising. */
vcoubard 1131:692ddf04fc42 72 unsigned connected : 1; /**< Peripheral is connected to a central. */
vcoubard 1131:692ddf04fc42 73 };
vcoubard 1131:692ddf04fc42 74
vcoubard 1131:692ddf04fc42 75 typedef uint16_t Handle_t; /* Type for connection handle. */
vcoubard 1131:692ddf04fc42 76
vcoubard 1131:692ddf04fc42 77 typedef struct {
vcoubard 1131:692ddf04fc42 78 uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1131:692ddf04fc42 79 uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1131:692ddf04fc42 80 uint16_t slaveLatency; /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1131:692ddf04fc42 81 uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
vcoubard 1131:692ddf04fc42 82 } ConnectionParams_t;
vcoubard 1131:692ddf04fc42 83
vcoubard 1131:692ddf04fc42 84 enum Role_t {
vcoubard 1131:692ddf04fc42 85 PERIPHERAL = 0x1, /**< Peripheral Role. */
vcoubard 1131:692ddf04fc42 86 CENTRAL = 0x2, /**< Central Role. */
vcoubard 1131:692ddf04fc42 87 };
vcoubard 1131:692ddf04fc42 88
vcoubard 1131:692ddf04fc42 89 struct AdvertisementCallbackParams_t {
vcoubard 1131:692ddf04fc42 90 Address_t peerAddr;
vcoubard 1131:692ddf04fc42 91 int8_t rssi;
vcoubard 1131:692ddf04fc42 92 bool isScanResponse;
vcoubard 1131:692ddf04fc42 93 GapAdvertisingParams::AdvertisingType_t type;
vcoubard 1131:692ddf04fc42 94 uint8_t advertisingDataLen;
vcoubard 1131:692ddf04fc42 95 const uint8_t *advertisingData;
vcoubard 1131:692ddf04fc42 96 };
vcoubard 1131:692ddf04fc42 97 typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> AdvertisementReportCallback_t;
vcoubard 1131:692ddf04fc42 98
vcoubard 1131:692ddf04fc42 99 struct ConnectionCallbackParams_t {
vcoubard 1131:692ddf04fc42 100 Handle_t handle;
vcoubard 1131:692ddf04fc42 101 Role_t role;
vcoubard 1131:692ddf04fc42 102 AddressType_t peerAddrType;
vcoubard 1131:692ddf04fc42 103 Address_t peerAddr;
vcoubard 1131:692ddf04fc42 104 AddressType_t ownAddrType;
vcoubard 1131:692ddf04fc42 105 Address_t ownAddr;
vcoubard 1131:692ddf04fc42 106 const ConnectionParams_t *connectionParams;
vcoubard 1131:692ddf04fc42 107
vcoubard 1131:692ddf04fc42 108 ConnectionCallbackParams_t(Handle_t handleIn,
vcoubard 1131:692ddf04fc42 109 Role_t roleIn,
vcoubard 1131:692ddf04fc42 110 AddressType_t peerAddrTypeIn,
vcoubard 1131:692ddf04fc42 111 const uint8_t *peerAddrIn,
vcoubard 1131:692ddf04fc42 112 AddressType_t ownAddrTypeIn,
vcoubard 1131:692ddf04fc42 113 const uint8_t *ownAddrIn,
vcoubard 1131:692ddf04fc42 114 const ConnectionParams_t *connectionParamsIn) :
vcoubard 1131:692ddf04fc42 115 handle(handleIn),
vcoubard 1131:692ddf04fc42 116 role(roleIn),
vcoubard 1131:692ddf04fc42 117 peerAddrType(peerAddrTypeIn),
vcoubard 1131:692ddf04fc42 118 peerAddr(),
vcoubard 1131:692ddf04fc42 119 ownAddrType(ownAddrTypeIn),
vcoubard 1131:692ddf04fc42 120 ownAddr(),
vcoubard 1131:692ddf04fc42 121 connectionParams(connectionParamsIn) {
vcoubard 1131:692ddf04fc42 122 memcpy(peerAddr, peerAddrIn, ADDR_LEN);
vcoubard 1131:692ddf04fc42 123 memcpy(ownAddr, ownAddrIn, ADDR_LEN);
vcoubard 1131:692ddf04fc42 124 }
vcoubard 1131:692ddf04fc42 125 };
vcoubard 1131:692ddf04fc42 126
vcoubard 1131:692ddf04fc42 127 struct DisconnectionCallbackParams_t {
vcoubard 1131:692ddf04fc42 128 Handle_t handle;
vcoubard 1131:692ddf04fc42 129 DisconnectionReason_t reason;
vcoubard 1131:692ddf04fc42 130
vcoubard 1131:692ddf04fc42 131 DisconnectionCallbackParams_t(Handle_t handleIn,
vcoubard 1131:692ddf04fc42 132 DisconnectionReason_t reasonIn) :
vcoubard 1131:692ddf04fc42 133 handle(handleIn),
vcoubard 1131:692ddf04fc42 134 reason(reasonIn)
vcoubard 1131:692ddf04fc42 135 {}
vcoubard 1131:692ddf04fc42 136 };
vcoubard 1131:692ddf04fc42 137
vcoubard 1131:692ddf04fc42 138 static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
vcoubard 1131:692ddf04fc42 139 static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
vcoubard 1131:692ddf04fc42 140 return (durationInMillis * 1000) / UNIT_1_25_MS;
vcoubard 1131:692ddf04fc42 141 }
vcoubard 1131:692ddf04fc42 142
vcoubard 1131:692ddf04fc42 143 typedef FunctionPointerWithContext<TimeoutSource_t> TimeoutEventCallback_t;
vcoubard 1131:692ddf04fc42 144 typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> TimeoutEventCallbackChain_t;
vcoubard 1131:692ddf04fc42 145
vcoubard 1131:692ddf04fc42 146 typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallback_t;
vcoubard 1131:692ddf04fc42 147 typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t;
vcoubard 1131:692ddf04fc42 148
vcoubard 1131:692ddf04fc42 149 typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
vcoubard 1131:692ddf04fc42 150 typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t;
vcoubard 1131:692ddf04fc42 151
vcoubard 1131:692ddf04fc42 152 typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
vcoubard 1131:692ddf04fc42 153
vcoubard 1131:692ddf04fc42 154 /*
vcoubard 1131:692ddf04fc42 155 * The following functions are meant to be overridden in the platform-specific sub-class.
vcoubard 1131:692ddf04fc42 156 */
vcoubard 1131:692ddf04fc42 157 public:
vcoubard 1131:692ddf04fc42 158 /**
vcoubard 1131:692ddf04fc42 159 * Set the BTLE MAC address and type. Please note that the address format is
vcoubard 1131:692ddf04fc42 160 * least significant byte first (LSB). Please refer to Address_t.
vcoubard 1131:692ddf04fc42 161 *
vcoubard 1131:692ddf04fc42 162 * @return BLE_ERROR_NONE on success.
vcoubard 1131:692ddf04fc42 163 */
vcoubard 1131:692ddf04fc42 164 virtual ble_error_t setAddress(AddressType_t type, const Address_t address) {
vcoubard 1131:692ddf04fc42 165 /* avoid compiler warnings about unused variables */
vcoubard 1131:692ddf04fc42 166 (void)type;
vcoubard 1131:692ddf04fc42 167 (void)address;
vcoubard 1131:692ddf04fc42 168
vcoubard 1131:692ddf04fc42 169 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 170 }
vcoubard 1131:692ddf04fc42 171
vcoubard 1131:692ddf04fc42 172 /**
vcoubard 1131:692ddf04fc42 173 * Fetch the BTLE MAC address and type.
vcoubard 1131:692ddf04fc42 174 *
vcoubard 1131:692ddf04fc42 175 * @return BLE_ERROR_NONE on success.
vcoubard 1131:692ddf04fc42 176 */
vcoubard 1131:692ddf04fc42 177 virtual ble_error_t getAddress(AddressType_t *typeP, Address_t address) {
vcoubard 1131:692ddf04fc42 178 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 179 (void)typeP;
vcoubard 1131:692ddf04fc42 180 (void)address;
vcoubard 1131:692ddf04fc42 181
vcoubard 1131:692ddf04fc42 182 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 183 }
vcoubard 1131:692ddf04fc42 184
vcoubard 1131:692ddf04fc42 185 /**
vcoubard 1131:692ddf04fc42 186 * @return Minimum Advertising interval in milliseconds.
vcoubard 1131:692ddf04fc42 187 */
vcoubard 1131:692ddf04fc42 188 virtual uint16_t getMinAdvertisingInterval(void) const {
vcoubard 1131:692ddf04fc42 189 return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 190 }
vcoubard 1131:692ddf04fc42 191
vcoubard 1131:692ddf04fc42 192 /**
vcoubard 1131:692ddf04fc42 193 * @return Minimum Advertising interval in milliseconds for non-connectible mode.
vcoubard 1131:692ddf04fc42 194 */
vcoubard 1131:692ddf04fc42 195 virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const {
vcoubard 1131:692ddf04fc42 196 return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 197 }
vcoubard 1131:692ddf04fc42 198
vcoubard 1131:692ddf04fc42 199 /**
vcoubard 1131:692ddf04fc42 200 * @return Maximum Advertising interval in milliseconds.
vcoubard 1131:692ddf04fc42 201 */
vcoubard 1131:692ddf04fc42 202 virtual uint16_t getMaxAdvertisingInterval(void) const {
vcoubard 1131:692ddf04fc42 203 return 0xFFFF; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 204 }
vcoubard 1131:692ddf04fc42 205
vcoubard 1131:692ddf04fc42 206 virtual ble_error_t stopAdvertising(void) {
vcoubard 1131:692ddf04fc42 207 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 208 }
vcoubard 1131:692ddf04fc42 209
vcoubard 1131:692ddf04fc42 210 /**
vcoubard 1131:692ddf04fc42 211 * Stop scanning. The current scanning parameters remain in effect.
vcoubard 1131:692ddf04fc42 212 *
vcoubard 1131:692ddf04fc42 213 * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
vcoubard 1131:692ddf04fc42 214 */
vcoubard 1131:692ddf04fc42 215 virtual ble_error_t stopScan() {
vcoubard 1131:692ddf04fc42 216 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 217 }
vcoubard 1131:692ddf04fc42 218
vcoubard 1131:692ddf04fc42 219 /**
vcoubard 1131:692ddf04fc42 220 * Create a connection (GAP Link Establishment).
vcoubard 1131:692ddf04fc42 221 *
vcoubard 1131:692ddf04fc42 222 * @param peerAddr
vcoubard 1131:692ddf04fc42 223 * 48-bit address, LSB format.
vcoubard 1131:692ddf04fc42 224 * @param peerAddrType
vcoubard 1131:692ddf04fc42 225 * Address type of the peer.
vcoubard 1131:692ddf04fc42 226 * @param connectionParams
vcoubard 1131:692ddf04fc42 227 * Connection parameters.
vcoubard 1131:692ddf04fc42 228 * @param scanParams
vcoubard 1131:692ddf04fc42 229 * Paramters to be used while scanning for the peer.
vcoubard 1131:692ddf04fc42 230 * @return BLE_ERROR_NONE if connection establishment procedure is started
vcoubard 1131:692ddf04fc42 231 * successfully. The connectionCallChain (if set) will be invoked upon
vcoubard 1131:692ddf04fc42 232 * a connection event.
vcoubard 1131:692ddf04fc42 233 */
vcoubard 1131:692ddf04fc42 234 virtual ble_error_t connect(const Address_t peerAddr,
vcoubard 1131:692ddf04fc42 235 Gap::AddressType_t peerAddrType,
vcoubard 1131:692ddf04fc42 236 const ConnectionParams_t *connectionParams,
vcoubard 1131:692ddf04fc42 237 const GapScanningParams *scanParams) {
vcoubard 1131:692ddf04fc42 238 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 239 (void)peerAddr;
vcoubard 1131:692ddf04fc42 240 (void)peerAddrType;
vcoubard 1131:692ddf04fc42 241 (void)connectionParams;
vcoubard 1131:692ddf04fc42 242 (void)scanParams;
vcoubard 1131:692ddf04fc42 243
vcoubard 1131:692ddf04fc42 244 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 245 }
vcoubard 1131:692ddf04fc42 246
vcoubard 1131:692ddf04fc42 247 /**
vcoubard 1131:692ddf04fc42 248 * This call initiates the disconnection procedure, and its completion will
vcoubard 1131:692ddf04fc42 249 * be communicated to the application with an invocation of the
vcoubard 1131:692ddf04fc42 250 * disconnectionCallback.
vcoubard 1131:692ddf04fc42 251 *
vcoubard 1131:692ddf04fc42 252 * @param reason
vcoubard 1131:692ddf04fc42 253 * The reason for disconnection; to be sent back to the peer.
vcoubard 1131:692ddf04fc42 254 */
vcoubard 1131:692ddf04fc42 255 virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
vcoubard 1131:692ddf04fc42 256 /* avoid compiler warnings about unused variables */
vcoubard 1131:692ddf04fc42 257 (void)connectionHandle;
vcoubard 1131:692ddf04fc42 258 (void)reason;
vcoubard 1131:692ddf04fc42 259
vcoubard 1131:692ddf04fc42 260 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 261 }
vcoubard 1131:692ddf04fc42 262
vcoubard 1131:692ddf04fc42 263 /**
vcoubard 1131:692ddf04fc42 264 * This call initiates the disconnection procedure, and its completion will
vcoubard 1131:692ddf04fc42 265 * be communicated to the application with an invocation of the
vcoubard 1131:692ddf04fc42 266 * disconnectionCallback.
vcoubard 1131:692ddf04fc42 267 *
vcoubard 1131:692ddf04fc42 268 * @param reason
vcoubard 1131:692ddf04fc42 269 * The reason for disconnection; to be sent back to the peer.
vcoubard 1131:692ddf04fc42 270 *
vcoubard 1131:692ddf04fc42 271 * @note: This version of disconnect() doesn't take a connection handle. It
vcoubard 1131:692ddf04fc42 272 * works reliably only for stacks that are limited to a single
vcoubard 1131:692ddf04fc42 273 * connection. This API should be considered *deprecated* in favour of the
vcoubard 1131:692ddf04fc42 274 * alternative, which takes a connection handle. It will be dropped in the future.
vcoubard 1131:692ddf04fc42 275 */
vcoubard 1131:692ddf04fc42 276 virtual ble_error_t disconnect(DisconnectionReason_t reason) {
vcoubard 1131:692ddf04fc42 277 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 278 (void)reason;
vcoubard 1131:692ddf04fc42 279
vcoubard 1131:692ddf04fc42 280 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 281 }
vcoubard 1131:692ddf04fc42 282
vcoubard 1131:692ddf04fc42 283 /**
vcoubard 1131:692ddf04fc42 284 * Get the GAP peripheral preferred connection parameters. These are the
vcoubard 1131:692ddf04fc42 285 * defaults that the peripheral would like to have in a connection. The
vcoubard 1131:692ddf04fc42 286 * choice of the connection parameters is eventually up to the central.
vcoubard 1131:692ddf04fc42 287 *
vcoubard 1131:692ddf04fc42 288 * @param[out] params
vcoubard 1131:692ddf04fc42 289 * The structure where the parameters will be stored. Memory
vcoubard 1131:692ddf04fc42 290 * for this is owned by the caller.
vcoubard 1131:692ddf04fc42 291 *
vcoubard 1131:692ddf04fc42 292 * @return BLE_ERROR_NONE if the parameters were successfully filled into
vcoubard 1131:692ddf04fc42 293 * the given structure pointed to by params.
vcoubard 1131:692ddf04fc42 294 */
vcoubard 1131:692ddf04fc42 295 virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
vcoubard 1131:692ddf04fc42 296 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 297 (void)params;
vcoubard 1131:692ddf04fc42 298
vcoubard 1131:692ddf04fc42 299 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 300 }
vcoubard 1131:692ddf04fc42 301
vcoubard 1131:692ddf04fc42 302 /**
vcoubard 1131:692ddf04fc42 303 * Set the GAP peripheral preferred connection parameters. These are the
vcoubard 1131:692ddf04fc42 304 * defaults that the peripheral would like to have in a connection. The
vcoubard 1131:692ddf04fc42 305 * choice of the connection parameters is eventually up to the central.
vcoubard 1131:692ddf04fc42 306 *
vcoubard 1131:692ddf04fc42 307 * @param[in] params
vcoubard 1131:692ddf04fc42 308 * The structure containing the desired parameters.
vcoubard 1131:692ddf04fc42 309 */
vcoubard 1131:692ddf04fc42 310 virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
vcoubard 1131:692ddf04fc42 311 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 312 (void)params;
vcoubard 1131:692ddf04fc42 313
vcoubard 1131:692ddf04fc42 314 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 315 }
vcoubard 1131:692ddf04fc42 316
vcoubard 1131:692ddf04fc42 317 /**
vcoubard 1131:692ddf04fc42 318 * Update connection parameters.
vcoubard 1131:692ddf04fc42 319 * In the central role this will initiate a Link Layer connection parameter update procedure.
vcoubard 1131:692ddf04fc42 320 * In the peripheral role, this will send the corresponding L2CAP request and wait for
vcoubard 1131:692ddf04fc42 321 * the central to perform the procedure.
vcoubard 1131:692ddf04fc42 322 *
vcoubard 1131:692ddf04fc42 323 * @param[in] handle
vcoubard 1131:692ddf04fc42 324 * Connection Handle.
vcoubard 1131:692ddf04fc42 325 * @param[in] params
vcoubard 1131:692ddf04fc42 326 * Pointer to desired connection parameters. If NULL is provided on a peripheral role,
vcoubard 1131:692ddf04fc42 327 * the parameters in the PPCP characteristic of the GAP service will be used instead.
vcoubard 1131:692ddf04fc42 328 */
vcoubard 1131:692ddf04fc42 329 virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) {
vcoubard 1131:692ddf04fc42 330 /* avoid compiler warnings about unused variables */
vcoubard 1131:692ddf04fc42 331 (void)handle;
vcoubard 1131:692ddf04fc42 332 (void)params;
vcoubard 1131:692ddf04fc42 333
vcoubard 1131:692ddf04fc42 334 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 335 }
vcoubard 1131:692ddf04fc42 336
vcoubard 1131:692ddf04fc42 337 /**
vcoubard 1131:692ddf04fc42 338 * Set the device name characteristic in the GAP service.
vcoubard 1131:692ddf04fc42 339 * @param[in] deviceName
vcoubard 1131:692ddf04fc42 340 * The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
vcoubard 1131:692ddf04fc42 341 */
vcoubard 1131:692ddf04fc42 342 virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
vcoubard 1131:692ddf04fc42 343 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 344 (void)deviceName;
vcoubard 1131:692ddf04fc42 345
vcoubard 1131:692ddf04fc42 346 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 347 }
vcoubard 1131:692ddf04fc42 348
vcoubard 1131:692ddf04fc42 349 /**
vcoubard 1131:692ddf04fc42 350 * Get the value of the device name characteristic in the GAP service.
vcoubard 1131:692ddf04fc42 351 * @param[out] deviceName
vcoubard 1131:692ddf04fc42 352 * Pointer to an empty buffer where the UTF-8 *non NULL-
vcoubard 1131:692ddf04fc42 353 * terminated* string will be placed. Set this
vcoubard 1131:692ddf04fc42 354 * value to NULL in order to obtain the deviceName-length
vcoubard 1131:692ddf04fc42 355 * from the 'length' parameter.
vcoubard 1131:692ddf04fc42 356 *
vcoubard 1131:692ddf04fc42 357 * @param[in/out] lengthP
vcoubard 1131:692ddf04fc42 358 * (on input) Length of the buffer pointed to by deviceName;
vcoubard 1131:692ddf04fc42 359 * (on output) the complete device name length (without the
vcoubard 1131:692ddf04fc42 360 * null terminator).
vcoubard 1131:692ddf04fc42 361 *
vcoubard 1131:692ddf04fc42 362 * @note If the device name is longer than the size of the supplied buffer,
vcoubard 1131:692ddf04fc42 363 * length will return the complete device name length, and not the
vcoubard 1131:692ddf04fc42 364 * number of bytes actually returned in deviceName. The application may
vcoubard 1131:692ddf04fc42 365 * use this information to retry with a suitable buffer size.
vcoubard 1131:692ddf04fc42 366 */
vcoubard 1131:692ddf04fc42 367 virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
vcoubard 1131:692ddf04fc42 368 /* avoid compiler warnings about unused variables */
vcoubard 1131:692ddf04fc42 369 (void)deviceName;
vcoubard 1131:692ddf04fc42 370 (void)lengthP;
vcoubard 1131:692ddf04fc42 371
vcoubard 1131:692ddf04fc42 372 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 373 }
vcoubard 1131:692ddf04fc42 374
vcoubard 1131:692ddf04fc42 375 /**
vcoubard 1131:692ddf04fc42 376 * Set the appearance characteristic in the GAP service.
vcoubard 1131:692ddf04fc42 377 * @param[in] appearance
vcoubard 1131:692ddf04fc42 378 * The new value for the device-appearance.
vcoubard 1131:692ddf04fc42 379 */
vcoubard 1131:692ddf04fc42 380 virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
vcoubard 1131:692ddf04fc42 381 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 382 (void)appearance;
vcoubard 1131:692ddf04fc42 383
vcoubard 1131:692ddf04fc42 384 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 385 }
vcoubard 1131:692ddf04fc42 386
vcoubard 1131:692ddf04fc42 387 /**
vcoubard 1131:692ddf04fc42 388 * Get the appearance characteristic in the GAP service.
vcoubard 1131:692ddf04fc42 389 * @param[out] appearance
vcoubard 1131:692ddf04fc42 390 * The new value for the device-appearance.
vcoubard 1131:692ddf04fc42 391 */
vcoubard 1131:692ddf04fc42 392 virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
vcoubard 1131:692ddf04fc42 393 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 394 (void)appearanceP;
vcoubard 1131:692ddf04fc42 395
vcoubard 1131:692ddf04fc42 396 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 397 }
vcoubard 1131:692ddf04fc42 398
vcoubard 1131:692ddf04fc42 399 /**
vcoubard 1131:692ddf04fc42 400 * Set the radio's transmit power.
vcoubard 1131:692ddf04fc42 401 * @param[in] txPower Radio transmit power in dBm.
vcoubard 1131:692ddf04fc42 402 */
vcoubard 1131:692ddf04fc42 403 virtual ble_error_t setTxPower(int8_t txPower) {
vcoubard 1131:692ddf04fc42 404 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 405 (void)txPower;
vcoubard 1131:692ddf04fc42 406
vcoubard 1131:692ddf04fc42 407 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 408 }
vcoubard 1131:692ddf04fc42 409
vcoubard 1131:692ddf04fc42 410 /**
vcoubard 1131:692ddf04fc42 411 * Query the underlying stack for permitted arguments for setTxPower().
vcoubard 1131:692ddf04fc42 412 *
vcoubard 1131:692ddf04fc42 413 * @param[out] valueArrayPP
vcoubard 1131:692ddf04fc42 414 * Out parameter to receive the immutable array of Tx values.
vcoubard 1131:692ddf04fc42 415 * @param[out] countP
vcoubard 1131:692ddf04fc42 416 * Out parameter to receive the array's size.
vcoubard 1131:692ddf04fc42 417 */
vcoubard 1131:692ddf04fc42 418 virtual void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
vcoubard 1131:692ddf04fc42 419 /* Avoid compiler warnings about unused variables. */
vcoubard 1131:692ddf04fc42 420 (void)valueArrayPP;
vcoubard 1131:692ddf04fc42 421 (void)countP;
vcoubard 1131:692ddf04fc42 422
vcoubard 1131:692ddf04fc42 423 *countP = 0; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 424 }
vcoubard 1131:692ddf04fc42 425
vcoubard 1131:692ddf04fc42 426 protected:
vcoubard 1131:692ddf04fc42 427 /* Override the following in the underlying adaptation layer to provide the functionality of scanning. */
vcoubard 1131:692ddf04fc42 428 virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams) {
vcoubard 1131:692ddf04fc42 429 (void)scanningParams;
vcoubard 1131:692ddf04fc42 430 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 431 }
vcoubard 1131:692ddf04fc42 432
vcoubard 1131:692ddf04fc42 433 /*
vcoubard 1131:692ddf04fc42 434 * APIs with non-virtual implementations.
vcoubard 1131:692ddf04fc42 435 */
vcoubard 1131:692ddf04fc42 436 public:
vcoubard 1131:692ddf04fc42 437 /**
vcoubard 1131:692ddf04fc42 438 * Returns the current GAP state of the device using a bitmask that
vcoubard 1131:692ddf04fc42 439 * describes whether the device is advertising or connected.
vcoubard 1131:692ddf04fc42 440 */
vcoubard 1131:692ddf04fc42 441 GapState_t getState(void) const {
vcoubard 1131:692ddf04fc42 442 return state;
vcoubard 1131:692ddf04fc42 443 }
vcoubard 1131:692ddf04fc42 444
vcoubard 1131:692ddf04fc42 445 /**
vcoubard 1131:692ddf04fc42 446 * Set the GAP advertising mode to use for this device.
vcoubard 1131:692ddf04fc42 447 */
vcoubard 1131:692ddf04fc42 448 void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType) {
vcoubard 1131:692ddf04fc42 449 _advParams.setAdvertisingType(advType);
vcoubard 1131:692ddf04fc42 450 }
vcoubard 1131:692ddf04fc42 451
vcoubard 1131:692ddf04fc42 452 /**
vcoubard 1131:692ddf04fc42 453 * @param[in] interval
vcoubard 1131:692ddf04fc42 454 * Advertising interval in units of milliseconds. Advertising
vcoubard 1131:692ddf04fc42 455 * is disabled if interval is 0. If interval is smaller than
vcoubard 1131:692ddf04fc42 456 * the minimum supported value, then the minimum supported
vcoubard 1131:692ddf04fc42 457 * value is used instead. This minimum value can be discovered
vcoubard 1131:692ddf04fc42 458 * using getMinAdvertisingInterval().
vcoubard 1131:692ddf04fc42 459 *
vcoubard 1131:692ddf04fc42 460 * This field must be set to 0 if connectionMode is equal
vcoubard 1131:692ddf04fc42 461 * to ADV_CONNECTABLE_DIRECTED.
vcoubard 1131:692ddf04fc42 462 *
vcoubard 1131:692ddf04fc42 463 * @note: Decreasing this value will allow central devices to detect a
vcoubard 1131:692ddf04fc42 464 * peripheral faster, at the expense of more power being used by the radio
vcoubard 1131:692ddf04fc42 465 * due to the higher data transmit rate.
vcoubard 1131:692ddf04fc42 466 *
vcoubard 1131:692ddf04fc42 467 * @note: This API is now *deprecated* and will be dropped in the future.
vcoubard 1131:692ddf04fc42 468 * You should use the parallel API from Gap directly. A former call to
vcoubard 1131:692ddf04fc42 469 * ble.setAdvertisingInterval(...) should now be achieved using
vcoubard 1131:692ddf04fc42 470 * ble.gap().setAdvertisingInterval(...).
vcoubard 1131:692ddf04fc42 471 *
vcoubard 1131:692ddf04fc42 472 * @Note: [WARNING] This API previously used 0.625ms as the unit for its
vcoubard 1131:692ddf04fc42 473 * 'interval' argument. That required an explicit conversion from
vcoubard 1131:692ddf04fc42 474 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
vcoubard 1131:692ddf04fc42 475 * no longer required as the new units are milliseconds. Any application
vcoubard 1131:692ddf04fc42 476 * code depending on the old semantics needs to be updated accordingly.
vcoubard 1131:692ddf04fc42 477 */
vcoubard 1131:692ddf04fc42 478 void setAdvertisingInterval(uint16_t interval) {
vcoubard 1131:692ddf04fc42 479 if (interval == 0) {
vcoubard 1131:692ddf04fc42 480 stopAdvertising();
vcoubard 1131:692ddf04fc42 481 } else if (interval < getMinAdvertisingInterval()) {
vcoubard 1131:692ddf04fc42 482 interval = getMinAdvertisingInterval();
vcoubard 1131:692ddf04fc42 483 }
vcoubard 1131:692ddf04fc42 484 _advParams.setInterval(interval);
vcoubard 1131:692ddf04fc42 485 }
vcoubard 1131:692ddf04fc42 486
vcoubard 1131:692ddf04fc42 487 /**
vcoubard 1131:692ddf04fc42 488 * @param[in] timeout
vcoubard 1131:692ddf04fc42 489 * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
vcoubard 1131:692ddf04fc42 490 * and 16383). Use 0 to disable the advertising timeout.
vcoubard 1131:692ddf04fc42 491 */
vcoubard 1131:692ddf04fc42 492 void setAdvertisingTimeout(uint16_t timeout) {
vcoubard 1131:692ddf04fc42 493 _advParams.setTimeout(timeout);
vcoubard 1131:692ddf04fc42 494 }
vcoubard 1131:692ddf04fc42 495
vcoubard 1131:692ddf04fc42 496 /**
vcoubard 1131:692ddf04fc42 497 * Start advertising.
vcoubard 1131:692ddf04fc42 498 */
vcoubard 1131:692ddf04fc42 499 ble_error_t startAdvertising(void) {
vcoubard 1131:692ddf04fc42 500 setAdvertisingData(); /* Update the underlying stack. */
vcoubard 1131:692ddf04fc42 501 return startAdvertising(_advParams);
vcoubard 1131:692ddf04fc42 502 }
vcoubard 1131:692ddf04fc42 503
vcoubard 1131:692ddf04fc42 504 /**
vcoubard 1131:692ddf04fc42 505 * Reset any advertising payload prepared from prior calls to
vcoubard 1131:692ddf04fc42 506 * accumulateAdvertisingPayload(). This automatically propagates the re-
vcoubard 1131:692ddf04fc42 507 * initialized advertising payload to the underlying stack.
vcoubard 1131:692ddf04fc42 508 */
vcoubard 1131:692ddf04fc42 509 void clearAdvertisingPayload(void) {
vcoubard 1131:692ddf04fc42 510 _advPayload.clear();
vcoubard 1131:692ddf04fc42 511 setAdvertisingData();
vcoubard 1131:692ddf04fc42 512 }
vcoubard 1131:692ddf04fc42 513
vcoubard 1131:692ddf04fc42 514 /**
vcoubard 1131:692ddf04fc42 515 * Accumulate an AD structure in the advertising payload. Please note that
vcoubard 1131:692ddf04fc42 516 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1131:692ddf04fc42 517 * as an additional 31 bytes if the advertising payload is too
vcoubard 1131:692ddf04fc42 518 * small.
vcoubard 1131:692ddf04fc42 519 *
vcoubard 1131:692ddf04fc42 520 * @param[in] flags
vcoubard 1131:692ddf04fc42 521 * The flags to be added. Please refer to
vcoubard 1131:692ddf04fc42 522 * GapAdvertisingData::Flags for valid flags. Multiple
vcoubard 1131:692ddf04fc42 523 * flags may be specified in combination.
vcoubard 1131:692ddf04fc42 524 */
vcoubard 1131:692ddf04fc42 525 ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
vcoubard 1131:692ddf04fc42 526 ble_error_t rc;
vcoubard 1131:692ddf04fc42 527 if ((rc = _advPayload.addFlags(flags)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 528 return rc;
vcoubard 1131:692ddf04fc42 529 }
vcoubard 1131:692ddf04fc42 530
vcoubard 1131:692ddf04fc42 531 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 532 }
vcoubard 1131:692ddf04fc42 533
vcoubard 1131:692ddf04fc42 534 /**
vcoubard 1131:692ddf04fc42 535 * Accumulate an AD structure in the advertising payload. Please note that
vcoubard 1131:692ddf04fc42 536 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1131:692ddf04fc42 537 * as an additional 31 bytes if the advertising payload is too
vcoubard 1131:692ddf04fc42 538 * small.
vcoubard 1131:692ddf04fc42 539 *
vcoubard 1131:692ddf04fc42 540 * @param app
vcoubard 1131:692ddf04fc42 541 * The appearance of the peripheral.
vcoubard 1131:692ddf04fc42 542 */
vcoubard 1131:692ddf04fc42 543 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
vcoubard 1131:692ddf04fc42 544 setAppearance(app);
vcoubard 1131:692ddf04fc42 545
vcoubard 1131:692ddf04fc42 546 ble_error_t rc;
vcoubard 1131:692ddf04fc42 547 if ((rc = _advPayload.addAppearance(app)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 548 return rc;
vcoubard 1131:692ddf04fc42 549 }
vcoubard 1131:692ddf04fc42 550
vcoubard 1131:692ddf04fc42 551 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 552 }
vcoubard 1131:692ddf04fc42 553
vcoubard 1131:692ddf04fc42 554 /**
vcoubard 1131:692ddf04fc42 555 * Accumulate an AD structure in the advertising payload. Please note that
vcoubard 1131:692ddf04fc42 556 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard 1131:692ddf04fc42 557 * as an additional 31 bytes if the advertising payload is too
vcoubard 1131:692ddf04fc42 558 * small.
vcoubard 1131:692ddf04fc42 559 *
vcoubard 1131:692ddf04fc42 560 * @param power
vcoubard 1131:692ddf04fc42 561 * The max transmit power to be used by the controller (in dBm).
vcoubard 1131:692ddf04fc42 562 */
vcoubard 1131:692ddf04fc42 563 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
vcoubard 1131:692ddf04fc42 564 ble_error_t rc;
vcoubard 1131:692ddf04fc42 565 if ((rc = _advPayload.addTxPower(power)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 566 return rc;
vcoubard 1131:692ddf04fc42 567 }
vcoubard 1131:692ddf04fc42 568
vcoubard 1131:692ddf04fc42 569 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 570 }
vcoubard 1131:692ddf04fc42 571
vcoubard 1131:692ddf04fc42 572 /**
vcoubard 1131:692ddf04fc42 573 * Accumulate a variable length byte-stream as an AD structure in the
vcoubard 1131:692ddf04fc42 574 * advertising payload. Please note that the payload is limited to 31 bytes.
vcoubard 1131:692ddf04fc42 575 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
vcoubard 1131:692ddf04fc42 576 * advertising payload is too small.
vcoubard 1131:692ddf04fc42 577 *
vcoubard 1131:692ddf04fc42 578 * @param type The type describing the variable length data.
vcoubard 1131:692ddf04fc42 579 * @param data Data bytes.
vcoubard 1131:692ddf04fc42 580 * @param len Length of data.
vcoubard 1131:692ddf04fc42 581 */
vcoubard 1131:692ddf04fc42 582 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard 1131:692ddf04fc42 583 if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
vcoubard 1131:692ddf04fc42 584 setDeviceName(data);
vcoubard 1131:692ddf04fc42 585 }
vcoubard 1131:692ddf04fc42 586
vcoubard 1131:692ddf04fc42 587 ble_error_t rc;
vcoubard 1131:692ddf04fc42 588 if ((rc = _advPayload.addData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 589 return rc;
vcoubard 1131:692ddf04fc42 590 }
vcoubard 1131:692ddf04fc42 591
vcoubard 1131:692ddf04fc42 592 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 593 }
vcoubard 1131:692ddf04fc42 594
vcoubard 1131:692ddf04fc42 595 /**
vcoubard 1131:692ddf04fc42 596 * Update a particular ADV field in the advertising payload (based on
vcoubard 1131:692ddf04fc42 597 * matching type and length). Note: the length of the new data must be the
vcoubard 1131:692ddf04fc42 598 * same as the old one.
vcoubard 1131:692ddf04fc42 599 *
vcoubard 1131:692ddf04fc42 600 * @param[in] type The ADV type field describing the variable length data.
vcoubard 1131:692ddf04fc42 601 * @param[in] data Data bytes.
vcoubard 1131:692ddf04fc42 602 * @param[in] len Length of data.
vcoubard 1131:692ddf04fc42 603 *
vcoubard 1131:692ddf04fc42 604 * @note: If advertisements are enabled, then the update will take effect immediately.
vcoubard 1131:692ddf04fc42 605 *
vcoubard 1131:692ddf04fc42 606 * @return BLE_ERROR_NONE if the advertisement payload was updated based on
vcoubard 1131:692ddf04fc42 607 * a <type, len> match; otherwise, an appropriate error.
vcoubard 1131:692ddf04fc42 608 */
vcoubard 1131:692ddf04fc42 609 ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard 1131:692ddf04fc42 610 if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
vcoubard 1131:692ddf04fc42 611 setDeviceName(data);
vcoubard 1131:692ddf04fc42 612 }
vcoubard 1131:692ddf04fc42 613
vcoubard 1131:692ddf04fc42 614 ble_error_t rc;
vcoubard 1131:692ddf04fc42 615 if ((rc = _advPayload.updateData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 616 return rc;
vcoubard 1131:692ddf04fc42 617 }
vcoubard 1131:692ddf04fc42 618
vcoubard 1131:692ddf04fc42 619 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 620 }
vcoubard 1131:692ddf04fc42 621
vcoubard 1131:692ddf04fc42 622 /**
vcoubard 1131:692ddf04fc42 623 * Set up a particular, user-constructed advertisement payload for the
vcoubard 1131:692ddf04fc42 624 * underlying stack. It would be uncommon for this API to be used directly;
vcoubard 1131:692ddf04fc42 625 * there are other APIs to build an advertisement payload (see above).
vcoubard 1131:692ddf04fc42 626 */
vcoubard 1131:692ddf04fc42 627 ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) {
vcoubard 1131:692ddf04fc42 628 _advPayload = payload;
vcoubard 1131:692ddf04fc42 629 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 630 }
vcoubard 1131:692ddf04fc42 631
vcoubard 1131:692ddf04fc42 632 /**
vcoubard 1131:692ddf04fc42 633 * @return Read back advertising data. Useful for storing and
vcoubard 1131:692ddf04fc42 634 * restoring payload.
vcoubard 1131:692ddf04fc42 635 */
vcoubard 1131:692ddf04fc42 636 const GapAdvertisingData &getAdvertisingPayload(void) const {
vcoubard 1131:692ddf04fc42 637 return _advPayload;
vcoubard 1131:692ddf04fc42 638 }
vcoubard 1131:692ddf04fc42 639
vcoubard 1131:692ddf04fc42 640 /**
vcoubard 1131:692ddf04fc42 641 * Accumulate a variable length byte-stream as an AD structure in the
vcoubard 1131:692ddf04fc42 642 * scanResponse payload.
vcoubard 1131:692ddf04fc42 643 *
vcoubard 1131:692ddf04fc42 644 * @param[in] type The type describing the variable length data.
vcoubard 1131:692ddf04fc42 645 * @param[in] data Data bytes.
vcoubard 1131:692ddf04fc42 646 * @param[in] len Length of data.
vcoubard 1131:692ddf04fc42 647 */
vcoubard 1131:692ddf04fc42 648 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard 1131:692ddf04fc42 649 ble_error_t rc;
vcoubard 1131:692ddf04fc42 650 if ((rc = _scanResponse.addData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 651 return rc;
vcoubard 1131:692ddf04fc42 652 }
vcoubard 1131:692ddf04fc42 653
vcoubard 1131:692ddf04fc42 654 return setAdvertisingData();
vcoubard 1131:692ddf04fc42 655 }
vcoubard 1131:692ddf04fc42 656
vcoubard 1131:692ddf04fc42 657 /**
vcoubard 1131:692ddf04fc42 658 * Reset any scan response prepared from prior calls to
vcoubard 1131:692ddf04fc42 659 * accumulateScanResponse().
vcoubard 1131:692ddf04fc42 660 *
vcoubard 1131:692ddf04fc42 661 * Note: This should be followed by a call to setAdvertisingPayload() or
vcoubard 1131:692ddf04fc42 662 * startAdvertising() before the update takes effect.
vcoubard 1131:692ddf04fc42 663 */
vcoubard 1131:692ddf04fc42 664 void clearScanResponse(void) {
vcoubard 1131:692ddf04fc42 665 _scanResponse.clear();
vcoubard 1131:692ddf04fc42 666 setAdvertisingData();
vcoubard 1131:692ddf04fc42 667 }
vcoubard 1131:692ddf04fc42 668
vcoubard 1131:692ddf04fc42 669 /**
vcoubard 1131:692ddf04fc42 670 * Set up parameters for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 671 * @param[in] interval
vcoubard 1131:692ddf04fc42 672 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 673 * @param[in] window
vcoubard 1131:692ddf04fc42 674 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 675 * @param[in] timeout
vcoubard 1131:692ddf04fc42 676 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
vcoubard 1131:692ddf04fc42 677 * @param[in] activeScanning
vcoubard 1131:692ddf04fc42 678 * Set to True if active-scanning is required. This is used to fetch the
vcoubard 1131:692ddf04fc42 679 * scan response from a peer if possible.
vcoubard 1131:692ddf04fc42 680 *
vcoubard 1131:692ddf04fc42 681 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1131:692ddf04fc42 682 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1131:692ddf04fc42 683 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1131:692ddf04fc42 684 * to have the interval and window set to the same value. In this case,
vcoubard 1131:692ddf04fc42 685 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1131:692ddf04fc42 686 * interval.
vcoubard 1131:692ddf04fc42 687 *
vcoubard 1131:692ddf04fc42 688 * Once the scanning parameters have been configured, scanning can be
vcoubard 1131:692ddf04fc42 689 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 690 *
vcoubard 1131:692ddf04fc42 691 * @Note: The scan interval and window are recommendations to the BLE stack.
vcoubard 1131:692ddf04fc42 692 */
vcoubard 1131:692ddf04fc42 693 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
vcoubard 1131:692ddf04fc42 694 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
vcoubard 1131:692ddf04fc42 695 uint16_t timeout = 0,
vcoubard 1131:692ddf04fc42 696 bool activeScanning = false) {
vcoubard 1131:692ddf04fc42 697 ble_error_t rc;
vcoubard 1131:692ddf04fc42 698 if (((rc = _scanningParams.setInterval(interval)) == BLE_ERROR_NONE) &&
vcoubard 1131:692ddf04fc42 699 ((rc = _scanningParams.setWindow(window)) == BLE_ERROR_NONE) &&
vcoubard 1131:692ddf04fc42 700 ((rc = _scanningParams.setTimeout(timeout)) == BLE_ERROR_NONE)) {
vcoubard 1131:692ddf04fc42 701 _scanningParams.setActiveScanning(activeScanning);
vcoubard 1131:692ddf04fc42 702 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 703 }
vcoubard 1131:692ddf04fc42 704
vcoubard 1131:692ddf04fc42 705 return rc;
vcoubard 1131:692ddf04fc42 706 }
vcoubard 1131:692ddf04fc42 707
vcoubard 1131:692ddf04fc42 708 /**
vcoubard 1131:692ddf04fc42 709 * Set up the scanInterval parameter for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 710 * @param[in] interval
vcoubard 1131:692ddf04fc42 711 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 712 *
vcoubard 1131:692ddf04fc42 713 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1131:692ddf04fc42 714 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1131:692ddf04fc42 715 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1131:692ddf04fc42 716 * to have the interval and window set to the same value. In this case,
vcoubard 1131:692ddf04fc42 717 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1131:692ddf04fc42 718 * interval.
vcoubard 1131:692ddf04fc42 719 *
vcoubard 1131:692ddf04fc42 720 * Once the scanning parameters have been configured, scanning can be
vcoubard 1131:692ddf04fc42 721 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 722 */
vcoubard 1131:692ddf04fc42 723 ble_error_t setScanInterval(uint16_t interval) {
vcoubard 1131:692ddf04fc42 724 return _scanningParams.setInterval(interval);
vcoubard 1131:692ddf04fc42 725 }
vcoubard 1131:692ddf04fc42 726
vcoubard 1131:692ddf04fc42 727 /**
vcoubard 1131:692ddf04fc42 728 * Set up the scanWindow parameter for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 729 * @param[in] window
vcoubard 1131:692ddf04fc42 730 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard 1131:692ddf04fc42 731 *
vcoubard 1131:692ddf04fc42 732 * The scanning window divided by the interval determines the duty cycle for
vcoubard 1131:692ddf04fc42 733 * scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard 1131:692ddf04fc42 734 * then the controller will scan for 10 percent of the time. It is possible
vcoubard 1131:692ddf04fc42 735 * to have the interval and window set to the same value. In this case,
vcoubard 1131:692ddf04fc42 736 * scanning is continuous, with a change of scanning frequency once every
vcoubard 1131:692ddf04fc42 737 * interval.
vcoubard 1131:692ddf04fc42 738 *
vcoubard 1131:692ddf04fc42 739 * Once the scanning parameters have been configured, scanning can be
vcoubard 1131:692ddf04fc42 740 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 741 *
vcoubard 1131:692ddf04fc42 742 * If scanning is already active, the updated value of scanWindow will be
vcoubard 1131:692ddf04fc42 743 * propagated to the underlying BLE stack.
vcoubard 1131:692ddf04fc42 744 */
vcoubard 1131:692ddf04fc42 745 ble_error_t setScanWindow(uint16_t window) {
vcoubard 1131:692ddf04fc42 746 ble_error_t rc;
vcoubard 1131:692ddf04fc42 747 if ((rc = _scanningParams.setWindow(window)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 748 return rc;
vcoubard 1131:692ddf04fc42 749 }
vcoubard 1131:692ddf04fc42 750
vcoubard 1131:692ddf04fc42 751 /* If scanning is already active, propagate the new setting to the stack. */
vcoubard 1131:692ddf04fc42 752 if (scanningActive) {
vcoubard 1131:692ddf04fc42 753 return startRadioScan(_scanningParams);
vcoubard 1131:692ddf04fc42 754 }
vcoubard 1131:692ddf04fc42 755
vcoubard 1131:692ddf04fc42 756 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 757 }
vcoubard 1131:692ddf04fc42 758
vcoubard 1131:692ddf04fc42 759 /**
vcoubard 1131:692ddf04fc42 760 * Set up parameters for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 761 * @param[in] timeout
vcoubard 1131:692ddf04fc42 762 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
vcoubard 1131:692ddf04fc42 763 *
vcoubard 1131:692ddf04fc42 764 * Once the scanning parameters have been configured, scanning can be
vcoubard 1131:692ddf04fc42 765 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 766 *
vcoubard 1131:692ddf04fc42 767 * If scanning is already active, the updated value of scanTimeout will be
vcoubard 1131:692ddf04fc42 768 * propagated to the underlying BLE stack.
vcoubard 1131:692ddf04fc42 769 */
vcoubard 1131:692ddf04fc42 770 ble_error_t setScanTimeout(uint16_t timeout) {
vcoubard 1131:692ddf04fc42 771 ble_error_t rc;
vcoubard 1131:692ddf04fc42 772 if ((rc = _scanningParams.setTimeout(timeout)) != BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 773 return rc;
vcoubard 1131:692ddf04fc42 774 }
vcoubard 1131:692ddf04fc42 775
vcoubard 1131:692ddf04fc42 776 /* If scanning is already active, propagate the new settings to the stack. */
vcoubard 1131:692ddf04fc42 777 if (scanningActive) {
vcoubard 1131:692ddf04fc42 778 return startRadioScan(_scanningParams);
vcoubard 1131:692ddf04fc42 779 }
vcoubard 1131:692ddf04fc42 780
vcoubard 1131:692ddf04fc42 781 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 782 }
vcoubard 1131:692ddf04fc42 783
vcoubard 1131:692ddf04fc42 784 /**
vcoubard 1131:692ddf04fc42 785 * Set up parameters for GAP scanning (observer mode).
vcoubard 1131:692ddf04fc42 786 * @param[in] activeScanning
vcoubard 1131:692ddf04fc42 787 * Set to True if active-scanning is required. This is used to fetch the
vcoubard 1131:692ddf04fc42 788 * scan response from a peer if possible.
vcoubard 1131:692ddf04fc42 789 *
vcoubard 1131:692ddf04fc42 790 * Once the scanning parameters have been configured, scanning can be
vcoubard 1131:692ddf04fc42 791 * enabled by using startScan().
vcoubard 1131:692ddf04fc42 792 *
vcoubard 1131:692ddf04fc42 793 * If scanning is already in progress, then active-scanning will be enabled
vcoubard 1131:692ddf04fc42 794 * for the underlying BLE stack.
vcoubard 1131:692ddf04fc42 795 */
vcoubard 1131:692ddf04fc42 796 ble_error_t setActiveScanning(bool activeScanning) {
vcoubard 1131:692ddf04fc42 797 _scanningParams.setActiveScanning(activeScanning);
vcoubard 1131:692ddf04fc42 798
vcoubard 1131:692ddf04fc42 799 /* If scanning is already active, propagate the new settings to the stack. */
vcoubard 1131:692ddf04fc42 800 if (scanningActive) {
vcoubard 1131:692ddf04fc42 801 return startRadioScan(_scanningParams);
vcoubard 1131:692ddf04fc42 802 }
vcoubard 1131:692ddf04fc42 803
vcoubard 1131:692ddf04fc42 804 return BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 805 }
vcoubard 1131:692ddf04fc42 806
vcoubard 1131:692ddf04fc42 807 /**
vcoubard 1131:692ddf04fc42 808 * Start scanning (Observer Procedure) based on the parameters currently in
vcoubard 1131:692ddf04fc42 809 * effect.
vcoubard 1131:692ddf04fc42 810 *
vcoubard 1131:692ddf04fc42 811 * @param[in] callback
vcoubard 1131:692ddf04fc42 812 * The application-specific callback to be invoked upon
vcoubard 1131:692ddf04fc42 813 * receiving every advertisement report. This can be passed in
vcoubard 1131:692ddf04fc42 814 * as NULL, in which case scanning may not be enabled at all.
vcoubard 1131:692ddf04fc42 815 */
vcoubard 1131:692ddf04fc42 816 ble_error_t startScan(void (*callback)(const AdvertisementCallbackParams_t *params)) {
vcoubard 1131:692ddf04fc42 817 ble_error_t err = BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 818 if (callback) {
vcoubard 1131:692ddf04fc42 819 if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 820 scanningActive = true;
vcoubard 1131:692ddf04fc42 821 onAdvertisementReport.attach(callback);
vcoubard 1131:692ddf04fc42 822 }
vcoubard 1131:692ddf04fc42 823 }
vcoubard 1131:692ddf04fc42 824
vcoubard 1131:692ddf04fc42 825 return err;
vcoubard 1131:692ddf04fc42 826 }
vcoubard 1131:692ddf04fc42 827
vcoubard 1131:692ddf04fc42 828 /**
vcoubard 1131:692ddf04fc42 829 * Same as above, but this takes an (object, method) pair for a callback.
vcoubard 1131:692ddf04fc42 830 */
vcoubard 1131:692ddf04fc42 831 template<typename T>
vcoubard 1131:692ddf04fc42 832 ble_error_t startScan(T *object, void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)) {
vcoubard 1131:692ddf04fc42 833 ble_error_t err = BLE_ERROR_NONE;
vcoubard 1131:692ddf04fc42 834 if (object && callbackMember) {
vcoubard 1131:692ddf04fc42 835 if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
vcoubard 1131:692ddf04fc42 836 scanningActive = true;
vcoubard 1131:692ddf04fc42 837 onAdvertisementReport.attach(object, callbackMember);
vcoubard 1131:692ddf04fc42 838 }
vcoubard 1131:692ddf04fc42 839 }
vcoubard 1131:692ddf04fc42 840
vcoubard 1131:692ddf04fc42 841 return err;
vcoubard 1131:692ddf04fc42 842 }
vcoubard 1131:692ddf04fc42 843
vcoubard 1131:692ddf04fc42 844 /**
vcoubard 1131:692ddf04fc42 845 * Initialize radio-notification events to be generated from the stack.
vcoubard 1131:692ddf04fc42 846 * This API doesn't need to be called directly.
vcoubard 1131:692ddf04fc42 847 *
vcoubard 1131:692ddf04fc42 848 * Radio Notification is a feature that enables ACTIVE and INACTIVE
vcoubard 1131:692ddf04fc42 849 * (nACTIVE) signals from the stack that notify the application when the
vcoubard 1131:692ddf04fc42 850 * radio is in use.
vcoubard 1131:692ddf04fc42 851 *
vcoubard 1131:692ddf04fc42 852 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard 1131:692ddf04fc42 853 * signal is sent at the end of the radio event. These signals can be used
vcoubard 1131:692ddf04fc42 854 * by the application programmer to synchronize application logic with radio
vcoubard 1131:692ddf04fc42 855 * activity. For example, the ACTIVE signal can be used to shut off external
vcoubard 1131:692ddf04fc42 856 * devices, to manage peak current drawn during periods when the radio is on,
vcoubard 1131:692ddf04fc42 857 * or to trigger sensor data collection for transmission in the Radio Event.
vcoubard 1131:692ddf04fc42 858 *
vcoubard 1131:692ddf04fc42 859 * @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
vcoubard 1131:692ddf04fc42 860 */
vcoubard 1131:692ddf04fc42 861 virtual ble_error_t initRadioNotification(void) {
vcoubard 1131:692ddf04fc42 862 return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard 1131:692ddf04fc42 863 }
vcoubard 1131:692ddf04fc42 864
vcoubard 1131:692ddf04fc42 865 private:
vcoubard 1131:692ddf04fc42 866 ble_error_t setAdvertisingData(void) {
vcoubard 1131:692ddf04fc42 867 return setAdvertisingData(_advPayload, _scanResponse);
vcoubard 1131:692ddf04fc42 868 }
vcoubard 1131:692ddf04fc42 869
vcoubard 1131:692ddf04fc42 870 private:
vcoubard 1131:692ddf04fc42 871 virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0;
vcoubard 1131:692ddf04fc42 872 virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
vcoubard 1131:692ddf04fc42 873
vcoubard 1131:692ddf04fc42 874 public:
vcoubard 1131:692ddf04fc42 875 /**
vcoubard 1131:692ddf04fc42 876 * Accessors to read back currently active advertising params.
vcoubard 1131:692ddf04fc42 877 */
vcoubard 1131:692ddf04fc42 878 GapAdvertisingParams &getAdvertisingParams(void) {
vcoubard 1131:692ddf04fc42 879 return _advParams;
vcoubard 1131:692ddf04fc42 880 }
vcoubard 1131:692ddf04fc42 881 const GapAdvertisingParams &getAdvertisingParams(void) const {
vcoubard 1131:692ddf04fc42 882 return _advParams;
vcoubard 1131:692ddf04fc42 883 }
vcoubard 1131:692ddf04fc42 884
vcoubard 1131:692ddf04fc42 885 /**
vcoubard 1131:692ddf04fc42 886 * Set up a particular, user-constructed set of advertisement parameters for
vcoubard 1131:692ddf04fc42 887 * the underlying stack. It would be uncommon for this API to be used
vcoubard 1131:692ddf04fc42 888 * directly; there are other APIs to tweak advertisement parameters
vcoubard 1131:692ddf04fc42 889 * individually.
vcoubard 1131:692ddf04fc42 890 */
vcoubard 1131:692ddf04fc42 891 void setAdvertisingParams(const GapAdvertisingParams &newParams) {
vcoubard 1131:692ddf04fc42 892 _advParams = newParams;
vcoubard 1131:692ddf04fc42 893 }
vcoubard 1131:692ddf04fc42 894
vcoubard 1131:692ddf04fc42 895 /* Event callback handlers. */
vcoubard 1131:692ddf04fc42 896 public:
vcoubard 1131:692ddf04fc42 897 /**
vcoubard 1131:692ddf04fc42 898 * Set up a callback for timeout events. Refer to TimeoutSource_t for
vcoubard 1131:692ddf04fc42 899 * possible event types.
vcoubard 1131:692ddf04fc42 900 * @note It is possible to unregister callbacks using onTimeout().detach(callback)
vcoubard 1131:692ddf04fc42 901 */
vcoubard 1131:692ddf04fc42 902 void onTimeout(TimeoutEventCallback_t callback) {
vcoubard 1131:692ddf04fc42 903 timeoutCallbackChain.add(callback);
vcoubard 1131:692ddf04fc42 904 }
vcoubard 1131:692ddf04fc42 905
vcoubard 1131:692ddf04fc42 906 /**
vcoubard 1131:692ddf04fc42 907 * @brief provide access to the callchain of timeout event callbacks
vcoubard 1131:692ddf04fc42 908 * It is possible to register callbacks using onTimeout().add(callback);
vcoubard 1131:692ddf04fc42 909 * It is possible to unregister callbacks using onTimeout().detach(callback)
vcoubard 1131:692ddf04fc42 910 * @return The timeout event callbacks chain
vcoubard 1131:692ddf04fc42 911 */
vcoubard 1131:692ddf04fc42 912 TimeoutEventCallbackChain_t& onTimeout() {
vcoubard 1131:692ddf04fc42 913 return timeoutCallbackChain;
vcoubard 1131:692ddf04fc42 914 }
vcoubard 1131:692ddf04fc42 915
vcoubard 1131:692ddf04fc42 916 /**
vcoubard 1131:692ddf04fc42 917 * Append to a chain of callbacks to be invoked upon GAP connection.
vcoubard 1131:692ddf04fc42 918 * @note It is possible to unregister callbacks using onConnection().detach(callback)
vcoubard 1131:692ddf04fc42 919 */
vcoubard 1131:692ddf04fc42 920 void onConnection(ConnectionEventCallback_t callback) {connectionCallChain.add(callback);}
vcoubard 1131:692ddf04fc42 921
vcoubard 1131:692ddf04fc42 922 template<typename T>
vcoubard 1131:692ddf04fc42 923 void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
vcoubard 1131:692ddf04fc42 924
vcoubard 1131:692ddf04fc42 925 /**
vcoubard 1131:692ddf04fc42 926 * @brief provide access to the callchain of connection event callbacks
vcoubard 1131:692ddf04fc42 927 * It is possible to register callbacks using onConnection().add(callback);
vcoubard 1131:692ddf04fc42 928 * It is possible to unregister callbacks using onConnection().detach(callback)
vcoubard 1131:692ddf04fc42 929 * @return The connection event callbacks chain
vcoubard 1131:692ddf04fc42 930 */
vcoubard 1131:692ddf04fc42 931 ConnectionEventCallbackChain_t& onconnection() {
vcoubard 1131:692ddf04fc42 932 return connectionCallChain;
vcoubard 1131:692ddf04fc42 933 }
vcoubard 1131:692ddf04fc42 934
vcoubard 1131:692ddf04fc42 935 /**
vcoubard 1131:692ddf04fc42 936 * Append to a chain of callbacks to be invoked upon GAP disconnection.
vcoubard 1131:692ddf04fc42 937 * @note It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard 1131:692ddf04fc42 938 */
vcoubard 1131:692ddf04fc42 939 void onDisconnection(DisconnectionEventCallback_t callback) {disconnectionCallChain.add(callback);}
vcoubard 1131:692ddf04fc42 940
vcoubard 1131:692ddf04fc42 941 template<typename T>
vcoubard 1131:692ddf04fc42 942 void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
vcoubard 1131:692ddf04fc42 943
vcoubard 1131:692ddf04fc42 944 /**
vcoubard 1131:692ddf04fc42 945 * @brief provide access to the callchain of disconnection event callbacks
vcoubard 1131:692ddf04fc42 946 * It is possible to register callbacks using onDisconnection().add(callback);
vcoubard 1131:692ddf04fc42 947 * It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard 1131:692ddf04fc42 948 * @return The disconnection event callbacks chain
vcoubard 1131:692ddf04fc42 949 */
vcoubard 1131:692ddf04fc42 950 DisconnectionEventCallbackChain_t& onDisconnection() {
vcoubard 1131:692ddf04fc42 951 return disconnectionCallChain;
vcoubard 1131:692ddf04fc42 952 }
vcoubard 1131:692ddf04fc42 953
vcoubard 1131:692ddf04fc42 954 /**
vcoubard 1131:692ddf04fc42 955 * Set the application callback for radio-notification events.
vcoubard 1131:692ddf04fc42 956 *
vcoubard 1131:692ddf04fc42 957 * Radio Notification is a feature that enables ACTIVE and INACTIVE
vcoubard 1131:692ddf04fc42 958 * (nACTIVE) signals from the stack that notify the application when the
vcoubard 1131:692ddf04fc42 959 * radio is in use.
vcoubard 1131:692ddf04fc42 960 *
vcoubard 1131:692ddf04fc42 961 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard 1131:692ddf04fc42 962 * signal is sent at the end of the radio event. These signals can be used
vcoubard 1131:692ddf04fc42 963 * by the application programmer to synchronize application logic with radio
vcoubard 1131:692ddf04fc42 964 * activity. For example, the ACTIVE signal can be used to shut off external
vcoubard 1131:692ddf04fc42 965 * devices, to manage peak current drawn during periods when the radio is on,
vcoubard 1131:692ddf04fc42 966 * or to trigger sensor data collection for transmission in the Radio Event.
vcoubard 1131:692ddf04fc42 967 *
vcoubard 1131:692ddf04fc42 968 * @param callback
vcoubard 1131:692ddf04fc42 969 * The application handler to be invoked in response to a radio
vcoubard 1131:692ddf04fc42 970 * ACTIVE/INACTIVE event.
vcoubard 1131:692ddf04fc42 971 *
vcoubard 1131:692ddf04fc42 972 * Or in the other version:
vcoubard 1131:692ddf04fc42 973 *
vcoubard 1131:692ddf04fc42 974 * @param tptr
vcoubard 1131:692ddf04fc42 975 * Pointer to the object of a class defining the member callback
vcoubard 1131:692ddf04fc42 976 * function (mptr).
vcoubard 1131:692ddf04fc42 977 * @param mptr
vcoubard 1131:692ddf04fc42 978 * The member callback (within the context of an object) to be
vcoubard 1131:692ddf04fc42 979 * invoked in response to a radio ACTIVE/INACTIVE event.
vcoubard 1131:692ddf04fc42 980 */
vcoubard 1131:692ddf04fc42 981 void onRadioNotification(void (*callback)(bool param)) {
vcoubard 1131:692ddf04fc42 982 radioNotificationCallback.attach(callback);
vcoubard 1131:692ddf04fc42 983 }
vcoubard 1131:692ddf04fc42 984 template <typename T>
vcoubard 1131:692ddf04fc42 985 void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
vcoubard 1131:692ddf04fc42 986 radioNotificationCallback.attach(tptr, mptr);
vcoubard 1131:692ddf04fc42 987 }
vcoubard 1131:692ddf04fc42 988
vcoubard 1131:692ddf04fc42 989 protected:
vcoubard 1131:692ddf04fc42 990 Gap() :
vcoubard 1131:692ddf04fc42 991 _advParams(),
vcoubard 1131:692ddf04fc42 992 _advPayload(),
vcoubard 1131:692ddf04fc42 993 _scanningParams(),
vcoubard 1131:692ddf04fc42 994 _scanResponse(),
vcoubard 1131:692ddf04fc42 995 state(),
vcoubard 1131:692ddf04fc42 996 scanningActive(false),
vcoubard 1131:692ddf04fc42 997 timeoutCallbackChain(),
vcoubard 1131:692ddf04fc42 998 radioNotificationCallback(),
vcoubard 1131:692ddf04fc42 999 onAdvertisementReport(),
vcoubard 1131:692ddf04fc42 1000 connectionCallChain(),
vcoubard 1131:692ddf04fc42 1001 disconnectionCallChain() {
vcoubard 1131:692ddf04fc42 1002 _advPayload.clear();
vcoubard 1131:692ddf04fc42 1003 _scanResponse.clear();
vcoubard 1131:692ddf04fc42 1004 }
vcoubard 1131:692ddf04fc42 1005
vcoubard 1131:692ddf04fc42 1006 /* Entry points for the underlying stack to report events back to the user. */
vcoubard 1131:692ddf04fc42 1007 public:
vcoubard 1131:692ddf04fc42 1008 void processConnectionEvent(Handle_t handle,
vcoubard 1131:692ddf04fc42 1009 Role_t role,
vcoubard 1131:692ddf04fc42 1010 AddressType_t peerAddrType,
vcoubard 1131:692ddf04fc42 1011 const Address_t peerAddr,
vcoubard 1131:692ddf04fc42 1012 AddressType_t ownAddrType,
vcoubard 1131:692ddf04fc42 1013 const Address_t ownAddr,
vcoubard 1131:692ddf04fc42 1014 const ConnectionParams_t *connectionParams) {
vcoubard 1131:692ddf04fc42 1015 state.connected = 1;
vcoubard 1131:692ddf04fc42 1016 ConnectionCallbackParams_t callbackParams(handle, role, peerAddrType, peerAddr, ownAddrType, ownAddr, connectionParams);
vcoubard 1131:692ddf04fc42 1017 connectionCallChain.call(&callbackParams);
vcoubard 1131:692ddf04fc42 1018 }
vcoubard 1131:692ddf04fc42 1019
vcoubard 1131:692ddf04fc42 1020 void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
vcoubard 1131:692ddf04fc42 1021 state.connected = 0;
vcoubard 1131:692ddf04fc42 1022 DisconnectionCallbackParams_t callbackParams(handle, reason);
vcoubard 1131:692ddf04fc42 1023 disconnectionCallChain.call(&callbackParams);
vcoubard 1131:692ddf04fc42 1024 }
vcoubard 1131:692ddf04fc42 1025
vcoubard 1131:692ddf04fc42 1026 void processAdvertisementReport(const Address_t peerAddr,
vcoubard 1131:692ddf04fc42 1027 int8_t rssi,
vcoubard 1131:692ddf04fc42 1028 bool isScanResponse,
vcoubard 1131:692ddf04fc42 1029 GapAdvertisingParams::AdvertisingType_t type,
vcoubard 1131:692ddf04fc42 1030 uint8_t advertisingDataLen,
vcoubard 1131:692ddf04fc42 1031 const uint8_t *advertisingData) {
vcoubard 1131:692ddf04fc42 1032 AdvertisementCallbackParams_t params;
vcoubard 1131:692ddf04fc42 1033 memcpy(params.peerAddr, peerAddr, ADDR_LEN);
vcoubard 1131:692ddf04fc42 1034 params.rssi = rssi;
vcoubard 1131:692ddf04fc42 1035 params.isScanResponse = isScanResponse;
vcoubard 1131:692ddf04fc42 1036 params.type = type;
vcoubard 1131:692ddf04fc42 1037 params.advertisingDataLen = advertisingDataLen;
vcoubard 1131:692ddf04fc42 1038 params.advertisingData = advertisingData;
vcoubard 1131:692ddf04fc42 1039 onAdvertisementReport.call(&params);
vcoubard 1131:692ddf04fc42 1040 }
vcoubard 1131:692ddf04fc42 1041
vcoubard 1131:692ddf04fc42 1042 void processTimeoutEvent(TimeoutSource_t source) {
vcoubard 1131:692ddf04fc42 1043 if (timeoutCallbackChain) {
vcoubard 1131:692ddf04fc42 1044 timeoutCallbackChain(source);
vcoubard 1131:692ddf04fc42 1045 }
vcoubard 1131:692ddf04fc42 1046 }
vcoubard 1131:692ddf04fc42 1047
vcoubard 1131:692ddf04fc42 1048 protected:
vcoubard 1131:692ddf04fc42 1049 GapAdvertisingParams _advParams;
vcoubard 1131:692ddf04fc42 1050 GapAdvertisingData _advPayload;
vcoubard 1131:692ddf04fc42 1051 GapScanningParams _scanningParams;
vcoubard 1131:692ddf04fc42 1052 GapAdvertisingData _scanResponse;
vcoubard 1131:692ddf04fc42 1053
vcoubard 1131:692ddf04fc42 1054 GapState_t state;
vcoubard 1131:692ddf04fc42 1055 bool scanningActive;
vcoubard 1131:692ddf04fc42 1056
vcoubard 1131:692ddf04fc42 1057 protected:
vcoubard 1131:692ddf04fc42 1058 TimeoutEventCallbackChain_t timeoutCallbackChain;
vcoubard 1131:692ddf04fc42 1059 RadioNotificationEventCallback_t radioNotificationCallback;
vcoubard 1131:692ddf04fc42 1060 AdvertisementReportCallback_t onAdvertisementReport;
vcoubard 1131:692ddf04fc42 1061 ConnectionEventCallbackChain_t connectionCallChain;
vcoubard 1131:692ddf04fc42 1062 DisconnectionEventCallbackChain_t disconnectionCallChain;
vcoubard 1131:692ddf04fc42 1063
vcoubard 1131:692ddf04fc42 1064 private:
vcoubard 1131:692ddf04fc42 1065 /* Disallow copy and assignment. */
vcoubard 1131:692ddf04fc42 1066 Gap(const Gap &);
vcoubard 1131:692ddf04fc42 1067 Gap& operator=(const Gap &);
vcoubard 1131:692ddf04fc42 1068 };
vcoubard 1131:692ddf04fc42 1069
rgrover1 710:b2e1a2660ec2 1070 #endif // ifndef __GAP_H__