BLE_API - jgh

Users » stoicancristi » Code » BLE_API

jgh

Fork of BLE_API by Bluetooth Low Energy

ble/Gap.h@1123:685c954464e1, 2016-01-11 (annotated)

Committer:: vcoubard
Date:: Mon Jan 11 08:52:04 2016 +0000
Revision:: 1123:685c954464e1
Parent:: 1122:57dcf7dc2fe8
Child:: 1124:7ffed715734a

Synchronized with git rev 706a97bc

Author: Andres Amaya Garcia

Add @experimental doxygen tag to new APIs

Who changed what in which revision?

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

Repository toolbox

Export to desktop IDE

Repository details

Type:	Library
Created:	05 Feb 2017
Imports:	1
Forks:	0
Commits:	1210
Dependents:	1
Dependencies:	0
Followers:	1

ble/Gap.h@1123:685c954464e1, 2016-01-11 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning