BLE_API - BLE_API

Users » chocolatepatty » Code » BLE_API

BLE_API

ble/Gap.h@1182:b70129080ddf, 2016-04-06 (annotated)

Committer:: vcoubard
Date:: Wed Apr 06 19:15:34 2016 +0100
Revision:: 1182:b70129080ddf
Parent:: 1180:e11b058d005e
Child:: 1183:1589830dbdb7

Synchronized with git rev 07ad5292

Author: Andres Amaya Garcia

Update Gap state in startAdvertising()

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	1182:b70129080ddf	744	ble_error_t rc;
vcoubard	1131:692ddf04fc42	745	setAdvertisingData(); /* Update the underlying stack. */
vcoubard	1182:b70129080ddf	746	if ((rc = startAdvertising(_advParams)) == BLE_ERROR_NONE) {
vcoubard	1182:b70129080ddf	747	state.advertising = 1;
vcoubard	1182:b70129080ddf	748	}
vcoubard	1182:b70129080ddf	749	return rc;
vcoubard	1131:692ddf04fc42	750	}
vcoubard	1131:692ddf04fc42	751
vcoubard	1131:692ddf04fc42	752	/**
vcoubard	1131:692ddf04fc42	753	* Reset any advertising payload prepared from prior calls to
vcoubard	1131:692ddf04fc42	754	* accumulateAdvertisingPayload(). This automatically propagates the re-
vcoubard	1131:692ddf04fc42	755	* initialized advertising payload to the underlying stack.
vcoubard	1131:692ddf04fc42	756	*/
vcoubard	1131:692ddf04fc42	757	void clearAdvertisingPayload(void) {
vcoubard	1131:692ddf04fc42	758	_advPayload.clear();
vcoubard	1131:692ddf04fc42	759	setAdvertisingData();
vcoubard	1131:692ddf04fc42	760	}
vcoubard	1131:692ddf04fc42	761
vcoubard	1131:692ddf04fc42	762	/**
vcoubard	1131:692ddf04fc42	763	* Accumulate an AD structure in the advertising payload. Please note that
vcoubard	1131:692ddf04fc42	764	* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard	1131:692ddf04fc42	765	* as an additional 31 bytes if the advertising payload is too
vcoubard	1131:692ddf04fc42	766	* small.
vcoubard	1131:692ddf04fc42	767	*
vcoubard	1131:692ddf04fc42	768	* @param[in] flags
vcoubard	1131:692ddf04fc42	769	* The flags to be added. Please refer to
vcoubard	1131:692ddf04fc42	770	* GapAdvertisingData::Flags for valid flags. Multiple
vcoubard	1131:692ddf04fc42	771	* flags may be specified in combination.
vcoubard	1131:692ddf04fc42	772	*/
vcoubard	1131:692ddf04fc42	773	ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
vcoubard	1131:692ddf04fc42	774	ble_error_t rc;
vcoubard	1131:692ddf04fc42	775	if ((rc = _advPayload.addFlags(flags)) != BLE_ERROR_NONE) {
vcoubard	1131:692ddf04fc42	776	return rc;
vcoubard	1131:692ddf04fc42	777	}
vcoubard	1131:692ddf04fc42	778
vcoubard	1131:692ddf04fc42	779	return setAdvertisingData();
vcoubard	1131:692ddf04fc42	780	}
vcoubard	1131:692ddf04fc42	781
vcoubard	1131:692ddf04fc42	782	/**
vcoubard	1131:692ddf04fc42	783	* Accumulate an AD structure in the advertising payload. Please note that
vcoubard	1131:692ddf04fc42	784	* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard	1131:692ddf04fc42	785	* as an additional 31 bytes if the advertising payload is too
vcoubard	1131:692ddf04fc42	786	* small.
vcoubard	1131:692ddf04fc42	787	*
vcoubard	1179:4ab722f8dca0	788	* @param app
vcoubard	1179:4ab722f8dca0	789	* The appearance of the peripheral.
vcoubard	1131:692ddf04fc42	790	*/
vcoubard	1131:692ddf04fc42	791	ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
vcoubard	1131:692ddf04fc42	792	setAppearance(app);
vcoubard	1131:692ddf04fc42	793
vcoubard	1131:692ddf04fc42	794	ble_error_t rc;
vcoubard	1131:692ddf04fc42	795	if ((rc = _advPayload.addAppearance(app)) != BLE_ERROR_NONE) {
vcoubard	1131:692ddf04fc42	796	return rc;
vcoubard	1131:692ddf04fc42	797	}
vcoubard	1131:692ddf04fc42	798
vcoubard	1131:692ddf04fc42	799	return setAdvertisingData();
vcoubard	1131:692ddf04fc42	800	}
vcoubard	1131:692ddf04fc42	801
vcoubard	1131:692ddf04fc42	802	/**
vcoubard	1131:692ddf04fc42	803	* Accumulate an AD structure in the advertising payload. Please note that
vcoubard	1131:692ddf04fc42	804	* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard	1131:692ddf04fc42	805	* as an additional 31 bytes if the advertising payload is too
vcoubard	1131:692ddf04fc42	806	* small.
vcoubard	1131:692ddf04fc42	807	*
vcoubard	1179:4ab722f8dca0	808	* @param power
vcoubard	1179:4ab722f8dca0	809	* The max transmit power to be used by the controller (in dBm).
vcoubard	1131:692ddf04fc42	810	*/
vcoubard	1131:692ddf04fc42	811	ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
vcoubard	1131:692ddf04fc42	812	ble_error_t rc;
vcoubard	1131:692ddf04fc42	813	if ((rc = _advPayload.addTxPower(power)) != BLE_ERROR_NONE) {
vcoubard	1131:692ddf04fc42	814	return rc;
vcoubard	1131:692ddf04fc42	815	}
vcoubard	1131:692ddf04fc42	816
vcoubard	1131:692ddf04fc42	817	return setAdvertisingData();
vcoubard	1131:692ddf04fc42	818	}
vcoubard	1131:692ddf04fc42	819
vcoubard	1131:692ddf04fc42	820	/**
vcoubard	1131:692ddf04fc42	821	* Accumulate a variable length byte-stream as an AD structure in the
vcoubard	1131:692ddf04fc42	822	* advertising payload. Please note that the payload is limited to 31 bytes.
vcoubard	1131:692ddf04fc42	823	* The SCAN_RESPONSE message may be used as an additional 31 bytes if the
vcoubard	1131:692ddf04fc42	824	* advertising payload is too small.
vcoubard	1131:692ddf04fc42	825	*
vcoubard	1179:4ab722f8dca0	826	* @param type The type describing the variable length data.
vcoubard	1179:4ab722f8dca0	827	* @param data Data bytes.
vcoubard	1179:4ab722f8dca0	828	* @param len Length of data.
vcoubard	1135:22aada733dbd	829	*
vcoubard	1135:22aada733dbd	830	* @return BLE_ERROR_NONE if the advertisement payload was updated based on
vcoubard	1135:22aada733dbd	831	* matching AD type; otherwise, an appropriate error.
vcoubard	1135:22aada733dbd	832	*
vcoubard	1135:22aada733dbd	833	* @note When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS,
vcoubard	1135:22aada733dbd	834	* COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS,
vcoubard	1135:22aada733dbd	835	* COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS,
vcoubard	1135:22aada733dbd	836	* COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the
vcoubard	1135:22aada733dbd	837	* supplied value is appended to the values previously added to the
vcoubard	1135:22aada733dbd	838	* payload.
vcoubard	1131:692ddf04fc42	839	*/
vcoubard	1131:692ddf04fc42	840	ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard	1131:692ddf04fc42	841	if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
vcoubard	1131:692ddf04fc42	842	setDeviceName(data);
vcoubard	1131:692ddf04fc42	843	}
vcoubard	1131:692ddf04fc42	844
vcoubard	1131:692ddf04fc42	845	ble_error_t rc;
vcoubard	1131:692ddf04fc42	846	if ((rc = _advPayload.addData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard	1131:692ddf04fc42	847	return rc;
vcoubard	1131:692ddf04fc42	848	}
vcoubard	1131:692ddf04fc42	849
vcoubard	1131:692ddf04fc42	850	return setAdvertisingData();
vcoubard	1131:692ddf04fc42	851	}
vcoubard	1131:692ddf04fc42	852
vcoubard	1131:692ddf04fc42	853	/**
vcoubard	1131:692ddf04fc42	854	* Update a particular ADV field in the advertising payload (based on
vcoubard	1135:22aada733dbd	855	* matching type).
vcoubard	1131:692ddf04fc42	856	*
vcoubard	1179:4ab722f8dca0	857	* @param[in] type The ADV type field describing the variable length data.
vcoubard	1179:4ab722f8dca0	858	* @param[in] data Data bytes.
vcoubard	1179:4ab722f8dca0	859	* @param[in] len Length of data.
vcoubard	1131:692ddf04fc42	860	*
vcoubard	1179:4ab722f8dca0	861	* @note: If advertisements are enabled, then the update will take effect immediately.
vcoubard	1131:692ddf04fc42	862	*
vcoubard	1131:692ddf04fc42	863	* @return BLE_ERROR_NONE if the advertisement payload was updated based on
vcoubard	1135:22aada733dbd	864	* matching AD type; otherwise, an appropriate error.
vcoubard	1131:692ddf04fc42	865	*/
vcoubard	1131:692ddf04fc42	866	ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard	1131:692ddf04fc42	867	if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
vcoubard	1131:692ddf04fc42	868	setDeviceName(data);
vcoubard	1131:692ddf04fc42	869	}
vcoubard	1131:692ddf04fc42	870
vcoubard	1131:692ddf04fc42	871	ble_error_t rc;
vcoubard	1131:692ddf04fc42	872	if ((rc = _advPayload.updateData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard	1131:692ddf04fc42	873	return rc;
vcoubard	1131:692ddf04fc42	874	}
vcoubard	1131:692ddf04fc42	875
vcoubard	1131:692ddf04fc42	876	return setAdvertisingData();
vcoubard	1131:692ddf04fc42	877	}
vcoubard	1131:692ddf04fc42	878
vcoubard	1131:692ddf04fc42	879	/**
vcoubard	1131:692ddf04fc42	880	* Set up a particular, user-constructed advertisement payload for the
vcoubard	1131:692ddf04fc42	881	* underlying stack. It would be uncommon for this API to be used directly;
vcoubard	1179:4ab722f8dca0	882	* there are other APIs to build an advertisement payload (see above).
vcoubard	1131:692ddf04fc42	883	*/
vcoubard	1131:692ddf04fc42	884	ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) {
vcoubard	1131:692ddf04fc42	885	_advPayload = payload;
vcoubard	1131:692ddf04fc42	886	return setAdvertisingData();
vcoubard	1131:692ddf04fc42	887	}
vcoubard	1131:692ddf04fc42	888
vcoubard	1131:692ddf04fc42	889	/**
vcoubard	1179:4ab722f8dca0	890	* @return Read back advertising data. Useful for storing and
vcoubard	1179:4ab722f8dca0	891	* restoring payload.
vcoubard	1131:692ddf04fc42	892	*/
vcoubard	1131:692ddf04fc42	893	const GapAdvertisingData &getAdvertisingPayload(void) const {
vcoubard	1131:692ddf04fc42	894	return _advPayload;
vcoubard	1131:692ddf04fc42	895	}
vcoubard	1131:692ddf04fc42	896
vcoubard	1131:692ddf04fc42	897	/**
vcoubard	1131:692ddf04fc42	898	* Accumulate a variable length byte-stream as an AD structure in the
vcoubard	1131:692ddf04fc42	899	* scanResponse payload.
vcoubard	1131:692ddf04fc42	900	*
vcoubard	1179:4ab722f8dca0	901	* @param[in] type The type describing the variable length data.
vcoubard	1179:4ab722f8dca0	902	* @param[in] data Data bytes.
vcoubard	1179:4ab722f8dca0	903	* @param[in] len Length of data.
vcoubard	1131:692ddf04fc42	904	*/
vcoubard	1131:692ddf04fc42	905	ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
vcoubard	1131:692ddf04fc42	906	ble_error_t rc;
vcoubard	1131:692ddf04fc42	907	if ((rc = _scanResponse.addData(type, data, len)) != BLE_ERROR_NONE) {
vcoubard	1131:692ddf04fc42	908	return rc;
vcoubard	1131:692ddf04fc42	909	}
vcoubard	1131:692ddf04fc42	910
vcoubard	1131:692ddf04fc42	911	return setAdvertisingData();
vcoubard	1131:692ddf04fc42	912	}
vcoubard	1131:692ddf04fc42	913
vcoubard	1131:692ddf04fc42	914	/**
vcoubard	1131:692ddf04fc42	915	* Reset any scan response prepared from prior calls to
vcoubard	1179:4ab722f8dca0	916	* accumulateScanResponse().
vcoubard	1131:692ddf04fc42	917	*
vcoubard	1179:4ab722f8dca0	918	* Note: This should be followed by a call to setAdvertisingPayload() or
vcoubard	1179:4ab722f8dca0	919	* startAdvertising() before the update takes effect.
vcoubard	1131:692ddf04fc42	920	*/
vcoubard	1131:692ddf04fc42	921	void clearScanResponse(void) {
vcoubard	1131:692ddf04fc42	922	_scanResponse.clear();
vcoubard	1131:692ddf04fc42	923	setAdvertisingData();
vcoubard	1131:692ddf04fc42	924	}
vcoubard	1131:692ddf04fc42	925
vcoubard	1131:692ddf04fc42	926	/**
vcoubard	1131:692ddf04fc42	927	* Set up parameters for GAP scanning (observer mode).
vcoubard	1131:692ddf04fc42	928	* @param[in] interval
vcoubard	1131:692ddf04fc42	929	* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard	1131:692ddf04fc42	930	* @param[in] window
vcoubard	1131:692ddf04fc42	931	* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard	1131:692ddf04fc42	932	* @param[in] timeout
vcoubard	1131:692ddf04fc42	933	* Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
vcoubard	1131:692ddf04fc42	934	* @param[in] activeScanning
vcoubard	1131:692ddf04fc42	935	* Set to True if active-scanning is required. This is used to fetch the
vcoubard	1131:692ddf04fc42	936	* scan response from a peer if possible.
vcoubard	1131:692ddf04fc42	937	*
vcoubard	1179:4ab722f8dca0	938	* The scanning window divided by the interval determines the duty cycle for
vcoubard	1179:4ab722f8dca0	939	* scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard	1179:4ab722f8dca0	940	* then the controller will scan for 10 percent of the time. It is possible
vcoubard	1179:4ab722f8dca0	941	* to have the interval and window set to the same value. In this case,
vcoubard	1179:4ab722f8dca0	942	* scanning is continuous, with a change of scanning frequency once every
vcoubard	1179:4ab722f8dca0	943	* interval.
vcoubard	1131:692ddf04fc42	944	*
vcoubard	1179:4ab722f8dca0	945	* Once the scanning parameters have been configured, scanning can be
vcoubard	1179:4ab722f8dca0	946	* enabled by using startScan().
vcoubard	1131:692ddf04fc42	947	*
vcoubard	1179:4ab722f8dca0	948	* @Note: The scan interval and window are recommendations to the BLE stack.
vcoubard	1131:692ddf04fc42	949	*/
vcoubard	1131:692ddf04fc42	950	ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
vcoubard	1131:692ddf04fc42	951	uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
vcoubard	1131:692ddf04fc42	952	uint16_t timeout = 0,
vcoubard	1131:692ddf04fc42	953	bool activeScanning = false) {
vcoubard	1131:692ddf04fc42	954	ble_error_t rc;
vcoubard	1131:692ddf04fc42	955	if (((rc = _scanningParams.setInterval(interval)) == BLE_ERROR_NONE) &&
vcoubard	1131:692ddf04fc42	956	((rc = _scanningParams.setWindow(window)) == BLE_ERROR_NONE) &&
vcoubard	1131:692ddf04fc42	957	((rc = _scanningParams.setTimeout(timeout)) == BLE_ERROR_NONE)) {
vcoubard	1131:692ddf04fc42	958	_scanningParams.setActiveScanning(activeScanning);
vcoubard	1131:692ddf04fc42	959	return BLE_ERROR_NONE;
vcoubard	1131:692ddf04fc42	960	}
vcoubard	1131:692ddf04fc42	961
vcoubard	1131:692ddf04fc42	962	return rc;
vcoubard	1131:692ddf04fc42	963	}
vcoubard	1131:692ddf04fc42	964
vcoubard	1131:692ddf04fc42	965	/**
vcoubard	1131:692ddf04fc42	966	* Set up the scanInterval parameter for GAP scanning (observer mode).
vcoubard	1131:692ddf04fc42	967	* @param[in] interval
vcoubard	1131:692ddf04fc42	968	* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard	1131:692ddf04fc42	969	*
vcoubard	1179:4ab722f8dca0	970	* The scanning window divided by the interval determines the duty cycle for
vcoubard	1179:4ab722f8dca0	971	* scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard	1179:4ab722f8dca0	972	* then the controller will scan for 10 percent of the time. It is possible
vcoubard	1179:4ab722f8dca0	973	* to have the interval and window set to the same value. In this case,
vcoubard	1179:4ab722f8dca0	974	* scanning is continuous, with a change of scanning frequency once every
vcoubard	1179:4ab722f8dca0	975	* interval.
vcoubard	1131:692ddf04fc42	976	*
vcoubard	1179:4ab722f8dca0	977	* Once the scanning parameters have been configured, scanning can be
vcoubard	1179:4ab722f8dca0	978	* enabled by using startScan().
vcoubard	1131:692ddf04fc42	979	*/
vcoubard	1131:692ddf04fc42	980	ble_error_t setScanInterval(uint16_t interval) {
vcoubard	1131:692ddf04fc42	981	return _scanningParams.setInterval(interval);
vcoubard	1131:692ddf04fc42	982	}
vcoubard	1131:692ddf04fc42	983
vcoubard	1131:692ddf04fc42	984	/**
vcoubard	1131:692ddf04fc42	985	* Set up the scanWindow parameter for GAP scanning (observer mode).
vcoubard	1131:692ddf04fc42	986	* @param[in] window
vcoubard	1131:692ddf04fc42	987	* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
vcoubard	1131:692ddf04fc42	988	*
vcoubard	1179:4ab722f8dca0	989	* The scanning window divided by the interval determines the duty cycle for
vcoubard	1179:4ab722f8dca0	990	* scanning. For example, if the interval is 100ms and the window is 10ms,
vcoubard	1179:4ab722f8dca0	991	* then the controller will scan for 10 percent of the time. It is possible
vcoubard	1179:4ab722f8dca0	992	* to have the interval and window set to the same value. In this case,
vcoubard	1179:4ab722f8dca0	993	* scanning is continuous, with a change of scanning frequency once every
vcoubard	1179:4ab722f8dca0	994	* interval.
vcoubard	1131:692ddf04fc42	995	*
vcoubard	1179:4ab722f8dca0	996	* Once the scanning parameters have been configured, scanning can be
vcoubard	1179:4ab722f8dca0	997	* enabled by using startScan().
vcoubard	1131:692ddf04fc42	998	*
vcoubard	1179:4ab722f8dca0	999	* If scanning is already active, the updated value of scanWindow will be
vcoubard	1179:4ab722f8dca0	1000	* propagated to the underlying BLE stack.
vcoubard	1131:692ddf04fc42	1001	*/
vcoubard	1131:692ddf04fc42	1002	ble_error_t setScanWindow(uint16_t window) {
vcoubard	1131:692ddf04fc42	1003	ble_error_t rc;
vcoubard	1131:692ddf04fc42	1004	if ((rc = _scanningParams.setWindow(window)) != BLE_ERROR_NONE) {
vcoubard	1131:692ddf04fc42	1005	return rc;
vcoubard	1131:692ddf04fc42	1006	}
vcoubard	1131:692ddf04fc42	1007
vcoubard	1131:692ddf04fc42	1008	/* If scanning is already active, propagate the new setting to the stack. */
vcoubard	1131:692ddf04fc42	1009	if (scanningActive) {
vcoubard	1131:692ddf04fc42	1010	return startRadioScan(_scanningParams);
vcoubard	1131:692ddf04fc42	1011	}
vcoubard	1131:692ddf04fc42	1012
vcoubard	1131:692ddf04fc42	1013	return BLE_ERROR_NONE;
vcoubard	1131:692ddf04fc42	1014	}
vcoubard	1131:692ddf04fc42	1015
vcoubard	1131:692ddf04fc42	1016	/**
vcoubard	1131:692ddf04fc42	1017	* Set up parameters for GAP scanning (observer mode).
vcoubard	1131:692ddf04fc42	1018	* @param[in] timeout
vcoubard	1131:692ddf04fc42	1019	* Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
vcoubard	1131:692ddf04fc42	1020	*
vcoubard	1179:4ab722f8dca0	1021	* Once the scanning parameters have been configured, scanning can be
vcoubard	1179:4ab722f8dca0	1022	* enabled by using startScan().
vcoubard	1131:692ddf04fc42	1023	*
vcoubard	1179:4ab722f8dca0	1024	* If scanning is already active, the updated value of scanTimeout will be
vcoubard	1179:4ab722f8dca0	1025	* propagated to the underlying BLE stack.
vcoubard	1131:692ddf04fc42	1026	*/
vcoubard	1131:692ddf04fc42	1027	ble_error_t setScanTimeout(uint16_t timeout) {
vcoubard	1131:692ddf04fc42	1028	ble_error_t rc;
vcoubard	1131:692ddf04fc42	1029	if ((rc = _scanningParams.setTimeout(timeout)) != BLE_ERROR_NONE) {
vcoubard	1131:692ddf04fc42	1030	return rc;
vcoubard	1131:692ddf04fc42	1031	}
vcoubard	1131:692ddf04fc42	1032
vcoubard	1131:692ddf04fc42	1033	/* If scanning is already active, propagate the new settings to the stack. */
vcoubard	1131:692ddf04fc42	1034	if (scanningActive) {
vcoubard	1131:692ddf04fc42	1035	return startRadioScan(_scanningParams);
vcoubard	1131:692ddf04fc42	1036	}
vcoubard	1131:692ddf04fc42	1037
vcoubard	1131:692ddf04fc42	1038	return BLE_ERROR_NONE;
vcoubard	1131:692ddf04fc42	1039	}
vcoubard	1131:692ddf04fc42	1040
vcoubard	1131:692ddf04fc42	1041	/**
vcoubard	1179:4ab722f8dca0	1042	* Set up parameters for GAP scanning (observer mode).
vcoubard	1131:692ddf04fc42	1043	* @param[in] activeScanning
vcoubard	1179:4ab722f8dca0	1044	* Set to True if active-scanning is required. This is used to fetch the
vcoubard	1179:4ab722f8dca0	1045	* scan response from a peer if possible.
vcoubard	1131:692ddf04fc42	1046	*
vcoubard	1179:4ab722f8dca0	1047	* Once the scanning parameters have been configured, scanning can be
vcoubard	1179:4ab722f8dca0	1048	* enabled by using startScan().
vcoubard	1131:692ddf04fc42	1049	*
vcoubard	1179:4ab722f8dca0	1050	* If scanning is already in progress, then active-scanning will be enabled
vcoubard	1179:4ab722f8dca0	1051	* for the underlying BLE stack.
vcoubard	1131:692ddf04fc42	1052	*/
vcoubard	1131:692ddf04fc42	1053	ble_error_t setActiveScanning(bool activeScanning) {
vcoubard	1131:692ddf04fc42	1054	_scanningParams.setActiveScanning(activeScanning);
vcoubard	1131:692ddf04fc42	1055
vcoubard	1131:692ddf04fc42	1056	/* If scanning is already active, propagate the new settings to the stack. */
vcoubard	1131:692ddf04fc42	1057	if (scanningActive) {
vcoubard	1131:692ddf04fc42	1058	return startRadioScan(_scanningParams);
vcoubard	1131:692ddf04fc42	1059	}
vcoubard	1131:692ddf04fc42	1060
vcoubard	1131:692ddf04fc42	1061	return BLE_ERROR_NONE;
vcoubard	1131:692ddf04fc42	1062	}
vcoubard	1131:692ddf04fc42	1063
vcoubard	1131:692ddf04fc42	1064	/**
vcoubard	1131:692ddf04fc42	1065	* Start scanning (Observer Procedure) based on the parameters currently in
vcoubard	1131:692ddf04fc42	1066	* effect.
vcoubard	1131:692ddf04fc42	1067	*
vcoubard	1131:692ddf04fc42	1068	* @param[in] callback
vcoubard	1131:692ddf04fc42	1069	* The application-specific callback to be invoked upon
vcoubard	1131:692ddf04fc42	1070	* receiving every advertisement report. This can be passed in
vcoubard	1131:692ddf04fc42	1071	* as NULL, in which case scanning may not be enabled at all.
vcoubard	1131:692ddf04fc42	1072	*/
vcoubard	1131:692ddf04fc42	1073	ble_error_t startScan(void (callback)(const AdvertisementCallbackParams_t params)) {
vcoubard	1131:692ddf04fc42	1074	ble_error_t err = BLE_ERROR_NONE;
vcoubard	1131:692ddf04fc42	1075	if (callback) {
vcoubard	1131:692ddf04fc42	1076	if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
vcoubard	1131:692ddf04fc42	1077	scanningActive = true;
vcoubard	1131:692ddf04fc42	1078	onAdvertisementReport.attach(callback);
vcoubard	1131:692ddf04fc42	1079	}
vcoubard	1131:692ddf04fc42	1080	}
vcoubard	1131:692ddf04fc42	1081
vcoubard	1131:692ddf04fc42	1082	return err;
vcoubard	1131:692ddf04fc42	1083	}
vcoubard	1131:692ddf04fc42	1084
vcoubard	1131:692ddf04fc42	1085	/**
vcoubard	1179:4ab722f8dca0	1086	* Same as above, but this takes an (object, method) pair for a callback.
vcoubard	1131:692ddf04fc42	1087	*/
vcoubard	1131:692ddf04fc42	1088	template<typename T>
vcoubard	1131:692ddf04fc42	1089	ble_error_t startScan(T object, void (T::callbackMember)(const AdvertisementCallbackParams_t *params)) {
vcoubard	1131:692ddf04fc42	1090	ble_error_t err = BLE_ERROR_NONE;
vcoubard	1131:692ddf04fc42	1091	if (object && callbackMember) {
vcoubard	1131:692ddf04fc42	1092	if ((err = startRadioScan(_scanningParams)) == BLE_ERROR_NONE) {
vcoubard	1131:692ddf04fc42	1093	scanningActive = true;
vcoubard	1131:692ddf04fc42	1094	onAdvertisementReport.attach(object, callbackMember);
vcoubard	1131:692ddf04fc42	1095	}
vcoubard	1131:692ddf04fc42	1096	}
vcoubard	1131:692ddf04fc42	1097
vcoubard	1131:692ddf04fc42	1098	return err;
vcoubard	1131:692ddf04fc42	1099	}
vcoubard	1131:692ddf04fc42	1100
vcoubard	1131:692ddf04fc42	1101	/**
vcoubard	1131:692ddf04fc42	1102	* Initialize radio-notification events to be generated from the stack.
vcoubard	1131:692ddf04fc42	1103	* This API doesn't need to be called directly.
vcoubard	1131:692ddf04fc42	1104	*
vcoubard	1131:692ddf04fc42	1105	* Radio Notification is a feature that enables ACTIVE and INACTIVE
vcoubard	1131:692ddf04fc42	1106	* (nACTIVE) signals from the stack that notify the application when the
vcoubard	1131:692ddf04fc42	1107	* radio is in use.
vcoubard	1131:692ddf04fc42	1108	*
vcoubard	1131:692ddf04fc42	1109	* The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard	1131:692ddf04fc42	1110	* signal is sent at the end of the radio event. These signals can be used
vcoubard	1131:692ddf04fc42	1111	* by the application programmer to synchronize application logic with radio
vcoubard	1131:692ddf04fc42	1112	* activity. For example, the ACTIVE signal can be used to shut off external
vcoubard	1131:692ddf04fc42	1113	* devices, to manage peak current drawn during periods when the radio is on,
vcoubard	1131:692ddf04fc42	1114	* or to trigger sensor data collection for transmission in the Radio Event.
vcoubard	1131:692ddf04fc42	1115	*
vcoubard	1131:692ddf04fc42	1116	* @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
vcoubard	1131:692ddf04fc42	1117	*/
vcoubard	1131:692ddf04fc42	1118	virtual ble_error_t initRadioNotification(void) {
vcoubard	1131:692ddf04fc42	1119	return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
vcoubard	1131:692ddf04fc42	1120	}
vcoubard	1131:692ddf04fc42	1121
vcoubard	1131:692ddf04fc42	1122	private:
vcoubard	1131:692ddf04fc42	1123	ble_error_t setAdvertisingData(void) {
vcoubard	1131:692ddf04fc42	1124	return setAdvertisingData(_advPayload, _scanResponse);
vcoubard	1131:692ddf04fc42	1125	}
vcoubard	1131:692ddf04fc42	1126
vcoubard	1131:692ddf04fc42	1127	private:
vcoubard	1131:692ddf04fc42	1128	virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0;
vcoubard	1131:692ddf04fc42	1129	virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
vcoubard	1131:692ddf04fc42	1130
vcoubard	1131:692ddf04fc42	1131	public:
vcoubard	1131:692ddf04fc42	1132	/**
vcoubard	1179:4ab722f8dca0	1133	* Accessors to read back currently active advertising params.
vcoubard	1131:692ddf04fc42	1134	*/
vcoubard	1131:692ddf04fc42	1135	GapAdvertisingParams &getAdvertisingParams(void) {
vcoubard	1131:692ddf04fc42	1136	return _advParams;
vcoubard	1131:692ddf04fc42	1137	}
vcoubard	1131:692ddf04fc42	1138	const GapAdvertisingParams &getAdvertisingParams(void) const {
vcoubard	1131:692ddf04fc42	1139	return _advParams;
vcoubard	1131:692ddf04fc42	1140	}
vcoubard	1131:692ddf04fc42	1141
vcoubard	1131:692ddf04fc42	1142	/**
vcoubard	1131:692ddf04fc42	1143	* Set up a particular, user-constructed set of advertisement parameters for
vcoubard	1131:692ddf04fc42	1144	* the underlying stack. It would be uncommon for this API to be used
vcoubard	1131:692ddf04fc42	1145	* directly; there are other APIs to tweak advertisement parameters
vcoubard	1131:692ddf04fc42	1146	* individually.
vcoubard	1131:692ddf04fc42	1147	*/
vcoubard	1131:692ddf04fc42	1148	void setAdvertisingParams(const GapAdvertisingParams &newParams) {
vcoubard	1131:692ddf04fc42	1149	_advParams = newParams;
vcoubard	1131:692ddf04fc42	1150	}
vcoubard	1131:692ddf04fc42	1151
vcoubard	1131:692ddf04fc42	1152	/* Event callback handlers. */
vcoubard	1131:692ddf04fc42	1153	public:
vcoubard	1131:692ddf04fc42	1154	/**
vcoubard	1131:692ddf04fc42	1155	* Set up a callback for timeout events. Refer to TimeoutSource_t for
vcoubard	1131:692ddf04fc42	1156	* possible event types.
vcoubard	1179:4ab722f8dca0	1157	* @note It is possible to unregister callbacks using onTimeout().detach(callback)
vcoubard	1131:692ddf04fc42	1158	*/
vcoubard	1131:692ddf04fc42	1159	void onTimeout(TimeoutEventCallback_t callback) {
vcoubard	1131:692ddf04fc42	1160	timeoutCallbackChain.add(callback);
vcoubard	1131:692ddf04fc42	1161	}
vcoubard	1131:692ddf04fc42	1162
vcoubard	1131:692ddf04fc42	1163	/**
vcoubard	1179:4ab722f8dca0	1164	* @brief provide access to the callchain of timeout event callbacks
vcoubard	1179:4ab722f8dca0	1165	* It is possible to register callbacks using onTimeout().add(callback);
vcoubard	1179:4ab722f8dca0	1166	* It is possible to unregister callbacks using onTimeout().detach(callback)
vcoubard	1179:4ab722f8dca0	1167	* @return The timeout event callbacks chain
vcoubard	1131:692ddf04fc42	1168	*/
vcoubard	1131:692ddf04fc42	1169	TimeoutEventCallbackChain_t& onTimeout() {
vcoubard	1131:692ddf04fc42	1170	return timeoutCallbackChain;
vcoubard	1131:692ddf04fc42	1171	}
vcoubard	1131:692ddf04fc42	1172
vcoubard	1131:692ddf04fc42	1173	/**
vcoubard	1131:692ddf04fc42	1174	* Append to a chain of callbacks to be invoked upon GAP connection.
vcoubard	1131:692ddf04fc42	1175	* @note It is possible to unregister callbacks using onConnection().detach(callback)
vcoubard	1131:692ddf04fc42	1176	*/
vcoubard	1179:4ab722f8dca0	1177	void onConnection(ConnectionEventCallback_t callback) {connectionCallChain.add(callback);}
vcoubard	1179:4ab722f8dca0	1178
vcoubard	1179:4ab722f8dca0	1179	template<typename T>
vcoubard	1179:4ab722f8dca0	1180	void onConnection(T tptr, void (T::mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
vcoubard	1131:692ddf04fc42	1181
vcoubard	1131:692ddf04fc42	1182	/**
vcoubard	1179:4ab722f8dca0	1183	* @brief provide access to the callchain of connection event callbacks
vcoubard	1179:4ab722f8dca0	1184	* It is possible to register callbacks using onConnection().add(callback);
vcoubard	1179:4ab722f8dca0	1185	* It is possible to unregister callbacks using onConnection().detach(callback)
vcoubard	1179:4ab722f8dca0	1186	* @return The connection event callbacks chain
vcoubard	1131:692ddf04fc42	1187	*/
vcoubard	1132:6362b7c2fdff	1188	ConnectionEventCallbackChain_t& onConnection() {
vcoubard	1131:692ddf04fc42	1189	return connectionCallChain;
vcoubard	1131:692ddf04fc42	1190	}
vcoubard	1131:692ddf04fc42	1191
vcoubard	1131:692ddf04fc42	1192	/**
vcoubard	1131:692ddf04fc42	1193	* Append to a chain of callbacks to be invoked upon GAP disconnection.
vcoubard	1179:4ab722f8dca0	1194	* @note It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard	1131:692ddf04fc42	1195	*/
vcoubard	1179:4ab722f8dca0	1196	void onDisconnection(DisconnectionEventCallback_t callback) {disconnectionCallChain.add(callback);}
vcoubard	1179:4ab722f8dca0	1197
vcoubard	1179:4ab722f8dca0	1198	template<typename T>
vcoubard	1179:4ab722f8dca0	1199	void onDisconnection(T tptr, void (T::mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
vcoubard	1131:692ddf04fc42	1200
vcoubard	1131:692ddf04fc42	1201	/**
vcoubard	1179:4ab722f8dca0	1202	* @brief provide access to the callchain of disconnection event callbacks
vcoubard	1179:4ab722f8dca0	1203	* It is possible to register callbacks using onDisconnection().add(callback);
vcoubard	1179:4ab722f8dca0	1204	* It is possible to unregister callbacks using onDisconnection().detach(callback)
vcoubard	1179:4ab722f8dca0	1205	* @return The disconnection event callbacks chain
vcoubard	1131:692ddf04fc42	1206	*/
vcoubard	1131:692ddf04fc42	1207	DisconnectionEventCallbackChain_t& onDisconnection() {
vcoubard	1131:692ddf04fc42	1208	return disconnectionCallChain;
vcoubard	1131:692ddf04fc42	1209	}
vcoubard	1131:692ddf04fc42	1210
vcoubard	1131:692ddf04fc42	1211	/**
vcoubard	1131:692ddf04fc42	1212	* Set the application callback for radio-notification events.
vcoubard	1131:692ddf04fc42	1213	*
vcoubard	1131:692ddf04fc42	1214	* Radio Notification is a feature that enables ACTIVE and INACTIVE
vcoubard	1131:692ddf04fc42	1215	* (nACTIVE) signals from the stack that notify the application when the
vcoubard	1131:692ddf04fc42	1216	* radio is in use.
vcoubard	1131:692ddf04fc42	1217	*
vcoubard	1131:692ddf04fc42	1218	* The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard	1131:692ddf04fc42	1219	* signal is sent at the end of the radio event. These signals can be used
vcoubard	1131:692ddf04fc42	1220	* by the application programmer to synchronize application logic with radio
vcoubard	1131:692ddf04fc42	1221	* activity. For example, the ACTIVE signal can be used to shut off external
vcoubard	1131:692ddf04fc42	1222	* devices, to manage peak current drawn during periods when the radio is on,
vcoubard	1131:692ddf04fc42	1223	* or to trigger sensor data collection for transmission in the Radio Event.
vcoubard	1131:692ddf04fc42	1224	*
vcoubard	1179:4ab722f8dca0	1225	* @param callback
vcoubard	1179:4ab722f8dca0	1226	* The application handler to be invoked in response to a radio
vcoubard	1179:4ab722f8dca0	1227	* ACTIVE/INACTIVE event.
vcoubard	1179:4ab722f8dca0	1228	*
vcoubard	1179:4ab722f8dca0	1229	* Or in the other version:
vcoubard	1179:4ab722f8dca0	1230	*
vcoubard	1179:4ab722f8dca0	1231	* @param tptr
vcoubard	1179:4ab722f8dca0	1232	* Pointer to the object of a class defining the member callback
vcoubard	1179:4ab722f8dca0	1233	* function (mptr).
vcoubard	1179:4ab722f8dca0	1234	* @param mptr
vcoubard	1179:4ab722f8dca0	1235	* The member callback (within the context of an object) to be
vcoubard	1179:4ab722f8dca0	1236	* invoked in response to a radio ACTIVE/INACTIVE event.
vcoubard	1131:692ddf04fc42	1237	*/
vcoubard	1131:692ddf04fc42	1238	void onRadioNotification(void (*callback)(bool param)) {
vcoubard	1131:692ddf04fc42	1239	radioNotificationCallback.attach(callback);
vcoubard	1131:692ddf04fc42	1240	}
vcoubard	1131:692ddf04fc42	1241	template <typename T>
vcoubard	1131:692ddf04fc42	1242	void onRadioNotification(T tptr, void (T::mptr)(bool)) {
vcoubard	1131:692ddf04fc42	1243	radioNotificationCallback.attach(tptr, mptr);
vcoubard	1131:692ddf04fc42	1244	}
vcoubard	1131:692ddf04fc42	1245
vcoubard	1135:22aada733dbd	1246	/**
vcoubard	1135:22aada733dbd	1247	* Setup a callback to be invoked to notify the user application that the
vcoubard	1135:22aada733dbd	1248	* Gap instance is about to shutdown (possibly as a result of a call
vcoubard	1135:22aada733dbd	1249	* to BLE::shutdown()).
vcoubard	1135:22aada733dbd	1250	*
vcoubard	1179:4ab722f8dca0	1251	* @Note: It is possible to chain together multiple onShutdown callbacks
vcoubard	1135:22aada733dbd	1252	* (potentially from different modules of an application) to be notified
vcoubard	1135:22aada733dbd	1253	* before the Gap instance is shutdown.
vcoubard	1135:22aada733dbd	1254	*
vcoubard	1179:4ab722f8dca0	1255	* @Note: It is also possible to set up a callback into a member function of
vcoubard	1135:22aada733dbd	1256	* some object.
vcoubard	1135:22aada733dbd	1257	*
vcoubard	1179:4ab722f8dca0	1258	* @Note It is possible to unregister a callback using onShutdown().detach(callback)
vcoubard	1135:22aada733dbd	1259	*/
vcoubard	1135:22aada733dbd	1260	void onShutdown(const GapShutdownCallback_t& callback) {
vcoubard	1135:22aada733dbd	1261	shutdownCallChain.add(callback);
vcoubard	1135:22aada733dbd	1262	}
vcoubard	1135:22aada733dbd	1263	template <typename T>
vcoubard	1135:22aada733dbd	1264	void onShutdown(T objPtr, void (T::memberPtr)(void)) {
vcoubard	1135:22aada733dbd	1265	shutdownCallChain.add(objPtr, memberPtr);
vcoubard	1135:22aada733dbd	1266	}
vcoubard	1135:22aada733dbd	1267
vcoubard	1135:22aada733dbd	1268	/**
vcoubard	1179:4ab722f8dca0	1269	* @brief provide access to the callchain of shutdown event callbacks
vcoubard	1179:4ab722f8dca0	1270	* It is possible to register callbacks using onShutdown().add(callback);
vcoubard	1179:4ab722f8dca0	1271	* It is possible to unregister callbacks using onShutdown().detach(callback)
vcoubard	1179:4ab722f8dca0	1272	* @return The shutdown event callbacks chain
vcoubard	1135:22aada733dbd	1273	*/
vcoubard	1135:22aada733dbd	1274	GapShutdownCallbackChain_t& onShutdown() {
vcoubard	1135:22aada733dbd	1275	return shutdownCallChain;
vcoubard	1135:22aada733dbd	1276	}
vcoubard	1135:22aada733dbd	1277
vcoubard	1135:22aada733dbd	1278	public:
vcoubard	1135:22aada733dbd	1279	/**
vcoubard	1135:22aada733dbd	1280	* Notify all registered onShutdown callbacks that the Gap instance is
vcoubard	1135:22aada733dbd	1281	* about to be shutdown and clear all Gap state of the
vcoubard	1135:22aada733dbd	1282	* associated object.
vcoubard	1135:22aada733dbd	1283	*
vcoubard	1135:22aada733dbd	1284	* This function is meant to be overridden in the platform-specific
vcoubard	1135:22aada733dbd	1285	* sub-class. Nevertheless, the sub-class is only expected to reset its
vcoubard	1135:22aada733dbd	1286	* state and not the data held in Gap members. This shall be achieved by a
vcoubard	1135:22aada733dbd	1287	* call to Gap::reset() from the sub-class' reset() implementation.
vcoubard	1135:22aada733dbd	1288	*
vcoubard	1135:22aada733dbd	1289	* @return BLE_ERROR_NONE on success.
vcoubard	1135:22aada733dbd	1290	*
vcoubard	1179:4ab722f8dca0	1291	* @note: Currently a call to reset() does not reset the advertising and
vcoubard	1135:22aada733dbd	1292	* scan parameters to default values.
vcoubard	1135:22aada733dbd	1293	*/
vcoubard	1135:22aada733dbd	1294	virtual ble_error_t reset(void) {
vcoubard	1135:22aada733dbd	1295	/* Notify that the instance is about to shutdown */
vcoubard	1135:22aada733dbd	1296	shutdownCallChain.call(this);
vcoubard	1135:22aada733dbd	1297	shutdownCallChain.clear();
vcoubard	1135:22aada733dbd	1298
vcoubard	1135:22aada733dbd	1299	/* Clear Gap state */
vcoubard	1135:22aada733dbd	1300	state.advertising = 0;
vcoubard	1135:22aada733dbd	1301	state.connected = 0;
vcoubard	1180:e11b058d005e	1302	connectionCount = 0;
vcoubard	1135:22aada733dbd	1303
vcoubard	1135:22aada733dbd	1304	/* Clear scanning state */
vcoubard	1135:22aada733dbd	1305	scanningActive = false;
vcoubard	1135:22aada733dbd	1306
vcoubard	1135:22aada733dbd	1307	/* Clear advertising and scanning data */
vcoubard	1135:22aada733dbd	1308	_advPayload.clear();
vcoubard	1135:22aada733dbd	1309	_scanResponse.clear();
vcoubard	1135:22aada733dbd	1310
vcoubard	1135:22aada733dbd	1311	/* Clear callbacks */
vcoubard	1135:22aada733dbd	1312	timeoutCallbackChain.clear();
vcoubard	1135:22aada733dbd	1313	connectionCallChain.clear();
vcoubard	1135:22aada733dbd	1314	disconnectionCallChain.clear();
vcoubard	1135:22aada733dbd	1315	radioNotificationCallback = NULL;
vcoubard	1135:22aada733dbd	1316	onAdvertisementReport = NULL;
vcoubard	1135:22aada733dbd	1317
vcoubard	1135:22aada733dbd	1318	return BLE_ERROR_NONE;
vcoubard	1135:22aada733dbd	1319	}
vcoubard	1135:22aada733dbd	1320
vcoubard	1131:692ddf04fc42	1321	protected:
vcoubard	1131:692ddf04fc42	1322	Gap() :
vcoubard	1131:692ddf04fc42	1323	_advParams(),
vcoubard	1131:692ddf04fc42	1324	_advPayload(),
vcoubard	1131:692ddf04fc42	1325	_scanningParams(),
vcoubard	1131:692ddf04fc42	1326	_scanResponse(),
vcoubard	1180:e11b058d005e	1327	connectionCount(0),
vcoubard	1131:692ddf04fc42	1328	state(),
vcoubard	1131:692ddf04fc42	1329	scanningActive(false),
vcoubard	1131:692ddf04fc42	1330	timeoutCallbackChain(),
vcoubard	1131:692ddf04fc42	1331	radioNotificationCallback(),
vcoubard	1131:692ddf04fc42	1332	onAdvertisementReport(),
vcoubard	1131:692ddf04fc42	1333	connectionCallChain(),
vcoubard	1131:692ddf04fc42	1334	disconnectionCallChain() {
vcoubard	1131:692ddf04fc42	1335	_advPayload.clear();
vcoubard	1131:692ddf04fc42	1336	_scanResponse.clear();
vcoubard	1131:692ddf04fc42	1337	}
vcoubard	1131:692ddf04fc42	1338
vcoubard	1131:692ddf04fc42	1339	/* Entry points for the underlying stack to report events back to the user. */
vcoubard	1131:692ddf04fc42	1340	public:
vcoubard	1135:22aada733dbd	1341	void processConnectionEvent(Handle_t handle,
vcoubard	1135:22aada733dbd	1342	Role_t role,
vcoubard	1135:22aada733dbd	1343	BLEProtocol::AddressType_t peerAddrType,
vcoubard	1135:22aada733dbd	1344	const BLEProtocol::AddressBytes_t peerAddr,
vcoubard	1135:22aada733dbd	1345	BLEProtocol::AddressType_t ownAddrType,
vcoubard	1135:22aada733dbd	1346	const BLEProtocol::AddressBytes_t ownAddr,
vcoubard	1135:22aada733dbd	1347	const ConnectionParams_t *connectionParams) {
vcoubard	1180:e11b058d005e	1348	/* Update Gap state */
vcoubard	1180:e11b058d005e	1349	state.advertising = 0;
vcoubard	1180:e11b058d005e	1350	state.connected = 1;
vcoubard	1180:e11b058d005e	1351	++connectionCount;
vcoubard	1180:e11b058d005e	1352
vcoubard	1131:692ddf04fc42	1353	ConnectionCallbackParams_t callbackParams(handle, role, peerAddrType, peerAddr, ownAddrType, ownAddr, connectionParams);
vcoubard	1131:692ddf04fc42	1354	connectionCallChain.call(&callbackParams);
vcoubard	1131:692ddf04fc42	1355	}
vcoubard	1131:692ddf04fc42	1356
vcoubard	1131:692ddf04fc42	1357	void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
vcoubard	1180:e11b058d005e	1358	/* Update Gap state */
vcoubard	1180:e11b058d005e	1359	--connectionCount;
vcoubard	1180:e11b058d005e	1360	if (!connectionCount) {
vcoubard	1180:e11b058d005e	1361	state.connected = 0;
vcoubard	1180:e11b058d005e	1362	}
vcoubard	1180:e11b058d005e	1363
vcoubard	1131:692ddf04fc42	1364	DisconnectionCallbackParams_t callbackParams(handle, reason);
vcoubard	1131:692ddf04fc42	1365	disconnectionCallChain.call(&callbackParams);
vcoubard	1131:692ddf04fc42	1366	}
vcoubard	1131:692ddf04fc42	1367
vcoubard	1135:22aada733dbd	1368	void processAdvertisementReport(const BLEProtocol::AddressBytes_t peerAddr,
vcoubard	1135:22aada733dbd	1369	int8_t rssi,
vcoubard	1135:22aada733dbd	1370	bool isScanResponse,
vcoubard	1131:692ddf04fc42	1371	GapAdvertisingParams::AdvertisingType_t type,
vcoubard	1135:22aada733dbd	1372	uint8_t advertisingDataLen,
vcoubard	1135:22aada733dbd	1373	const uint8_t *advertisingData) {
vcoubard	1131:692ddf04fc42	1374	AdvertisementCallbackParams_t params;
vcoubard	1131:692ddf04fc42	1375	memcpy(params.peerAddr, peerAddr, ADDR_LEN);
vcoubard	1131:692ddf04fc42	1376	params.rssi = rssi;
vcoubard	1131:692ddf04fc42	1377	params.isScanResponse = isScanResponse;
vcoubard	1131:692ddf04fc42	1378	params.type = type;
vcoubard	1131:692ddf04fc42	1379	params.advertisingDataLen = advertisingDataLen;
vcoubard	1131:692ddf04fc42	1380	params.advertisingData = advertisingData;
vcoubard	1131:692ddf04fc42	1381	onAdvertisementReport.call(&params);
vcoubard	1131:692ddf04fc42	1382	}
vcoubard	1131:692ddf04fc42	1383
vcoubard	1131:692ddf04fc42	1384	void processTimeoutEvent(TimeoutSource_t source) {
vcoubard	1179:4ab722f8dca0	1385	if (source == TIMEOUT_SRC_ADVERTISING) {
vcoubard	1179:4ab722f8dca0	1386	/* Update gap state if the source is an advertising timeout */
vcoubard	1179:4ab722f8dca0	1387	state.advertising = 0;
vcoubard	1179:4ab722f8dca0	1388	}
vcoubard	1131:692ddf04fc42	1389	if (timeoutCallbackChain) {
vcoubard	1131:692ddf04fc42	1390	timeoutCallbackChain(source);
vcoubard	1131:692ddf04fc42	1391	}
vcoubard	1131:692ddf04fc42	1392	}
vcoubard	1131:692ddf04fc42	1393
vcoubard	1131:692ddf04fc42	1394	protected:
vcoubard	1131:692ddf04fc42	1395	GapAdvertisingParams _advParams;
vcoubard	1131:692ddf04fc42	1396	GapAdvertisingData _advPayload;
vcoubard	1131:692ddf04fc42	1397	GapScanningParams _scanningParams;
vcoubard	1131:692ddf04fc42	1398	GapAdvertisingData _scanResponse;
vcoubard	1131:692ddf04fc42	1399
vcoubard	1180:e11b058d005e	1400	/**
vcoubard	1180:e11b058d005e	1401	* Total number of open connections.
vcoubard	1180:e11b058d005e	1402	*/
vcoubard	1180:e11b058d005e	1403	uint8_t connectionCount;
vcoubard	1131:692ddf04fc42	1404	GapState_t state;
vcoubard	1131:692ddf04fc42	1405	bool scanningActive;
vcoubard	1131:692ddf04fc42	1406
vcoubard	1131:692ddf04fc42	1407	protected:
vcoubard	1131:692ddf04fc42	1408	TimeoutEventCallbackChain_t timeoutCallbackChain;
vcoubard	1131:692ddf04fc42	1409	RadioNotificationEventCallback_t radioNotificationCallback;
vcoubard	1131:692ddf04fc42	1410	AdvertisementReportCallback_t onAdvertisementReport;
vcoubard	1131:692ddf04fc42	1411	ConnectionEventCallbackChain_t connectionCallChain;
vcoubard	1131:692ddf04fc42	1412	DisconnectionEventCallbackChain_t disconnectionCallChain;
vcoubard	1131:692ddf04fc42	1413
vcoubard	1131:692ddf04fc42	1414	private:
vcoubard	1135:22aada733dbd	1415	GapShutdownCallbackChain_t shutdownCallChain;
vcoubard	1135:22aada733dbd	1416
vcoubard	1135:22aada733dbd	1417	private:
vcoubard	1131:692ddf04fc42	1418	/* Disallow copy and assignment. */
vcoubard	1131:692ddf04fc42	1419	Gap(const Gap &);
vcoubard	1131:692ddf04fc42	1420	Gap& operator=(const Gap &);
vcoubard	1131:692ddf04fc42	1421	};
vcoubard	1131:692ddf04fc42	1422
rgrover1	710:b2e1a2660ec2	1423	#endif // ifndef __GAP_H__

Repository toolbox

Export to desktop IDE

Repository details

Type:	Library
Created:	11 Jul 2019
Imports:	12
Forks:	0
Commits:	1209
Dependents:	0
Dependencies:	0
Followers:	1

ble/Gap.h@1182:b70129080ddf, 2016-04-06 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning