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@1140:dd2f69fad8c6, 2016-04-06 (annotated)

Committer:: LancasterUniversity
Date:: Wed Apr 06 18:40:40 2016 +0100
Revision:: 1140:dd2f69fad8c6
Parent:: 1139:9af191d14c05

Synchronized with git rev bbc2dc58

Author: Joe Finney

microbit: Additional callback to indicate to applications when System

Attributes require initialisation from persistent storage.

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@1140:dd2f69fad8c6, 2016-04-06 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning