BLE_API - Lancaster University's fork of the mbed BLE API. …

Lancaster University » Code » BLE_API

Lancaster University's fork of the mbed BLE API. Lives on github, https://github.com/lancaster-university/BLE_API

Dependents: microbit-dal microbit-dal microbit-ble-open microbit-dal ... more

Fork of BLE_API by Bluetooth Low Energy

ble/Gap.h@1139:9af191d14c05, 2016-04-06 (annotated)

Committer:: LancasterUniversity
Date:: Wed Apr 06 18:40:39 2016 +0100
Revision:: 1139:9af191d14c05
Parent:: 1137:290d499dd0e8

Synchronized with git rev 1b78b7bb

Author: Joe Finney

microbit: Added 'bonds' field to Gap::Whitelist_t structure



It is common for application to need to know the number of bonds stored at any

time, for the purposes of bond management. This simple addition allows

applicaitons to discover the number of bonds present using the existing API.

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

Repository toolbox

Export to desktop IDE

Repository details

Type:	Library
Created:	06 Apr 2016
Imports:	35
Forks:	0
Commits:	1141
Dependents:	23
Dependencies:	0
Followers:	14

ble/Gap.h@1139:9af191d14c05, 2016-04-06 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning