BLE_API - High level Bluetooth Low Energy API and radio abs…

Users » luzai » Code » BLE_API

Wang Xinglu / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Dependencies: nRF51822

Dependents: LinkNode_LIS3DH

Fork of BLE_API by Bluetooth Low Energy

ble/Gap.h@1180:e11b058d005e, 2016-04-06 (annotated)

Committer:: vcoubard
Date:: Wed Apr 06 19:15:32 2016 +0100
Revision:: 1180:e11b058d005e
Parent:: 1179:4ab722f8dca0
Child:: 1182:b70129080ddf

Synchronized with git rev a990f23a

Author: Andres Amaya Garcia

Add connectionCount and fix Gap state updates



Add a connectionCount member to Gap that keeps track of the total number of

open connections. Also, update the Gap state member when a connection is opened

to set advertising to false. Finally modify the processDisconnection member to

unset the connected state if connectionCount is 0.

Who changed what in which revision?

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

Repository toolbox

Export to desktop IDE

Repository details

Type:	Library
Created:	11 May 2016
Imports:	8
Forks:	0
Commits:	1202
Dependents:	1
Dependencies:	1
Followers:	1

ble/Gap.h@1180:e11b058d005e, 2016-04-06 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning