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:49 2016 +0100
Revision:
1132:6362b7c2fdff
Parent:
1131:692ddf04fc42
Child:
1134:d540a48f650d
Synchronized with git rev 35adda98
Author: Rohit Grover
Release 2.1.6
=============

Minor update around GattCharacteristics having variable length.

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 1132:6362b7c2fdff 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 1132:6362b7c2fdff 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 1132:6362b7c2fdff 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 1132:6362b7c2fdff 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 1132:6362b7c2fdff 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__