BLE_API - BLE

Users » tlon_citizen » Code » BLE_API

BLE

Fork of BLE_API by Bluetooth Low Energy

ble/BLE.h@1116:82d4a8a56d91, 2016-01-11 (annotated)

Committer:: vcoubard
Date:: Mon Jan 11 08:52:01 2016 +0000
Revision:: 1116:82d4a8a56d91
Parent:: 1079:79c089630b38
Child:: 1120:7a487d506451

Synchronized with git rev f7570e8b

Author: Andres Amaya Garcia

Early whitelisting API

Who changed what in which revision?

User	Revision	Line number	New contents of line
rgrover1	717:11b41f651697	1	/* mbed Microcontroller Library
rgrover1	717:11b41f651697	2	* Copyright (c) 2006-2013 ARM Limited
rgrover1	717:11b41f651697	3	*
rgrover1	717:11b41f651697	4	* Licensed under the Apache License, Version 2.0 (the "License");
rgrover1	717:11b41f651697	5	* you may not use this file except in compliance with the License.
rgrover1	717:11b41f651697	6	* You may obtain a copy of the License at
rgrover1	717:11b41f651697	7	*
rgrover1	717:11b41f651697	8	* http://www.apache.org/licenses/LICENSE-2.0
rgrover1	717:11b41f651697	9	*
rgrover1	717:11b41f651697	10	* Unless required by applicable law or agreed to in writing, software
rgrover1	717:11b41f651697	11	* distributed under the License is distributed on an "AS IS" BASIS,
rgrover1	717:11b41f651697	12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1	717:11b41f651697	13	* See the License for the specific language governing permissions and
rgrover1	717:11b41f651697	14	* limitations under the License.
rgrover1	717:11b41f651697	15	*/
rgrover1	717:11b41f651697	16
rgrover1	717:11b41f651697	17	#ifndef __BLE_H__
rgrover1	717:11b41f651697	18	#define __BLE_H__
rgrover1	717:11b41f651697	19
rgrover1	717:11b41f651697	20	#include "blecommon.h"
rgrover1	717:11b41f651697	21	#include "Gap.h"
rgrover1	717:11b41f651697	22	#include "GattServer.h"
rgrover1	717:11b41f651697	23	#include "GattClient.h"
rgrover1	717:11b41f651697	24
rgrover1	887:0a45c67b2301	25	#include "ble/FunctionPointerWithContext.h"
rgrover1	887:0a45c67b2301	26
rgrover1	862:2afa79e3ed0a	27	#ifdef YOTTA_CFG_MBED_OS
rgrover1	862:2afa79e3ed0a	28	#include "mbed-drivers/mbed_error.h"
rgrover1	862:2afa79e3ed0a	29	#else
rgrover1	819:61c62a287194	30	#include "mbed_error.h"
rgrover1	862:2afa79e3ed0a	31	#endif
rgrover1	862:2afa79e3ed0a	32
vcoubard	1049:efb29faf12fc	33	/* Forward declaration for the implementation class */
rgrover1	862:2afa79e3ed0a	34	class BLEInstanceBase;
rgrover1	859:38a4963a455e	35
rgrover1	717:11b41f651697	36	/**
vcoubard	1049:efb29faf12fc	37	* The base class used to abstract away BLE-capable radio transceivers or SOCs,
vcoubard	1049:efb29faf12fc	38	* so that the BLE API can work with any radio transparently.
rgrover1	717:11b41f651697	39	*/
rgrover1	717:11b41f651697	40	class BLE
rgrover1	717:11b41f651697	41	{
rgrover1	717:11b41f651697	42	public:
rgrover1	862:2afa79e3ed0a	43	typedef unsigned InstanceID_t; /** The type returned by BLE::getInstanceID(). */
rgrover1	862:2afa79e3ed0a	44
rgrover1	862:2afa79e3ed0a	45	/**
rgrover1	887:0a45c67b2301	46	* The context provided to init-completion-callbacks (see init() below).
rgrover1	887:0a45c67b2301	47	*
rgrover1	862:2afa79e3ed0a	48	* @param ble
rgrover1	862:2afa79e3ed0a	49	* A reference to the BLE instance being initialized.
rgrover1	862:2afa79e3ed0a	50	* @param error
vcoubard	1049:efb29faf12fc	51	* Captures the result of initialization. It is set to
rgrover1	862:2afa79e3ed0a	52	* BLE_ERROR_NONE if initialization completed successfully. Else
rgrover1	862:2afa79e3ed0a	53	* the error value is implementation specific.
rgrover1	862:2afa79e3ed0a	54	*/
rgrover1	887:0a45c67b2301	55	struct InitializationCompleteCallbackContext {
vcoubard	1049:efb29faf12fc	56	BLE& ble; /* Reference to the BLE object that has been initialized */
vcoubard	1049:efb29faf12fc	57	ble_error_t error; /* Error status of the initialization. It is set to BLE_ERROR_NONE if initialization completed successfully. */
rgrover1	887:0a45c67b2301	58	};
rgrover1	887:0a45c67b2301	59
rgrover1	887:0a45c67b2301	60	/**
rgrover1	887:0a45c67b2301	61	* The signature for function-pointer like callbacks for initialization-completion.
rgrover1	887:0a45c67b2301	62	*
rgrover1	887:0a45c67b2301	63	* @note There are two versions of init(). In addition to the simple
rgrover1	887:0a45c67b2301	64	* function-pointer, init() can also take a <Object, member> tuple as its
rgrover1	887:0a45c67b2301	65	* callback target. In case of the latter, the following declaration doesn't apply.
rgrover1	887:0a45c67b2301	66	*/
rgrover1	887:0a45c67b2301	67	typedef void (InitializationCompleteCallback_t)(InitializationCompleteCallbackContext context);
rgrover1	862:2afa79e3ed0a	68
rgrover1	717:11b41f651697	69	/**
rgrover1	717:11b41f651697	70	* Initialize the BLE controller. This should be called before using
rgrover1	717:11b41f651697	71	* anything else in the BLE_API.
rgrover1	717:11b41f651697	72	*
rgrover1	717:11b41f651697	73	* init() hands control to the underlying BLE module to accomplish
rgrover1	717:11b41f651697	74	* initialization. This initialization may tacitly depend on other hardware
vcoubard	1049:efb29faf12fc	75	* setup (such as clocks or power-modes) that happens early on during
vcoubard	1049:efb29faf12fc	76	* system startup. It may not be safe to call init() from a global static
vcoubard	1049:efb29faf12fc	77	* context where ordering is compiler-specific and can't be guaranteed - it
rgrover1	717:11b41f651697	78	* is safe to call BLE::init() from within main().
rgrover1	862:2afa79e3ed0a	79	*
rgrover1	887:0a45c67b2301	80	* @param initCompleteCallback
rgrover1	862:2afa79e3ed0a	81	* A callback for when initialization completes for a BLE
vcoubard	1049:efb29faf12fc	82	* instance. This is an optional parameter; if no callback is
vcoubard	1049:efb29faf12fc	83	* set up the application can still determine the status of
rgrover1	862:2afa79e3ed0a	84	* initialization using BLE::hasInitialized() (see below).
rgrover1	862:2afa79e3ed0a	85	*
rgrover1	862:2afa79e3ed0a	86	* @return BLE_ERROR_NONE if the initialization procedure was started
rgrover1	862:2afa79e3ed0a	87	* successfully.
rgrover1	862:2afa79e3ed0a	88	*
rgrover1	887:0a45c67b2301	89	* @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke
rgrover1	887:0a45c67b2301	90	* the initialization completion callback at some point.
rgrover1	887:0a45c67b2301	91	*
rgrover1	887:0a45c67b2301	92	* @note In some cases, initialization is instantaneous (or blocking); if
rgrover1	887:0a45c67b2301	93	* so, it is acceptable for the stack-specific implementation of init()
vcoubard	1049:efb29faf12fc	94	* to invoke the completion callback directly (within its own
vcoubard	1049:efb29faf12fc	95	* context).
rgrover1	862:2afa79e3ed0a	96	*
rgrover1	862:2afa79e3ed0a	97	* @note Nearly all BLE APIs would return
rgrover1	862:2afa79e3ed0a	98	* BLE_ERROR_INITIALIZATION_INCOMPLETE if used on an instance before the
rgrover1	862:2afa79e3ed0a	99	* corresponding transport is initialized.
rgrover1	887:0a45c67b2301	100	*
rgrover1	887:0a45c67b2301	101	* @note There are two versions of init(). In addition to the simple
rgrover1	887:0a45c67b2301	102	* function-pointer, init() can also take an <Object, member> tuple as its
rgrover1	887:0a45c67b2301	103	* callback target.
rgrover1	717:11b41f651697	104	*/
rgrover1	887:0a45c67b2301	105	ble_error_t init(InitializationCompleteCallback_t initCompleteCallback = NULL) {
rgrover1	887:0a45c67b2301	106	FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(initCompleteCallback);
rgrover1	888:fed45b77c90c	107	return initImplementation(callback);
rgrover1	887:0a45c67b2301	108	}
rgrover1	887:0a45c67b2301	109
rgrover1	887:0a45c67b2301	110	/**
rgrover1	887:0a45c67b2301	111	* An alternate declaration for init(). This one takes an <Object, member> tuple as its
rgrover1	887:0a45c67b2301	112	* callback target.
rgrover1	887:0a45c67b2301	113	*/
rgrover1	887:0a45c67b2301	114	template<typename T>
rgrover1	887:0a45c67b2301	115	ble_error_t init(T object, void (T::initCompleteCallback)(InitializationCompleteCallbackContext *context)) {
rgrover1	887:0a45c67b2301	116	FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(object, initCompleteCallback);
rgrover1	888:fed45b77c90c	117	return initImplementation(callback);
rgrover1	887:0a45c67b2301	118	}
rgrover1	875:0607a58418ce	119
rgrover1	875:0607a58418ce	120	/**
rgrover1	862:2afa79e3ed0a	121	* @return true if initialization has completed for the underlying BLE
rgrover1	862:2afa79e3ed0a	122	* transport.
rgrover1	862:2afa79e3ed0a	123	*
vcoubard	1049:efb29faf12fc	124	* The application can set up a callback to signal completion of
rgrover1	862:2afa79e3ed0a	125	* initialization when using init(). Otherwise, this method can be used to
rgrover1	862:2afa79e3ed0a	126	* poll the state of initialization.
rgrover1	862:2afa79e3ed0a	127	*/
rgrover1	862:2afa79e3ed0a	128	bool hasInitialized(void) const;
rgrover1	717:11b41f651697	129
rgrover1	717:11b41f651697	130	/**
rgrover1	717:11b41f651697	131	* Purge the BLE stack of GATT and GAP state. init() must be called
rgrover1	717:11b41f651697	132	* afterwards to re-instate services and GAP state. This API offers a way to
rgrover1	717:11b41f651697	133	* repopulate the GATT database with new services and characteristics.
rgrover1	717:11b41f651697	134	*/
rgrover1	862:2afa79e3ed0a	135	ble_error_t shutdown(void);
rgrover1	717:11b41f651697	136
rgrover1	717:11b41f651697	137	/**
rgrover1	717:11b41f651697	138	* This call allows the application to get the BLE stack version information.
rgrover1	717:11b41f651697	139	*
rgrover1	717:11b41f651697	140	* @return A pointer to a const string representing the version.
vcoubard	1049:efb29faf12fc	141	* Note: The string is owned by BLE_API.
rgrover1	717:11b41f651697	142	*/
rgrover1	862:2afa79e3ed0a	143	const char *getVersion(void);
rgrover1	717:11b41f651697	144
rgrover1	717:11b41f651697	145	/*
rgrover1	717:11b41f651697	146	* Accessors to GAP. Please refer to Gap.h. All GAP related functionality requires
rgrover1	717:11b41f651697	147	* going through this accessor.
rgrover1	717:11b41f651697	148	*/
rgrover1	862:2afa79e3ed0a	149	const Gap &gap() const;
rgrover1	862:2afa79e3ed0a	150	Gap &gap();
rgrover1	717:11b41f651697	151
rgrover1	717:11b41f651697	152	/*
rgrover1	717:11b41f651697	153	* Accessors to GATT Server. Please refer to GattServer.h. All GATTServer related
rgrover1	717:11b41f651697	154	* functionality requires going through this accessor.
rgrover1	717:11b41f651697	155	*/
rgrover1	862:2afa79e3ed0a	156	const GattServer& gattServer() const;
rgrover1	862:2afa79e3ed0a	157	GattServer& gattServer();
rgrover1	717:11b41f651697	158
rgrover1	717:11b41f651697	159	/*
rgrover1	717:11b41f651697	160	* Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related
rgrover1	717:11b41f651697	161	* functionality requires going through this accessor.
rgrover1	717:11b41f651697	162	*/
rgrover1	862:2afa79e3ed0a	163	const GattClient& gattClient() const;
rgrover1	862:2afa79e3ed0a	164	GattClient& gattClient();
rgrover1	717:11b41f651697	165
rgrover1	717:11b41f651697	166	/*
rgrover1	717:11b41f651697	167	* Accessors to Security Manager. Please refer to SecurityManager.h. All
rgrover1	717:11b41f651697	168	* SecurityManager related functionality requires going through this
rgrover1	717:11b41f651697	169	* accessor.
rgrover1	717:11b41f651697	170	*/
rgrover1	862:2afa79e3ed0a	171	const SecurityManager& securityManager() const;
rgrover1	862:2afa79e3ed0a	172	SecurityManager& securityManager();
rgrover1	717:11b41f651697	173
rgrover1	717:11b41f651697	174	/**
rgrover1	717:11b41f651697	175	* Yield control to the BLE stack or to other tasks waiting for events. This
vcoubard	1049:efb29faf12fc	176	* is a sleep function that will return when there is an application-specific
vcoubard	1049:efb29faf12fc	177	* interrupt, but the MCU might wake up several times before
rgrover1	717:11b41f651697	178	* returning (to service the stack). This is not always interchangeable with
rgrover1	717:11b41f651697	179	* WFE().
rgrover1	717:11b41f651697	180	*/
rgrover1	862:2afa79e3ed0a	181	void waitForEvent(void);
rgrover1	717:11b41f651697	182
rgrover1	823:a0f080d1e836	183	public:
rgrover1	823:a0f080d1e836	184	static const InstanceID_t DEFAULT_INSTANCE = 0;
rgrover1	823:a0f080d1e836	185	#ifndef YOTTA_CFG_BLE_INSTANCES_COUNT
rgrover1	823:a0f080d1e836	186	static const InstanceID_t NUM_INSTANCES = 1;
rgrover1	823:a0f080d1e836	187	#else
rgrover1	823:a0f080d1e836	188	static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT;
rgrover1	823:a0f080d1e836	189	#endif
rgrover1	823:a0f080d1e836	190
rgrover1	823:a0f080d1e836	191	/**
rgrover1	823:a0f080d1e836	192	* Get a reference to the BLE singleton corresponding to a given interface.
rgrover1	823:a0f080d1e836	193	* There is a static array of BLE singletons.
rgrover1	823:a0f080d1e836	194	*
rgrover1	823:a0f080d1e836	195	* @Note: Calling Instance() is preferred over constructing a BLE object
rgrover1	823:a0f080d1e836	196	* directly, as it returns references to singletons.
rgrover1	823:a0f080d1e836	197	*
rgrover1	823:a0f080d1e836	198	* @param[in] id
vcoubard	1079:79c089630b38	199	* Instance-ID. This should be less than NUM_INSTANCES
rgrover1	823:a0f080d1e836	200	* for the returned BLE singleton to be useful.
rgrover1	823:a0f080d1e836	201	*
vcoubard	1049:efb29faf12fc	202	* @return a reference to a single object.
rgrover1	823:a0f080d1e836	203	*/
rgrover1	823:a0f080d1e836	204	static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE);
rgrover1	823:a0f080d1e836	205
rgrover1	823:a0f080d1e836	206	/**
vcoubard	1049:efb29faf12fc	207	* Constructor for a handle to a BLE instance (the BLE stack). BLE handles
vcoubard	1049:efb29faf12fc	208	* are thin wrappers around a transport object (that is, ptr. to
rgrover1	823:a0f080d1e836	209	* BLEInstanceBase).
rgrover1	823:a0f080d1e836	210	*
vcoubard	1049:efb29faf12fc	211	* It is better to create BLE objects as singletons accessed through the
rgrover1	823:a0f080d1e836	212	* Instance() method. If multiple BLE handles are constructed for the same
rgrover1	823:a0f080d1e836	213	* interface (using this constructor), they will share the same underlying
rgrover1	823:a0f080d1e836	214	* transport object.
rgrover1	823:a0f080d1e836	215	*/
rgrover1	823:a0f080d1e836	216	BLE(InstanceID_t instanceID = DEFAULT_INSTANCE);
rgrover1	823:a0f080d1e836	217
rgrover1	862:2afa79e3ed0a	218	/**
rgrover1	862:2afa79e3ed0a	219	* Fetch the ID of a BLE instance. Typically there would only be the DEFAULT_INSTANCE.
rgrover1	862:2afa79e3ed0a	220	*/
rgrover1	862:2afa79e3ed0a	221	InstanceID_t getInstanceID(void) const {
rgrover1	862:2afa79e3ed0a	222	return instanceID;
rgrover1	862:2afa79e3ed0a	223	}
rgrover1	823:a0f080d1e836	224
rgrover1	717:11b41f651697	225	/*
rgrover1	717:11b41f651697	226	* Deprecation alert!
rgrover1	717:11b41f651697	227	* All of the following are deprecated and may be dropped in a future
rgrover1	717:11b41f651697	228	* release. Documentation should refer to alternative APIs.
rgrover1	717:11b41f651697	229	*/
rgrover1	717:11b41f651697	230
rgrover1	717:11b41f651697	231	/* GAP specific APIs. */
rgrover1	717:11b41f651697	232	public:
rgrover1	717:11b41f651697	233	/**
rgrover1	717:11b41f651697	234	* Set the BTLE MAC address and type.
rgrover1	717:11b41f651697	235	* @return BLE_ERROR_NONE on success.
rgrover1	717:11b41f651697	236	*
rgrover1	717:11b41f651697	237	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	238	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	239	* ble.setAddress(...) should be replaced with
rgrover1	717:11b41f651697	240	* ble.gap().setAddress(...).
rgrover1	717:11b41f651697	241	*/
vcoubard	1116:82d4a8a56d91	242	ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
rgrover1	717:11b41f651697	243	return gap().setAddress(type, address);
rgrover1	717:11b41f651697	244	}
rgrover1	717:11b41f651697	245
rgrover1	717:11b41f651697	246	/**
rgrover1	717:11b41f651697	247	* Fetch the BTLE MAC address and type.
rgrover1	717:11b41f651697	248	* @return BLE_ERROR_NONE on success.
rgrover1	717:11b41f651697	249	*
rgrover1	717:11b41f651697	250	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	251	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	252	* ble.getAddress(...) should be replaced with
rgrover1	717:11b41f651697	253	* ble.gap().getAddress(...).
rgrover1	717:11b41f651697	254	*/
vcoubard	1116:82d4a8a56d91	255	ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
rgrover1	717:11b41f651697	256	return gap().getAddress(typeP, address);
rgrover1	717:11b41f651697	257	}
rgrover1	717:11b41f651697	258
rgrover1	717:11b41f651697	259	/**
rgrover1	717:11b41f651697	260	* Set the GAP advertising mode to use for this device.
rgrover1	717:11b41f651697	261	*
rgrover1	717:11b41f651697	262	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	263	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	264	* ble.setAdvertisingType(...) should be replaced with
rgrover1	717:11b41f651697	265	* ble.gap().setAdvertisingType(...).
rgrover1	717:11b41f651697	266	*/
rgrover1	717:11b41f651697	267	void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
rgrover1	717:11b41f651697	268	gap().setAdvertisingType(advType);
rgrover1	717:11b41f651697	269	}
rgrover1	717:11b41f651697	270
rgrover1	717:11b41f651697	271	/**
rgrover1	717:11b41f651697	272	* @param[in] interval
rgrover1	717:11b41f651697	273	* Advertising interval in units of milliseconds. Advertising
rgrover1	717:11b41f651697	274	* is disabled if interval is 0. If interval is smaller than
rgrover1	717:11b41f651697	275	* the minimum supported value, then the minimum supported
rgrover1	717:11b41f651697	276	* value is used instead. This minimum value can be discovered
rgrover1	717:11b41f651697	277	* using getMinAdvertisingInterval().
rgrover1	717:11b41f651697	278	*
rgrover1	717:11b41f651697	279	* This field must be set to 0 if connectionMode is equal
rgrover1	717:11b41f651697	280	* to ADV_CONNECTABLE_DIRECTED.
rgrover1	717:11b41f651697	281	*
vcoubard	1049:efb29faf12fc	282	* @note: Decreasing this value allows central devices to detect a
vcoubard	1049:efb29faf12fc	283	* peripheral faster, at the expense of more power being used by the radio
rgrover1	717:11b41f651697	284	* due to the higher data transmit rate.
rgrover1	717:11b41f651697	285	*
rgrover1	717:11b41f651697	286	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	287	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	288	* ble.setAdvertisingInterval(...) should be replaced with
rgrover1	717:11b41f651697	289	* ble.gap().setAdvertisingInterval(...).
rgrover1	717:11b41f651697	290	*
rgrover1	717:11b41f651697	291	* @note: [WARNING] This API previously used 0.625ms as the unit for its
rgrover1	717:11b41f651697	292	* 'interval' argument. That required an explicit conversion from
rgrover1	717:11b41f651697	293	* milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
rgrover1	717:11b41f651697	294	* no longer required as the new units are milliseconds. Any application
vcoubard	1049:efb29faf12fc	295	* code depending on the old semantics needs to be updated accordingly.
rgrover1	717:11b41f651697	296	*/
rgrover1	717:11b41f651697	297	void setAdvertisingInterval(uint16_t interval) {
rgrover1	717:11b41f651697	298	gap().setAdvertisingInterval(interval);
rgrover1	717:11b41f651697	299	}
rgrover1	717:11b41f651697	300
rgrover1	717:11b41f651697	301	/**
rgrover1	717:11b41f651697	302	* @return Minimum Advertising interval in milliseconds.
rgrover1	717:11b41f651697	303	*
rgrover1	717:11b41f651697	304	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	305	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	306	* ble.getMinAdvertisingInterval(...) should be replaced with
rgrover1	717:11b41f651697	307	* ble.gap().getMinAdvertisingInterval(...).
rgrover1	717:11b41f651697	308	*/
rgrover1	717:11b41f651697	309	uint16_t getMinAdvertisingInterval(void) const {
rgrover1	717:11b41f651697	310	return gap().getMinAdvertisingInterval();
rgrover1	717:11b41f651697	311	}
rgrover1	717:11b41f651697	312
rgrover1	717:11b41f651697	313	/**
rgrover1	717:11b41f651697	314	* @return Minimum Advertising interval in milliseconds for non-connectible mode.
rgrover1	717:11b41f651697	315	*
rgrover1	717:11b41f651697	316	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	317	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	318	* ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
rgrover1	717:11b41f651697	319	* ble.gap().getMinNonConnectableAdvertisingInterval(...).
rgrover1	717:11b41f651697	320	*/
rgrover1	717:11b41f651697	321	uint16_t getMinNonConnectableAdvertisingInterval(void) const {
rgrover1	717:11b41f651697	322	return gap().getMinNonConnectableAdvertisingInterval();
rgrover1	717:11b41f651697	323	}
rgrover1	717:11b41f651697	324
rgrover1	717:11b41f651697	325	/**
rgrover1	717:11b41f651697	326	* @return Maximum Advertising interval in milliseconds.
rgrover1	717:11b41f651697	327	*
rgrover1	717:11b41f651697	328	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	329	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	330	* ble.getMaxAdvertisingInterval(...) should be replaced with
rgrover1	717:11b41f651697	331	* ble.gap().getMaxAdvertisingInterval(...).
rgrover1	717:11b41f651697	332	*/
rgrover1	717:11b41f651697	333	uint16_t getMaxAdvertisingInterval(void) const {
rgrover1	717:11b41f651697	334	return gap().getMaxAdvertisingInterval();
rgrover1	717:11b41f651697	335	}
rgrover1	717:11b41f651697	336
rgrover1	717:11b41f651697	337	/**
rgrover1	717:11b41f651697	338	* @param[in] timeout
rgrover1	717:11b41f651697	339	* Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
rgrover1	717:11b41f651697	340	* and 16383). Use 0 to disable the advertising timeout.
rgrover1	717:11b41f651697	341	*
rgrover1	717:11b41f651697	342	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	343	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	344	* ble.setAdvertisingTimeout(...) should be replaced with
rgrover1	717:11b41f651697	345	* ble.gap().setAdvertisingTimeout(...).
rgrover1	717:11b41f651697	346	*/
rgrover1	717:11b41f651697	347	void setAdvertisingTimeout(uint16_t timeout) {
rgrover1	717:11b41f651697	348	gap().setAdvertisingTimeout(timeout);
rgrover1	717:11b41f651697	349	}
rgrover1	717:11b41f651697	350
rgrover1	717:11b41f651697	351	/**
vcoubard	1049:efb29faf12fc	352	* Set up a particular, user-constructed set of advertisement parameters for
rgrover1	717:11b41f651697	353	* the underlying stack. It would be uncommon for this API to be used
rgrover1	717:11b41f651697	354	* directly; there are other APIs to tweak advertisement parameters
rgrover1	717:11b41f651697	355	* individually (see above).
rgrover1	717:11b41f651697	356	*
rgrover1	717:11b41f651697	357	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	358	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	359	* ble.setAdvertisingParams(...) should be replaced with
rgrover1	717:11b41f651697	360	* ble.gap().setAdvertisingParams(...).
rgrover1	717:11b41f651697	361	*/
rgrover1	717:11b41f651697	362	void setAdvertisingParams(const GapAdvertisingParams &advParams) {
rgrover1	717:11b41f651697	363	gap().setAdvertisingParams(advParams);
rgrover1	717:11b41f651697	364	}
rgrover1	717:11b41f651697	365
rgrover1	717:11b41f651697	366	/**
rgrover1	717:11b41f651697	367	* @return Read back advertising parameters. Useful for storing and
rgrover1	717:11b41f651697	368	* restoring parameters rapidly.
rgrover1	717:11b41f651697	369	*
rgrover1	717:11b41f651697	370	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	371	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	372	* ble.getAdvertisingParams(...) should be replaced with
rgrover1	717:11b41f651697	373	* ble.gap().getAdvertisingParams(...).
rgrover1	717:11b41f651697	374	*/
rgrover1	717:11b41f651697	375	const GapAdvertisingParams &getAdvertisingParams(void) const {
rgrover1	717:11b41f651697	376	return gap().getAdvertisingParams();
rgrover1	717:11b41f651697	377	}
rgrover1	717:11b41f651697	378
rgrover1	717:11b41f651697	379	/**
rgrover1	717:11b41f651697	380	* Accumulate an AD structure in the advertising payload. Please note that
rgrover1	717:11b41f651697	381	* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard	1049:efb29faf12fc	382	* as an additional 31 bytes if the advertising payload is too
rgrover1	717:11b41f651697	383	* small.
rgrover1	717:11b41f651697	384	*
rgrover1	717:11b41f651697	385	* @param[in] flags
vcoubard	1049:efb29faf12fc	386	* The flags to add. Please refer to
rgrover1	717:11b41f651697	387	* GapAdvertisingData::Flags for valid flags. Multiple
rgrover1	717:11b41f651697	388	* flags may be specified in combination.
rgrover1	717:11b41f651697	389	*
rgrover1	717:11b41f651697	390	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	391	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	392	* ble.accumulateAdvertisingPayload(flags) should be replaced with
rgrover1	717:11b41f651697	393	* ble.gap().accumulateAdvertisingPayload(flags).
rgrover1	717:11b41f651697	394	*/
rgrover1	717:11b41f651697	395	ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
rgrover1	717:11b41f651697	396	return gap().accumulateAdvertisingPayload(flags);
rgrover1	717:11b41f651697	397	}
rgrover1	717:11b41f651697	398
rgrover1	717:11b41f651697	399	/**
rgrover1	717:11b41f651697	400	* Accumulate an AD structure in the advertising payload. Please note that
rgrover1	717:11b41f651697	401	* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard	1049:efb29faf12fc	402	* as an additional 31 bytes if the advertising payload is too
rgrover1	717:11b41f651697	403	* small.
rgrover1	717:11b41f651697	404	*
rgrover1	717:11b41f651697	405	* @param[in] app
rgrover1	717:11b41f651697	406	* The appearance of the peripheral.
rgrover1	717:11b41f651697	407	*
rgrover1	717:11b41f651697	408	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	409	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	410	* ble.accumulateAdvertisingPayload(appearance) should be replaced with
rgrover1	717:11b41f651697	411	* ble.gap().accumulateAdvertisingPayload(appearance).
rgrover1	717:11b41f651697	412	*/
rgrover1	717:11b41f651697	413	ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
rgrover1	717:11b41f651697	414	return gap().accumulateAdvertisingPayload(app);
rgrover1	717:11b41f651697	415	}
rgrover1	717:11b41f651697	416
rgrover1	717:11b41f651697	417	/**
rgrover1	717:11b41f651697	418	* Accumulate an AD structure in the advertising payload. Please note that
rgrover1	717:11b41f651697	419	* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
vcoubard	1049:efb29faf12fc	420	* as an additional 31 bytes if the advertising payload is too
rgrover1	717:11b41f651697	421	* small.
rgrover1	717:11b41f651697	422	*
rgrover1	717:11b41f651697	423	* @param[in] app
rgrover1	717:11b41f651697	424	* The max transmit power to be used by the controller. This
rgrover1	717:11b41f651697	425	* is only a hint.
rgrover1	717:11b41f651697	426	*
rgrover1	717:11b41f651697	427	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	428	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	429	* ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
rgrover1	717:11b41f651697	430	* ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
rgrover1	717:11b41f651697	431	*/
rgrover1	717:11b41f651697	432	ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
rgrover1	717:11b41f651697	433	return gap().accumulateAdvertisingPayloadTxPower(power);
rgrover1	717:11b41f651697	434	}
rgrover1	717:11b41f651697	435
rgrover1	717:11b41f651697	436	/**
rgrover1	717:11b41f651697	437	* Accumulate a variable length byte-stream as an AD structure in the
rgrover1	717:11b41f651697	438	* advertising payload. Please note that the payload is limited to 31 bytes.
rgrover1	717:11b41f651697	439	* The SCAN_RESPONSE message may be used as an additional 31 bytes if the
vcoubard	1049:efb29faf12fc	440	* advertising payload is too small.
rgrover1	717:11b41f651697	441	*
vcoubard	1049:efb29faf12fc	442	* @param type The type that describes the variable length data.
vcoubard	1049:efb29faf12fc	443	* @param data Data bytes.
vcoubard	1049:efb29faf12fc	444	* @param len Data length.
rgrover1	717:11b41f651697	445	*
rgrover1	717:11b41f651697	446	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	447	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	448	* ble.accumulateAdvertisingPayload(...) should be replaced with
rgrover1	717:11b41f651697	449	* ble.gap().accumulateAdvertisingPayload(...).
rgrover1	717:11b41f651697	450	*/
rgrover1	717:11b41f651697	451	ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
rgrover1	717:11b41f651697	452	return gap().accumulateAdvertisingPayload(type, data, len);
rgrover1	717:11b41f651697	453	}
rgrover1	717:11b41f651697	454
rgrover1	717:11b41f651697	455	/**
rgrover1	717:11b41f651697	456	* Setup a particular, user-constructed advertisement payload for the
rgrover1	717:11b41f651697	457	* underlying stack. It would be uncommon for this API to be used directly;
rgrover1	717:11b41f651697	458	* there are other APIs to build an advertisement payload (see above).
rgrover1	717:11b41f651697	459	*
rgrover1	717:11b41f651697	460	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	461	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	462	* ble.setAdvertisingData(...) should be replaced with
rgrover1	717:11b41f651697	463	* ble.gap().setAdvertisingPayload(...).
rgrover1	717:11b41f651697	464	*/
rgrover1	717:11b41f651697	465	ble_error_t setAdvertisingData(const GapAdvertisingData &advData) {
rgrover1	717:11b41f651697	466	return gap().setAdvertisingPayload(advData);
rgrover1	717:11b41f651697	467	}
rgrover1	717:11b41f651697	468
rgrover1	717:11b41f651697	469	/**
rgrover1	717:11b41f651697	470	* @return Read back advertising data. Useful for storing and
rgrover1	717:11b41f651697	471	* restoring payload.
rgrover1	717:11b41f651697	472	*
rgrover1	717:11b41f651697	473	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	474	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	475	* ble.getAdvertisingData(...) should be replaced with
rgrover1	717:11b41f651697	476	* ble.gap().getAdvertisingPayload()(...).
rgrover1	717:11b41f651697	477	*/
rgrover1	717:11b41f651697	478	const GapAdvertisingData &getAdvertisingData(void) const {
rgrover1	717:11b41f651697	479	return gap().getAdvertisingPayload();
rgrover1	717:11b41f651697	480	}
rgrover1	717:11b41f651697	481
rgrover1	717:11b41f651697	482	/**
rgrover1	717:11b41f651697	483	* Reset any advertising payload prepared from prior calls to
rgrover1	717:11b41f651697	484	* accumulateAdvertisingPayload(). This automatically propagates the re-
vcoubard	1049:efb29faf12fc	485	* initialized advertising payload to the underlying stack.
rgrover1	717:11b41f651697	486	*
rgrover1	717:11b41f651697	487	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	488	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	489	* ble.clearAdvertisingPayload(...) should be replaced with
rgrover1	717:11b41f651697	490	* ble.gap().clearAdvertisingPayload(...).
rgrover1	717:11b41f651697	491	*/
rgrover1	717:11b41f651697	492	void clearAdvertisingPayload(void) {
rgrover1	717:11b41f651697	493	gap().clearAdvertisingPayload();
rgrover1	717:11b41f651697	494	}
rgrover1	717:11b41f651697	495
rgrover1	717:11b41f651697	496	/**
rgrover1	717:11b41f651697	497	* This API is deprecated and resolves to a no-operation. It is left here
rgrover1	717:11b41f651697	498	* to allow older code to compile. Please avoid using this API in new code.
rgrover1	717:11b41f651697	499	* This API will be dropped in a future release.
rgrover1	717:11b41f651697	500	*
rgrover1	717:11b41f651697	501	* Formerly, it would be used to dynamically reset the accumulated advertising
rgrover1	717:11b41f651697	502	* payload and scanResponse; to do this, the application would clear and re-
rgrover1	717:11b41f651697	503	* accumulate a new advertising payload (and scanResponse) before using this
rgrover1	717:11b41f651697	504	* API. Updates to the underlying advertisement payload now happen
rgrover1	717:11b41f651697	505	* implicitly.
rgrover1	717:11b41f651697	506	*/
rgrover1	717:11b41f651697	507	ble_error_t setAdvertisingPayload(void) {
rgrover1	717:11b41f651697	508	return BLE_ERROR_NONE;
rgrover1	717:11b41f651697	509	}
rgrover1	717:11b41f651697	510
rgrover1	717:11b41f651697	511	/**
rgrover1	717:11b41f651697	512	* Accumulate a variable length byte-stream as an AD structure in the
rgrover1	717:11b41f651697	513	* scanResponse payload.
rgrover1	717:11b41f651697	514	*
vcoubard	1049:efb29faf12fc	515	* @param[in] type The type that describes the variable length data.
vcoubard	1049:efb29faf12fc	516	* @param[in] data Data bytes.
vcoubard	1049:efb29faf12fc	517	* @param[in] len Data length.
rgrover1	717:11b41f651697	518	*
rgrover1	717:11b41f651697	519	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	520	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	521	* ble.accumulateScanResponse(...) should be replaced with
rgrover1	717:11b41f651697	522	* ble.gap().accumulateScanResponse(...).
rgrover1	717:11b41f651697	523	*/
rgrover1	717:11b41f651697	524	ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
rgrover1	717:11b41f651697	525	return gap().accumulateScanResponse(type, data, len);
rgrover1	717:11b41f651697	526	}
rgrover1	717:11b41f651697	527
rgrover1	717:11b41f651697	528	/**
rgrover1	717:11b41f651697	529	* Reset any scan response prepared from prior calls to
rgrover1	717:11b41f651697	530	* accumulateScanResponse().
rgrover1	717:11b41f651697	531	*
rgrover1	717:11b41f651697	532	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	533	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	534	* ble.clearScanResponse(...) should be replaced with
rgrover1	717:11b41f651697	535	* ble.gap().clearScanResponse(...).
rgrover1	717:11b41f651697	536	*/
rgrover1	717:11b41f651697	537	void clearScanResponse(void) {
rgrover1	717:11b41f651697	538	gap().clearScanResponse();
rgrover1	717:11b41f651697	539	}
rgrover1	717:11b41f651697	540
rgrover1	717:11b41f651697	541	/**
rgrover1	717:11b41f651697	542	* Start advertising.
rgrover1	717:11b41f651697	543	*
rgrover1	717:11b41f651697	544	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	545	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	546	* ble.startAdvertising(...) should be replaced with
rgrover1	717:11b41f651697	547	* ble.gap().startAdvertising(...).
rgrover1	717:11b41f651697	548	*/
rgrover1	717:11b41f651697	549	ble_error_t startAdvertising(void) {
rgrover1	717:11b41f651697	550	return gap().startAdvertising();
rgrover1	717:11b41f651697	551	}
rgrover1	717:11b41f651697	552
rgrover1	717:11b41f651697	553	/**
rgrover1	717:11b41f651697	554	* Stop advertising.
rgrover1	717:11b41f651697	555	*
rgrover1	717:11b41f651697	556	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	557	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	558	* ble.stopAdvertising(...) should be replaced with
rgrover1	717:11b41f651697	559	* ble.gap().stopAdvertising(...).
rgrover1	717:11b41f651697	560	*/
rgrover1	717:11b41f651697	561	ble_error_t stopAdvertising(void) {
rgrover1	717:11b41f651697	562	return gap().stopAdvertising();
rgrover1	717:11b41f651697	563	}
rgrover1	717:11b41f651697	564
rgrover1	717:11b41f651697	565	/**
vcoubard	1049:efb29faf12fc	566	* Set up parameters for GAP scanning (observer mode).
rgrover1	717:11b41f651697	567	* @param[in] interval
rgrover1	717:11b41f651697	568	* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
rgrover1	717:11b41f651697	569	* @param[in] window
rgrover1	717:11b41f651697	570	* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
rgrover1	717:11b41f651697	571	* @param[in] timeout
vcoubard	1049:efb29faf12fc	572	* Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
rgrover1	717:11b41f651697	573	* @param[in] activeScanning
rgrover1	717:11b41f651697	574	* Set to True if active-scanning is required. This is used to fetch the
rgrover1	717:11b41f651697	575	* scan response from a peer if possible.
rgrover1	717:11b41f651697	576	*
rgrover1	717:11b41f651697	577	* The scanning window divided by the interval determines the duty cycle for
rgrover1	717:11b41f651697	578	* scanning. For example, if the interval is 100ms and the window is 10ms,
rgrover1	717:11b41f651697	579	* then the controller will scan for 10 percent of the time. It is possible
rgrover1	717:11b41f651697	580	* to have the interval and window set to the same value. In this case,
rgrover1	717:11b41f651697	581	* scanning is continuous, with a change of scanning frequency once every
rgrover1	717:11b41f651697	582	* interval.
rgrover1	717:11b41f651697	583	*
rgrover1	717:11b41f651697	584	* Once the scanning parameters have been configured, scanning can be
rgrover1	717:11b41f651697	585	* enabled by using startScan().
rgrover1	717:11b41f651697	586	*
rgrover1	717:11b41f651697	587	* @Note: The scan interval and window are recommendations to the BLE stack.
rgrover1	717:11b41f651697	588	*
rgrover1	717:11b41f651697	589	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	590	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	591	* ble.setScanParams(...) should be replaced with
rgrover1	717:11b41f651697	592	* ble.gap().setScanParams(...).
rgrover1	717:11b41f651697	593	*/
rgrover1	717:11b41f651697	594	ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
rgrover1	717:11b41f651697	595	uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
rgrover1	717:11b41f651697	596	uint16_t timeout = 0,
rgrover1	717:11b41f651697	597	bool activeScanning = false) {
rgrover1	717:11b41f651697	598	return gap().setScanParams(interval, window, timeout, activeScanning);
rgrover1	717:11b41f651697	599	}
rgrover1	717:11b41f651697	600
rgrover1	717:11b41f651697	601	/**
vcoubard	1049:efb29faf12fc	602	* Set up the scanInterval parameter for GAP scanning (observer mode).
rgrover1	717:11b41f651697	603	* @param[in] interval
rgrover1	717:11b41f651697	604	* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
rgrover1	717:11b41f651697	605	*
rgrover1	717:11b41f651697	606	* The scanning window divided by the interval determines the duty cycle for
rgrover1	717:11b41f651697	607	* scanning. For example, if the interval is 100ms and the window is 10ms,
rgrover1	717:11b41f651697	608	* then the controller will scan for 10 percent of the time. It is possible
rgrover1	717:11b41f651697	609	* to have the interval and window set to the same value. In this case,
rgrover1	717:11b41f651697	610	* scanning is continuous, with a change of scanning frequency once every
rgrover1	717:11b41f651697	611	* interval.
rgrover1	717:11b41f651697	612	*
rgrover1	717:11b41f651697	613	* Once the scanning parameters have been configured, scanning can be
rgrover1	717:11b41f651697	614	* enabled by using startScan().
rgrover1	717:11b41f651697	615	*
rgrover1	717:11b41f651697	616	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	617	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	618	* ble.setScanInterval(interval) should be replaced with
rgrover1	717:11b41f651697	619	* ble.gap().setScanInterval(interval).
rgrover1	717:11b41f651697	620	*/
rgrover1	717:11b41f651697	621	ble_error_t setScanInterval(uint16_t interval) {
rgrover1	717:11b41f651697	622	return gap().setScanInterval(interval);
rgrover1	717:11b41f651697	623	}
rgrover1	717:11b41f651697	624
rgrover1	717:11b41f651697	625	/**
vcoubard	1049:efb29faf12fc	626	* Set up the scanWindow parameter for GAP scanning (observer mode).
rgrover1	717:11b41f651697	627	* @param[in] window
rgrover1	717:11b41f651697	628	* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
rgrover1	717:11b41f651697	629	*
rgrover1	717:11b41f651697	630	* The scanning window divided by the interval determines the duty cycle for
rgrover1	717:11b41f651697	631	* scanning. For example, if the interval is 100ms and the window is 10ms,
rgrover1	717:11b41f651697	632	* then the controller will scan for 10 percent of the time. It is possible
rgrover1	717:11b41f651697	633	* to have the interval and window set to the same value. In this case,
rgrover1	717:11b41f651697	634	* scanning is continuous, with a change of scanning frequency once every
rgrover1	717:11b41f651697	635	* interval.
rgrover1	717:11b41f651697	636	*
rgrover1	717:11b41f651697	637	* Once the scanning parameters have been configured, scanning can be
rgrover1	717:11b41f651697	638	* enabled by using startScan().
rgrover1	717:11b41f651697	639	*
rgrover1	717:11b41f651697	640	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	641	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	642	* ble.setScanWindow(window) should be replaced with
rgrover1	717:11b41f651697	643	* ble.gap().setScanWindow(window).
rgrover1	717:11b41f651697	644	*/
rgrover1	717:11b41f651697	645	ble_error_t setScanWindow(uint16_t window) {
rgrover1	717:11b41f651697	646	return gap().setScanWindow(window);
rgrover1	717:11b41f651697	647	}
rgrover1	717:11b41f651697	648
rgrover1	717:11b41f651697	649	/**
vcoubard	1049:efb29faf12fc	650	* Set up parameters for GAP scanning (observer mode).
rgrover1	717:11b41f651697	651	* @param[in] timeout
vcoubard	1049:efb29faf12fc	652	* Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
rgrover1	717:11b41f651697	653	*
rgrover1	717:11b41f651697	654	* The scanning window divided by the interval determines the duty cycle for
rgrover1	717:11b41f651697	655	* scanning. For example, if the interval is 100ms and the window is 10ms,
rgrover1	717:11b41f651697	656	* then the controller will scan for 10 percent of the time. It is possible
rgrover1	717:11b41f651697	657	* to have the interval and window set to the same value. In this case,
rgrover1	717:11b41f651697	658	* scanning is continuous, with a change of scanning frequency once every
rgrover1	717:11b41f651697	659	* interval.
rgrover1	717:11b41f651697	660	*
rgrover1	717:11b41f651697	661	* Once the scanning parameters have been configured, scanning can be
rgrover1	717:11b41f651697	662	* enabled by using startScan().
rgrover1	717:11b41f651697	663	*
rgrover1	717:11b41f651697	664	* @Note: The scan interval and window are recommendations to the BLE stack.
rgrover1	717:11b41f651697	665	*
rgrover1	717:11b41f651697	666	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	667	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	668	* ble.setScanTimeout(...) should be replaced with
rgrover1	717:11b41f651697	669	* ble.gap().setScanTimeout(...).
rgrover1	717:11b41f651697	670	*/
rgrover1	717:11b41f651697	671	ble_error_t setScanTimeout(uint16_t timeout) {
rgrover1	717:11b41f651697	672	return gap().setScanTimeout(timeout);
rgrover1	717:11b41f651697	673	}
rgrover1	717:11b41f651697	674
rgrover1	717:11b41f651697	675	/**
vcoubard	1049:efb29faf12fc	676	* Set up parameters for GAP scanning (observer mode).
rgrover1	717:11b41f651697	677	* @param[in] activeScanning
rgrover1	717:11b41f651697	678	* Set to True if active-scanning is required. This is used to fetch the
rgrover1	717:11b41f651697	679	* scan response from a peer if possible.
rgrover1	717:11b41f651697	680	*
rgrover1	717:11b41f651697	681	* Once the scanning parameters have been configured, scanning can be
rgrover1	717:11b41f651697	682	* enabled by using startScan().
rgrover1	717:11b41f651697	683	*
rgrover1	717:11b41f651697	684	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	685	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	686	* ble.setActiveScan(...) should be replaced with
rgrover1	717:11b41f651697	687	* ble.gap().setActiveScanning(...).
rgrover1	717:11b41f651697	688	*/
rgrover1	717:11b41f651697	689	void setActiveScan(bool activeScanning) {
rgrover1	717:11b41f651697	690	gap().setActiveScanning(activeScanning);
rgrover1	717:11b41f651697	691	}
rgrover1	717:11b41f651697	692
rgrover1	717:11b41f651697	693	/**
rgrover1	717:11b41f651697	694	* Start scanning (Observer Procedure) based on the parameters currently in
rgrover1	717:11b41f651697	695	* effect.
rgrover1	717:11b41f651697	696	*
rgrover1	717:11b41f651697	697	* @param[in] callback
vcoubard	1049:efb29faf12fc	698	* The application-specific callback to be invoked upon
rgrover1	717:11b41f651697	699	* receiving every advertisement report. This can be passed in
rgrover1	717:11b41f651697	700	* as NULL, in which case scanning may not be enabled at all.
rgrover1	717:11b41f651697	701	*
rgrover1	717:11b41f651697	702	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	703	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	704	* ble.startScan(callback) should be replaced with
rgrover1	717:11b41f651697	705	* ble.gap().startScan(callback).
rgrover1	717:11b41f651697	706	*/
rgrover1	717:11b41f651697	707	ble_error_t startScan(void (callback)(const Gap::AdvertisementCallbackParams_t params)) {
rgrover1	717:11b41f651697	708	return gap().startScan(callback);
rgrover1	717:11b41f651697	709	}
rgrover1	717:11b41f651697	710
rgrover1	717:11b41f651697	711	/**
rgrover1	717:11b41f651697	712	* Same as above, but this takes an (object, method) pair for a callback.
rgrover1	717:11b41f651697	713	*
rgrover1	717:11b41f651697	714	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	715	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	716	* ble.startScan(callback) should be replaced with
rgrover1	717:11b41f651697	717	* ble.gap().startScan(object, callback).
rgrover1	717:11b41f651697	718	*/
rgrover1	717:11b41f651697	719	template<typename T>
rgrover1	717:11b41f651697	720	ble_error_t startScan(T object, void (T::memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
rgrover1	717:11b41f651697	721
rgrover1	717:11b41f651697	722	/**
rgrover1	717:11b41f651697	723	* Stop scanning. The current scanning parameters remain in effect.
rgrover1	717:11b41f651697	724	*
rgrover1	717:11b41f651697	725	* @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
rgrover1	717:11b41f651697	726	*
rgrover1	717:11b41f651697	727	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	728	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	729	* ble.stopScan() should be replaced with
rgrover1	717:11b41f651697	730	* ble.gap().stopScan().
rgrover1	717:11b41f651697	731	*/
rgrover1	717:11b41f651697	732	ble_error_t stopScan(void) {
rgrover1	717:11b41f651697	733	return gap().stopScan();
rgrover1	717:11b41f651697	734	}
rgrover1	717:11b41f651697	735
rgrover1	717:11b41f651697	736	/**
rgrover1	717:11b41f651697	737	* Create a connection (GAP Link Establishment).
rgrover1	717:11b41f651697	738	* @param peerAddr
rgrover1	717:11b41f651697	739	* 48-bit address, LSB format.
rgrover1	717:11b41f651697	740	* @param peerAddrType
rgrover1	717:11b41f651697	741	* Address type of the peer.
rgrover1	717:11b41f651697	742	* @param connectionParams
rgrover1	717:11b41f651697	743	* Connection parameters.
rgrover1	717:11b41f651697	744	* @param scanParams
vcoubard	1049:efb29faf12fc	745	* Paramters to use while scanning for the peer.
rgrover1	717:11b41f651697	746	* @return BLE_ERROR_NONE if connection establishment procedure is started
vcoubard	1049:efb29faf12fc	747	* successfully. The onConnection callback (if set) is invoked upon
rgrover1	717:11b41f651697	748	* a connection event.
rgrover1	717:11b41f651697	749	*
rgrover1	717:11b41f651697	750	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	751	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	752	* ble.connect(...) should be replaced with
rgrover1	717:11b41f651697	753	* ble.gap().connect(...).
rgrover1	717:11b41f651697	754	*/
vcoubard	1116:82d4a8a56d91	755	ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
vcoubard	1079:79c089630b38	756	BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
rgrover1	717:11b41f651697	757	const Gap::ConnectionParams_t *connectionParams = NULL,
rgrover1	717:11b41f651697	758	const GapScanningParams *scanParams = NULL) {
rgrover1	717:11b41f651697	759	return gap().connect(peerAddr, peerAddrType, connectionParams, scanParams);
rgrover1	717:11b41f651697	760	}
rgrover1	717:11b41f651697	761
rgrover1	717:11b41f651697	762	/**
vcoubard	1049:efb29faf12fc	763	* This call initiates the disconnection procedure, and its completion is
vcoubard	1049:efb29faf12fc	764	* communicated to the application with an invocation of the
rgrover1	717:11b41f651697	765	* onDisconnection callback.
rgrover1	717:11b41f651697	766	*
rgrover1	717:11b41f651697	767	* @param[in] connectionHandle
rgrover1	717:11b41f651697	768	* @param[in] reason
vcoubard	1049:efb29faf12fc	769	* The reason for disconnection; sent back to the peer.
rgrover1	717:11b41f651697	770	*/
rgrover1	717:11b41f651697	771	ble_error_t disconnect(Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason) {
rgrover1	717:11b41f651697	772	return gap().disconnect(connectionHandle, reason);
rgrover1	717:11b41f651697	773	}
rgrover1	717:11b41f651697	774
rgrover1	717:11b41f651697	775	/**
vcoubard	1079:79c089630b38	776	* This call initiates the disconnection procedure, and its completion
vcoubard	1049:efb29faf12fc	777	* is communicated to the application with an invocation of the
rgrover1	717:11b41f651697	778	* onDisconnection callback.
rgrover1	717:11b41f651697	779	*
rgrover1	717:11b41f651697	780	* @param reason
vcoubard	1049:efb29faf12fc	781	* The reason for disconnection; sent back to the peer.
rgrover1	717:11b41f651697	782	*
rgrover1	717:11b41f651697	783	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	784	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	785	* ble.disconnect(reason) should be replaced with
rgrover1	717:11b41f651697	786	* ble.gap().disconnect(reason).
rgrover1	717:11b41f651697	787	*
vcoubard	1049:efb29faf12fc	788	* @note: This version of disconnect() doesn't take a connection handle. It
vcoubard	1049:efb29faf12fc	789	* works reliably only for stacks that are limited to a single
rgrover1	717:11b41f651697	790	* connection. This API should be considered deprecated in favour of the
vcoubard	1049:efb29faf12fc	791	* alternative, which takes a connection handle. It will be dropped in the future.
rgrover1	717:11b41f651697	792	*/
rgrover1	717:11b41f651697	793	ble_error_t disconnect(Gap::DisconnectionReason_t reason) {
rgrover1	717:11b41f651697	794	return gap().disconnect(reason);
rgrover1	717:11b41f651697	795	}
rgrover1	717:11b41f651697	796
rgrover1	717:11b41f651697	797	/**
vcoubard	1049:efb29faf12fc	798	* Returns the current GAP state of the device using a bitmask that
vcoubard	1049:efb29faf12fc	799	* describes whether the device is advertising or connected.
rgrover1	717:11b41f651697	800	*
rgrover1	717:11b41f651697	801	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	802	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	803	* ble.getGapState() should be replaced with
rgrover1	717:11b41f651697	804	* ble.gap().getState().
rgrover1	717:11b41f651697	805	*/
rgrover1	717:11b41f651697	806	Gap::GapState_t getGapState(void) const {
rgrover1	717:11b41f651697	807	return gap().getState();
rgrover1	717:11b41f651697	808	}
rgrover1	717:11b41f651697	809
rgrover1	717:11b41f651697	810	/**
vcoubard	1049:efb29faf12fc	811	* Get the GAP peripheral's preferred connection parameters. These are the
rgrover1	717:11b41f651697	812	* defaults that the peripheral would like to have in a connection. The
rgrover1	717:11b41f651697	813	* choice of the connection parameters is eventually up to the central.
rgrover1	717:11b41f651697	814	*
rgrover1	717:11b41f651697	815	* @param[out] params
rgrover1	717:11b41f651697	816	* The structure where the parameters will be stored. Memory
rgrover1	717:11b41f651697	817	* for this is owned by the caller.
rgrover1	717:11b41f651697	818	*
rgrover1	717:11b41f651697	819	* @return BLE_ERROR_NONE if the parameters were successfully filled into
rgrover1	717:11b41f651697	820	* the given structure pointed to by params.
rgrover1	717:11b41f651697	821	*
rgrover1	717:11b41f651697	822	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	823	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	824	* ble.getPreferredConnectionParams() should be replaced with
rgrover1	717:11b41f651697	825	* ble.gap().getPreferredConnectionParams().
rgrover1	717:11b41f651697	826	*/
rgrover1	717:11b41f651697	827	ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) {
rgrover1	717:11b41f651697	828	return gap().getPreferredConnectionParams(params);
rgrover1	717:11b41f651697	829	}
rgrover1	717:11b41f651697	830
rgrover1	717:11b41f651697	831	/**
vcoubard	1049:efb29faf12fc	832	* Set the GAP peripheral's preferred connection parameters. These are the
rgrover1	717:11b41f651697	833	* defaults that the peripheral would like to have in a connection. The
rgrover1	717:11b41f651697	834	* choice of the connection parameters is eventually up to the central.
rgrover1	717:11b41f651697	835	*
rgrover1	717:11b41f651697	836	* @param[in] params
rgrover1	717:11b41f651697	837	* The structure containing the desired parameters.
rgrover1	717:11b41f651697	838	*
rgrover1	717:11b41f651697	839	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	840	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	841	* ble.setPreferredConnectionParams() should be replaced with
rgrover1	717:11b41f651697	842	* ble.gap().setPreferredConnectionParams().
rgrover1	717:11b41f651697	843	*/
rgrover1	717:11b41f651697	844	ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) {
rgrover1	717:11b41f651697	845	return gap().setPreferredConnectionParams(params);
rgrover1	717:11b41f651697	846	}
rgrover1	717:11b41f651697	847
rgrover1	717:11b41f651697	848	/**
rgrover1	717:11b41f651697	849	* Update connection parameters while in the peripheral role.
rgrover1	717:11b41f651697	850	* @details In the peripheral role, this will send the corresponding L2CAP request to the connected peer and wait for
rgrover1	717:11b41f651697	851	* the central to perform the procedure.
rgrover1	717:11b41f651697	852	* @param[in] handle
rgrover1	717:11b41f651697	853	* Connection Handle
rgrover1	717:11b41f651697	854	* @param[in] params
rgrover1	717:11b41f651697	855	* Pointer to desired connection parameters. If NULL is provided on a peripheral role,
rgrover1	717:11b41f651697	856	* the parameters in the PPCP characteristic of the GAP service will be used instead.
rgrover1	717:11b41f651697	857	*
rgrover1	717:11b41f651697	858	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	859	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	860	* ble.updateConnectionParams() should be replaced with
rgrover1	717:11b41f651697	861	* ble.gap().updateConnectionParams().
rgrover1	717:11b41f651697	862	*/
rgrover1	717:11b41f651697	863	ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
rgrover1	717:11b41f651697	864	return gap().updateConnectionParams(handle, params);
rgrover1	717:11b41f651697	865	}
rgrover1	717:11b41f651697	866
rgrover1	717:11b41f651697	867	/**
rgrover1	717:11b41f651697	868	* Set the device name characteristic in the GAP service.
rgrover1	717:11b41f651697	869	* @param[in] deviceName
rgrover1	717:11b41f651697	870	* The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
rgrover1	717:11b41f651697	871	*
rgrover1	717:11b41f651697	872	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	873	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	874	* ble.setDeviceName() should be replaced with
rgrover1	717:11b41f651697	875	* ble.gap().setDeviceName().
rgrover1	717:11b41f651697	876	*/
rgrover1	717:11b41f651697	877	ble_error_t setDeviceName(const uint8_t *deviceName) {
rgrover1	717:11b41f651697	878	return gap().setDeviceName(deviceName);
rgrover1	717:11b41f651697	879	}
rgrover1	717:11b41f651697	880
rgrover1	717:11b41f651697	881	/**
rgrover1	717:11b41f651697	882	* Get the value of the device name characteristic in the GAP service.
rgrover1	717:11b41f651697	883	* @param[out] deviceName
rgrover1	717:11b41f651697	884	* Pointer to an empty buffer where the UTF-8 *non NULL-
rgrover1	717:11b41f651697	885	* terminated* string will be placed. Set this
rgrover1	717:11b41f651697	886	* value to NULL in order to obtain the deviceName-length
rgrover1	717:11b41f651697	887	* from the 'length' parameter.
rgrover1	717:11b41f651697	888	*
rgrover1	717:11b41f651697	889	* @param[in/out] lengthP
rgrover1	717:11b41f651697	890	* (on input) Length of the buffer pointed to by deviceName;
rgrover1	717:11b41f651697	891	* (on output) the complete device name length (without the
rgrover1	717:11b41f651697	892	* null terminator).
rgrover1	717:11b41f651697	893	*
rgrover1	717:11b41f651697	894	* @note If the device name is longer than the size of the supplied buffer,
rgrover1	717:11b41f651697	895	* length will return the complete device name length, and not the
rgrover1	717:11b41f651697	896	* number of bytes actually returned in deviceName. The application may
rgrover1	717:11b41f651697	897	* use this information to retry with a suitable buffer size.
rgrover1	717:11b41f651697	898	*
rgrover1	717:11b41f651697	899	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	900	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	901	* ble.getDeviceName() should be replaced with
rgrover1	717:11b41f651697	902	* ble.gap().getDeviceName().
rgrover1	717:11b41f651697	903	*/
rgrover1	717:11b41f651697	904	ble_error_t getDeviceName(uint8_t deviceName, unsigned lengthP) {
rgrover1	717:11b41f651697	905	return gap().getDeviceName(deviceName, lengthP);
rgrover1	717:11b41f651697	906	}
rgrover1	717:11b41f651697	907
rgrover1	717:11b41f651697	908	/**
rgrover1	717:11b41f651697	909	* Set the appearance characteristic in the GAP service.
rgrover1	717:11b41f651697	910	* @param[in] appearance
rgrover1	717:11b41f651697	911	* The new value for the device-appearance.
rgrover1	717:11b41f651697	912	*
rgrover1	717:11b41f651697	913	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	914	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	915	* ble.setAppearance() should be replaced with
rgrover1	717:11b41f651697	916	* ble.gap().setAppearance().
rgrover1	717:11b41f651697	917	*/
rgrover1	717:11b41f651697	918	ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
rgrover1	717:11b41f651697	919	return gap().setAppearance(appearance);
rgrover1	717:11b41f651697	920	}
rgrover1	717:11b41f651697	921
rgrover1	717:11b41f651697	922	/**
rgrover1	717:11b41f651697	923	* Get the appearance characteristic in the GAP service.
rgrover1	717:11b41f651697	924	* @param[out] appearance
rgrover1	717:11b41f651697	925	* The new value for the device-appearance.
rgrover1	717:11b41f651697	926	*
rgrover1	717:11b41f651697	927	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	928	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	929	* ble.getAppearance() should be replaced with
rgrover1	717:11b41f651697	930	* ble.gap().getAppearance().
rgrover1	717:11b41f651697	931	*/
rgrover1	717:11b41f651697	932	ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
rgrover1	717:11b41f651697	933	return gap().getAppearance(appearanceP);
rgrover1	717:11b41f651697	934	}
rgrover1	717:11b41f651697	935
rgrover1	717:11b41f651697	936	/**
rgrover1	717:11b41f651697	937	* Set the radio's transmit power.
rgrover1	717:11b41f651697	938	* @param[in] txPower Radio transmit power in dBm.
rgrover1	717:11b41f651697	939	*
rgrover1	717:11b41f651697	940	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	941	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	942	* ble.setTxPower() should be replaced with
rgrover1	717:11b41f651697	943	* ble.gap().setTxPower().
rgrover1	717:11b41f651697	944	*/
rgrover1	717:11b41f651697	945	ble_error_t setTxPower(int8_t txPower) {
rgrover1	717:11b41f651697	946	return gap().setTxPower(txPower);
rgrover1	717:11b41f651697	947	}
rgrover1	717:11b41f651697	948
rgrover1	717:11b41f651697	949	/**
rgrover1	717:11b41f651697	950	* Query the underlying stack for permitted arguments for setTxPower().
rgrover1	717:11b41f651697	951	*
rgrover1	717:11b41f651697	952	* @param[out] valueArrayPP
rgrover1	717:11b41f651697	953	* Out parameter to receive the immutable array of Tx values.
rgrover1	717:11b41f651697	954	* @param[out] countP
rgrover1	717:11b41f651697	955	* Out parameter to receive the array's size.
rgrover1	717:11b41f651697	956	*
rgrover1	717:11b41f651697	957	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	958	* You should use the parallel API from Gap directly. A former call to
rgrover1	717:11b41f651697	959	* ble.getPermittedTxPowerValues() should be replaced with
rgrover1	717:11b41f651697	960	* ble.gap().getPermittedTxPowerValues().
rgrover1	717:11b41f651697	961	*/
rgrover1	717:11b41f651697	962	void getPermittedTxPowerValues(const int8_t *valueArrayPP, size_t countP) {
rgrover1	717:11b41f651697	963	gap().getPermittedTxPowerValues(valueArrayPP, countP);
rgrover1	717:11b41f651697	964	}
rgrover1	717:11b41f651697	965
rgrover1	717:11b41f651697	966	/**
rgrover1	717:11b41f651697	967	* Add a service declaration to the local server ATT table. Also add the
rgrover1	717:11b41f651697	968	* characteristics contained within.
rgrover1	717:11b41f651697	969	*
rgrover1	717:11b41f651697	970	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	971	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	972	* to ble.addService() should be replaced with
rgrover1	717:11b41f651697	973	* ble.gattServer().addService().
rgrover1	717:11b41f651697	974	*/
rgrover1	717:11b41f651697	975	ble_error_t addService(GattService &service) {
rgrover1	717:11b41f651697	976	return gattServer().addService(service);
rgrover1	717:11b41f651697	977	}
rgrover1	717:11b41f651697	978
rgrover1	717:11b41f651697	979	/**
vcoubard	1049:efb29faf12fc	980	* Read the value of a characteristic from the local GattServer.
rgrover1	717:11b41f651697	981	* @param[in] attributeHandle
rgrover1	717:11b41f651697	982	* Attribute handle for the value attribute of the characteristic.
rgrover1	717:11b41f651697	983	* @param[out] buffer
rgrover1	717:11b41f651697	984	* A buffer to hold the value being read.
rgrover1	717:11b41f651697	985	* @param[in/out] lengthP
rgrover1	717:11b41f651697	986	* Length of the buffer being supplied. If the attribute
rgrover1	717:11b41f651697	987	* value is longer than the size of the supplied buffer,
vcoubard	1049:efb29faf12fc	988	* this variable will return the total attribute value length
rgrover1	717:11b41f651697	989	* (excluding offset). The application may use this
rgrover1	717:11b41f651697	990	* information to allocate a suitable buffer size.
rgrover1	717:11b41f651697	991	*
rgrover1	717:11b41f651697	992	* @return BLE_ERROR_NONE if a value was read successfully into the buffer.
rgrover1	717:11b41f651697	993	*
rgrover1	717:11b41f651697	994	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	995	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	996	* to ble.readCharacteristicValue() should be replaced with
rgrover1	717:11b41f651697	997	* ble.gattServer().read().
rgrover1	717:11b41f651697	998	*/
rgrover1	717:11b41f651697	999	ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t buffer, uint16_t lengthP) {
rgrover1	717:11b41f651697	1000	return gattServer().read(attributeHandle, buffer, lengthP);
rgrover1	717:11b41f651697	1001	}
rgrover1	717:11b41f651697	1002
rgrover1	717:11b41f651697	1003	/**
vcoubard	1049:efb29faf12fc	1004	* Read the value of a characteristic from the local GattServer.
rgrover1	717:11b41f651697	1005	* @param[in] connectionHandle
rgrover1	717:11b41f651697	1006	* Connection Handle.
rgrover1	717:11b41f651697	1007	* @param[in] attributeHandle
rgrover1	717:11b41f651697	1008	* Attribute handle for the value attribute of the characteristic.
rgrover1	717:11b41f651697	1009	* @param[out] buffer
rgrover1	717:11b41f651697	1010	* A buffer to hold the value being read.
rgrover1	717:11b41f651697	1011	* @param[in/out] lengthP
rgrover1	717:11b41f651697	1012	* Length of the buffer being supplied. If the attribute
rgrover1	717:11b41f651697	1013	* value is longer than the size of the supplied buffer,
vcoubard	1049:efb29faf12fc	1014	* this variable will return the total attribute value length
rgrover1	717:11b41f651697	1015	* (excluding offset). The application may use this
rgrover1	717:11b41f651697	1016	* information to allocate a suitable buffer size.
rgrover1	717:11b41f651697	1017	*
rgrover1	717:11b41f651697	1018	* @return BLE_ERROR_NONE if a value was read successfully into the buffer.
rgrover1	717:11b41f651697	1019	*
vcoubard	1049:efb29faf12fc	1020	* @note This API is a version of the above, with an additional connection handle
rgrover1	717:11b41f651697	1021	* parameter to allow fetches for connection-specific multivalued
rgrover1	734:718a3566b4ce	1022	* attributes (such as the CCCDs).
rgrover1	717:11b41f651697	1023	*
rgrover1	717:11b41f651697	1024	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1025	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	1026	* to ble.readCharacteristicValue() should be replaced with
rgrover1	717:11b41f651697	1027	* ble.gattServer().read().
rgrover1	717:11b41f651697	1028	*/
rgrover1	717:11b41f651697	1029	ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t buffer, uint16_t lengthP) {
rgrover1	717:11b41f651697	1030	return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP);
rgrover1	717:11b41f651697	1031	}
rgrover1	717:11b41f651697	1032
rgrover1	717:11b41f651697	1033	/**
rgrover1	717:11b41f651697	1034	* Update the value of a characteristic on the local GattServer.
rgrover1	717:11b41f651697	1035	*
rgrover1	717:11b41f651697	1036	* @param[in] attributeHandle
vcoubard	1049:efb29faf12fc	1037	* Handle for the value attribute of the characteristic.
rgrover1	717:11b41f651697	1038	* @param[in] value
vcoubard	1049:efb29faf12fc	1039	* A pointer to a buffer holding the new value.
rgrover1	717:11b41f651697	1040	* @param[in] size
rgrover1	717:11b41f651697	1041	* Size of the new value (in bytes).
rgrover1	717:11b41f651697	1042	* @param[in] localOnly
rgrover1	717:11b41f651697	1043	* Should this update be kept on the local
rgrover1	717:11b41f651697	1044	* GattServer regardless of the state of the
rgrover1	717:11b41f651697	1045	* notify/indicate flag in the CCCD for this
vcoubard	1049:efb29faf12fc	1046	* characteristic? If set to true, no notification
rgrover1	717:11b41f651697	1047	* or indication is generated.
rgrover1	717:11b41f651697	1048	*
rgrover1	717:11b41f651697	1049	* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
rgrover1	717:11b41f651697	1050	*
rgrover1	717:11b41f651697	1051	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1052	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	1053	* to ble.updateCharacteristicValue() should be replaced with
rgrover1	717:11b41f651697	1054	* ble.gattServer().write().
rgrover1	717:11b41f651697	1055	*/
rgrover1	717:11b41f651697	1056	ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle,
rgrover1	717:11b41f651697	1057	const uint8_t *value,
rgrover1	717:11b41f651697	1058	uint16_t size,
rgrover1	717:11b41f651697	1059	bool localOnly = false) {
rgrover1	717:11b41f651697	1060	return gattServer().write(attributeHandle, value, size, localOnly);
rgrover1	717:11b41f651697	1061	}
rgrover1	717:11b41f651697	1062
rgrover1	717:11b41f651697	1063	/**
rgrover1	717:11b41f651697	1064	* Update the value of a characteristic on the local GattServer. A version
vcoubard	1049:efb29faf12fc	1065	* of the above, with a connection handle parameter to allow updates
rgrover1	734:718a3566b4ce	1066	* for connection-specific multivalued attributes (such as the CCCDs).
rgrover1	717:11b41f651697	1067	*
rgrover1	717:11b41f651697	1068	* @param[in] connectionHandle
rgrover1	717:11b41f651697	1069	* Connection Handle.
rgrover1	717:11b41f651697	1070	* @param[in] attributeHandle
rgrover1	717:11b41f651697	1071	* Handle for the value attribute of the Characteristic.
rgrover1	717:11b41f651697	1072	* @param[in] value
vcoubard	1049:efb29faf12fc	1073	* A pointer to a buffer holding the new value.
rgrover1	717:11b41f651697	1074	* @param[in] size
rgrover1	717:11b41f651697	1075	* Size of the new value (in bytes).
rgrover1	717:11b41f651697	1076	* @param[in] localOnly
rgrover1	717:11b41f651697	1077	* Should this update be kept on the local
rgrover1	717:11b41f651697	1078	* GattServer regardless of the state of the
rgrover1	717:11b41f651697	1079	* notify/indicate flag in the CCCD for this
rgrover1	717:11b41f651697	1080	* Characteristic? If set to true, no notification
rgrover1	717:11b41f651697	1081	* or indication is generated.
rgrover1	717:11b41f651697	1082	*
rgrover1	717:11b41f651697	1083	* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
rgrover1	717:11b41f651697	1084	*
rgrover1	717:11b41f651697	1085	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1086	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	1087	* to ble.updateCharacteristicValue() should be replaced with
rgrover1	717:11b41f651697	1088	* ble.gattServer().write().
rgrover1	717:11b41f651697	1089	*/
rgrover1	717:11b41f651697	1090	ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle,
rgrover1	717:11b41f651697	1091	GattAttribute::Handle_t attributeHandle,
rgrover1	717:11b41f651697	1092	const uint8_t *value,
rgrover1	717:11b41f651697	1093	uint16_t size,
rgrover1	717:11b41f651697	1094	bool localOnly = false) {
rgrover1	717:11b41f651697	1095	return gattServer().write(connectionHandle, attributeHandle, value, size, localOnly);
rgrover1	717:11b41f651697	1096	}
rgrover1	717:11b41f651697	1097
rgrover1	717:11b41f651697	1098	/**
rgrover1	717:11b41f651697	1099	* Enable the BLE stack's Security Manager. The Security Manager implements
vcoubard	1049:efb29faf12fc	1100	* the cryptographic algorithms and protocol exchanges that allow two
rgrover1	717:11b41f651697	1101	* devices to securely exchange data and privately detect each other.
rgrover1	717:11b41f651697	1102	* Calling this API is a prerequisite for encryption and pairing (bonding).
rgrover1	717:11b41f651697	1103	*
rgrover1	717:11b41f651697	1104	* @param[in] enableBonding Allow for bonding.
vcoubard	1049:efb29faf12fc	1105	* @param[in] requireMITM Require protection against man-in-the-middle attacks.
vcoubard	1049:efb29faf12fc	1106	* @param[in] iocaps To specify the I/O capabilities of this peripheral,
vcoubard	1049:efb29faf12fc	1107	* such as availability of a display or keyboard, to
rgrover1	717:11b41f651697	1108	* support out-of-band exchanges of security data.
rgrover1	717:11b41f651697	1109	* @param[in] passkey To specify a static passkey.
rgrover1	717:11b41f651697	1110	*
rgrover1	717:11b41f651697	1111	* @return BLE_ERROR_NONE on success.
rgrover1	717:11b41f651697	1112	*
rgrover1	717:11b41f651697	1113	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1114	* You should use the parallel API from SecurityManager directly. A former
rgrover1	717:11b41f651697	1115	* call to ble.initializeSecurity(...) should be replaced with
rgrover1	717:11b41f651697	1116	* ble.securityManager().init(...).
rgrover1	717:11b41f651697	1117	*/
rgrover1	717:11b41f651697	1118	ble_error_t initializeSecurity(bool enableBonding = true,
rgrover1	717:11b41f651697	1119	bool requireMITM = true,
rgrover1	717:11b41f651697	1120	SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE,
rgrover1	717:11b41f651697	1121	const SecurityManager::Passkey_t passkey = NULL) {
rgrover1	717:11b41f651697	1122	return securityManager().init(enableBonding, requireMITM, iocaps, passkey);
rgrover1	717:11b41f651697	1123	}
rgrover1	717:11b41f651697	1124
rgrover1	717:11b41f651697	1125	/**
rgrover1	717:11b41f651697	1126	* Get the security status of a connection.
rgrover1	717:11b41f651697	1127	*
rgrover1	717:11b41f651697	1128	* @param[in] connectionHandle Handle to identify the connection.
vcoubard	1049:efb29faf12fc	1129	* @param[out] securityStatusP Security status.
rgrover1	717:11b41f651697	1130	*
vcoubard	1049:efb29faf12fc	1131	* @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
rgrover1	717:11b41f651697	1132	*
rgrover1	717:11b41f651697	1133	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1134	* You should use the parallel API from SecurityManager directly. A former
rgrover1	717:11b41f651697	1135	* call to ble.getLinkSecurity(...) should be replaced with
rgrover1	717:11b41f651697	1136	* ble.securityManager().getLinkSecurity(...).
rgrover1	717:11b41f651697	1137	*/
rgrover1	717:11b41f651697	1138	ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) {
rgrover1	717:11b41f651697	1139	return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
rgrover1	717:11b41f651697	1140	}
rgrover1	717:11b41f651697	1141
rgrover1	717:11b41f651697	1142	/**
rgrover1	717:11b41f651697	1143	* Delete all peer device context and all related bonding information from
rgrover1	717:11b41f651697	1144	* the database within the security manager.
rgrover1	717:11b41f651697	1145	*
vcoubard	1049:efb29faf12fc	1146	* @retval BLE_ERROR_NONE On success; else returns an error code indicating the reason for the failure.
vcoubard	1049:efb29faf12fc	1147	* @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
rgrover1	717:11b41f651697	1148	* application registration.
rgrover1	717:11b41f651697	1149	*
rgrover1	717:11b41f651697	1150	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1151	* You should use the parallel API from SecurityManager directly. A former
rgrover1	717:11b41f651697	1152	* call to ble.purgeAllBondingState() should be replaced with
rgrover1	717:11b41f651697	1153	* ble.securityManager().purgeAllBondingState().
rgrover1	717:11b41f651697	1154	*/
rgrover1	717:11b41f651697	1155	ble_error_t purgeAllBondingState(void) {
rgrover1	717:11b41f651697	1156	return securityManager().purgeAllBondingState();
rgrover1	717:11b41f651697	1157	}
rgrover1	717:11b41f651697	1158
rgrover1	717:11b41f651697	1159	/**
vcoubard	1049:efb29faf12fc	1160	* Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
rgrover1	717:11b41f651697	1161	* possible event types.
rgrover1	717:11b41f651697	1162	*
rgrover1	717:11b41f651697	1163	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	752:868b6dd7a6bf	1164	* You should use the parallel API from Gap directly. A former call
rgrover1	717:11b41f651697	1165	* to ble.onTimeout(callback) should be replaced with
rgrover1	717:11b41f651697	1166	* ble.gap().onTimeout(callback).
rgrover1	717:11b41f651697	1167	*/
rgrover1	717:11b41f651697	1168	void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) {
rgrover1	717:11b41f651697	1169	gap().onTimeout(timeoutCallback);
rgrover1	717:11b41f651697	1170	}
rgrover1	717:11b41f651697	1171
rgrover1	717:11b41f651697	1172	/**
vcoubard	1049:efb29faf12fc	1173	* Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
rgrover1	717:11b41f651697	1174	*
rgrover1	717:11b41f651697	1175	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	752:868b6dd7a6bf	1176	* You should use the parallel API from Gap directly. A former call
rgrover1	717:11b41f651697	1177	* to ble.onConnection(callback) should be replaced with
rgrover1	717:11b41f651697	1178	* ble.gap().onConnection(callback).
rgrover1	717:11b41f651697	1179	*/
rgrover1	717:11b41f651697	1180	void onConnection(Gap::ConnectionEventCallback_t connectionCallback) {
rgrover1	717:11b41f651697	1181	gap().onConnection(connectionCallback);
rgrover1	717:11b41f651697	1182	}
rgrover1	717:11b41f651697	1183
rgrover1	717:11b41f651697	1184	/**
rgrover1	830:9072de50087b	1185	* Append to a chain of callbacks to be invoked upon GAP disconnection.
rgrover1	717:11b41f651697	1186	*
rgrover1	717:11b41f651697	1187	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	752:868b6dd7a6bf	1188	* You should use the parallel API from Gap directly. A former call
rgrover1	717:11b41f651697	1189	* to ble.onDisconnection(callback) should be replaced with
rgrover1	717:11b41f651697	1190	* ble.gap().onDisconnection(callback).
rgrover1	717:11b41f651697	1191	*/
rgrover1	717:11b41f651697	1192	void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) {
rgrover1	717:11b41f651697	1193	gap().onDisconnection(disconnectionCallback);
rgrover1	717:11b41f651697	1194	}
rgrover1	717:11b41f651697	1195
rgrover1	717:11b41f651697	1196	template<typename T>
rgrover1	830:9072de50087b	1197	void onDisconnection(T tptr, void (T::mptr)(const Gap::DisconnectionCallbackParams_t*)) {
rgrover1	830:9072de50087b	1198	gap().onDisconnection(tptr, mptr);
rgrover1	717:11b41f651697	1199	}
rgrover1	717:11b41f651697	1200
rgrover1	717:11b41f651697	1201	/**
rgrover1	717:11b41f651697	1202	* Radio Notification is a feature that enables ACTIVE and INACTIVE
vcoubard	1049:efb29faf12fc	1203	* (nACTIVE) signals from the stack. These notify the application when the
rgrover1	717:11b41f651697	1204	* radio is in use. The signal is sent using software interrupt.
rgrover1	717:11b41f651697	1205	*
vcoubard	1049:efb29faf12fc	1206	* The ACTIVE signal is sent before the radio event starts. The nACTIVE
vcoubard	1049:efb29faf12fc	1207	* signal is sent at the end of the radio event. These signals can be used
rgrover1	717:11b41f651697	1208	* by the application programmer to synchronize application logic with radio
rgrover1	717:11b41f651697	1209	* activity. For example, the ACTIVE signal can be used to shut off external
rgrover1	717:11b41f651697	1210	* devices to manage peak current drawn during periods when the radio is on,
vcoubard	1049:efb29faf12fc	1211	* or to trigger sensor data collection for transmission in the radio event.
rgrover1	717:11b41f651697	1212	*
rgrover1	717:11b41f651697	1213	* @param callback
rgrover1	717:11b41f651697	1214	* The application handler to be invoked in response to a radio
rgrover1	717:11b41f651697	1215	* ACTIVE/INACTIVE event.
rgrover1	717:11b41f651697	1216	*
rgrover1	717:11b41f651697	1217	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	752:868b6dd7a6bf	1218	* You should use the parallel API from Gap directly. A former call
rgrover1	717:11b41f651697	1219	* to ble.onRadioNotification(...) should be replaced with
rgrover1	717:11b41f651697	1220	* ble.gap().onRadioNotification(...).
rgrover1	717:11b41f651697	1221	*/
rgrover1	753:424c2ae44553	1222	void onRadioNotification(void (*callback)(bool)) {
rgrover1	717:11b41f651697	1223	gap().onRadioNotification(callback);
rgrover1	717:11b41f651697	1224	}
rgrover1	717:11b41f651697	1225
rgrover1	717:11b41f651697	1226	/**
rgrover1	717:11b41f651697	1227	* Add a callback for the GATT event DATA_SENT (which is triggered when
rgrover1	717:11b41f651697	1228	* updates are sent out by GATT in the form of notifications).
rgrover1	717:11b41f651697	1229	*
vcoubard	1049:efb29faf12fc	1230	* @Note: It is possible to chain together multiple onDataSent callbacks
rgrover1	717:11b41f651697	1231	* (potentially from different modules of an application) to receive updates
rgrover1	717:11b41f651697	1232	* to characteristics.
rgrover1	717:11b41f651697	1233	*
vcoubard	1049:efb29faf12fc	1234	* @Note: It is also possible to set up a callback into a member function of
rgrover1	717:11b41f651697	1235	* some object.
rgrover1	717:11b41f651697	1236	*
rgrover1	717:11b41f651697	1237	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1238	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	1239	* to ble.onDataSent(...) should be replaced with
rgrover1	717:11b41f651697	1240	* ble.gattServer().onDataSent(...).
rgrover1	717:11b41f651697	1241	*/
rgrover1	717:11b41f651697	1242	void onDataSent(void (*callback)(unsigned count)) {
rgrover1	717:11b41f651697	1243	gattServer().onDataSent(callback);
rgrover1	717:11b41f651697	1244	}
rgrover1	717:11b41f651697	1245	template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) {
rgrover1	717:11b41f651697	1246	gattServer().onDataSent(objPtr, memberPtr);
rgrover1	717:11b41f651697	1247	}
rgrover1	717:11b41f651697	1248
rgrover1	717:11b41f651697	1249	/**
vcoubard	1049:efb29faf12fc	1250	* Set up a callback for when an attribute has its value updated by or at the
vcoubard	1049:efb29faf12fc	1251	* connected peer. For a peripheral, this callback is triggered when the local
rgrover1	717:11b41f651697	1252	* GATT server has an attribute updated by a write command from the peer.
rgrover1	717:11b41f651697	1253	* For a Central, this callback is triggered when a response is received for
rgrover1	717:11b41f651697	1254	* a write request.
rgrover1	717:11b41f651697	1255	*
vcoubard	1049:efb29faf12fc	1256	* @Note: It is possible to chain together multiple onDataWritten callbacks
rgrover1	717:11b41f651697	1257	* (potentially from different modules of an application) to receive updates
vcoubard	1049:efb29faf12fc	1258	* to characteristics. Many services, such as DFU and UART, add their own
rgrover1	717:11b41f651697	1259	* onDataWritten callbacks behind the scenes to trap interesting events.
rgrover1	717:11b41f651697	1260	*
vcoubard	1049:efb29faf12fc	1261	* @Note: It is also possible to set up a callback into a member function of
rgrover1	717:11b41f651697	1262	* some object.
rgrover1	717:11b41f651697	1263	*
rgrover1	717:11b41f651697	1264	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1265	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	1266	* to ble.onDataWritten(...) should be replaced with
rgrover1	717:11b41f651697	1267	* ble.gattServer().onDataWritten(...).
rgrover1	717:11b41f651697	1268	*/
rgrover1	717:11b41f651697	1269	void onDataWritten(void (callback)(const GattWriteCallbackParams eventDataP)) {
rgrover1	717:11b41f651697	1270	gattServer().onDataWritten(callback);
rgrover1	717:11b41f651697	1271	}
rgrover1	717:11b41f651697	1272	template <typename T> void onDataWritten(T * objPtr, void (T::memberPtr)(const GattWriteCallbackParams context)) {
rgrover1	717:11b41f651697	1273	gattServer().onDataWritten(objPtr, memberPtr);
rgrover1	717:11b41f651697	1274	}
rgrover1	717:11b41f651697	1275
rgrover1	717:11b41f651697	1276	/**
vcoubard	1049:efb29faf12fc	1277	* Set up a callback to be invoked on the peripheral when an attribute is
rgrover1	717:11b41f651697	1278	* being read by a remote client.
rgrover1	717:11b41f651697	1279	*
vcoubard	1049:efb29faf12fc	1280	* @Note: This functionality may not be available on all underlying stacks.
rgrover1	717:11b41f651697	1281	* You could use GattCharacteristic::setReadAuthorizationCallback() as an
rgrover1	717:11b41f651697	1282	* alternative.
rgrover1	717:11b41f651697	1283	*
vcoubard	1049:efb29faf12fc	1284	* @Note: It is possible to chain together multiple onDataRead callbacks
rgrover1	717:11b41f651697	1285	* (potentially from different modules of an application) to receive updates
rgrover1	717:11b41f651697	1286	* to characteristics. Services may add their own onDataRead callbacks
rgrover1	717:11b41f651697	1287	* behind the scenes to trap interesting events.
rgrover1	717:11b41f651697	1288	*
vcoubard	1049:efb29faf12fc	1289	* @Note: It is also possible to set up a callback into a member function of
rgrover1	717:11b41f651697	1290	* some object.
rgrover1	717:11b41f651697	1291	*
rgrover1	717:11b41f651697	1292	* @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
rgrover1	717:11b41f651697	1293	* else BLE_ERROR_NONE.
rgrover1	717:11b41f651697	1294	*
rgrover1	717:11b41f651697	1295	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1296	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	1297	* to ble.onDataRead(...) should be replaced with
rgrover1	717:11b41f651697	1298	* ble.gattServer().onDataRead(...).
rgrover1	717:11b41f651697	1299	*/
rgrover1	717:11b41f651697	1300	ble_error_t onDataRead(void (callback)(const GattReadCallbackParams eventDataP)) {
rgrover1	717:11b41f651697	1301	return gattServer().onDataRead(callback);
rgrover1	717:11b41f651697	1302	}
rgrover1	717:11b41f651697	1303	template <typename T> ble_error_t onDataRead(T * objPtr, void (T::memberPtr)(const GattReadCallbackParams context)) {
rgrover1	717:11b41f651697	1304	return gattServer().onDataRead(objPtr, memberPtr);
rgrover1	717:11b41f651697	1305	}
rgrover1	717:11b41f651697	1306
rgrover1	717:11b41f651697	1307	/**
vcoubard	1049:efb29faf12fc	1308	* Set up a callback for when notifications or indications are enabled for a
rgrover1	717:11b41f651697	1309	* characteristic on the local GattServer.
rgrover1	717:11b41f651697	1310	*
rgrover1	717:11b41f651697	1311	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1312	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	1313	* to ble.onUpdatesEnabled(callback) should be replaced with
rgrover1	717:11b41f651697	1314	* ble.gattServer().onUpdatesEnabled(callback).
rgrover1	717:11b41f651697	1315	*/
rgrover1	717:11b41f651697	1316	void onUpdatesEnabled(GattServer::EventCallback_t callback) {
rgrover1	717:11b41f651697	1317	gattServer().onUpdatesEnabled(callback);
rgrover1	717:11b41f651697	1318	}
rgrover1	717:11b41f651697	1319
rgrover1	717:11b41f651697	1320	/**
vcoubard	1049:efb29faf12fc	1321	* Set up a callback for when notifications or indications are disabled for a
rgrover1	717:11b41f651697	1322	* characteristic on the local GattServer.
rgrover1	717:11b41f651697	1323	*
rgrover1	717:11b41f651697	1324	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1325	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	1326	* to ble.onUpdatesEnabled(callback) should be replaced with
rgrover1	717:11b41f651697	1327	* ble.gattServer().onUpdatesEnabled(callback).
rgrover1	717:11b41f651697	1328	*/
rgrover1	717:11b41f651697	1329	void onUpdatesDisabled(GattServer::EventCallback_t callback) {
rgrover1	717:11b41f651697	1330	gattServer().onUpdatesDisabled(callback);
rgrover1	717:11b41f651697	1331	}
rgrover1	717:11b41f651697	1332
rgrover1	717:11b41f651697	1333	/**
vcoubard	1049:efb29faf12fc	1334	* Set up a callback for when the GATT server receives a response for an
rgrover1	717:11b41f651697	1335	* indication event sent previously.
rgrover1	717:11b41f651697	1336	*
rgrover1	717:11b41f651697	1337	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1338	* You should use the parallel API from GattServer directly. A former call
rgrover1	717:11b41f651697	1339	* to ble.onConfirmationReceived(callback) should be replaced with
rgrover1	717:11b41f651697	1340	* ble.gattServer().onConfirmationReceived(callback).
rgrover1	717:11b41f651697	1341	*/
rgrover1	717:11b41f651697	1342	void onConfirmationReceived(GattServer::EventCallback_t callback) {
rgrover1	717:11b41f651697	1343	gattServer().onConfirmationReceived(callback);
rgrover1	717:11b41f651697	1344	}
rgrover1	717:11b41f651697	1345
rgrover1	717:11b41f651697	1346	/**
vcoubard	1049:efb29faf12fc	1347	* Set up a callback for when the security setup procedure (key generation
rgrover1	717:11b41f651697	1348	* and exchange) for a link has started. This will be skipped for bonded
rgrover1	717:11b41f651697	1349	* devices. The callback is passed in parameters received from the peer's
rgrover1	717:11b41f651697	1350	* security request: bool allowBonding, bool requireMITM, and
rgrover1	717:11b41f651697	1351	* SecurityIOCapabilities_t.
rgrover1	717:11b41f651697	1352	*
rgrover1	717:11b41f651697	1353	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1354	* You should use the parallel API from SecurityManager directly. A former
rgrover1	717:11b41f651697	1355	* call to ble.onSecuritySetupInitiated(callback) should be replaced with
rgrover1	717:11b41f651697	1356	* ble.securityManager().onSecuritySetupInitiated(callback).
rgrover1	717:11b41f651697	1357	*/
rgrover1	717:11b41f651697	1358	void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
rgrover1	717:11b41f651697	1359	securityManager().onSecuritySetupInitiated(callback);
rgrover1	717:11b41f651697	1360	}
rgrover1	717:11b41f651697	1361
rgrover1	717:11b41f651697	1362	/**
vcoubard	1049:efb29faf12fc	1363	* Set up a callback for when the security setup procedure (key generation
rgrover1	717:11b41f651697	1364	* and exchange) for a link has completed. This will be skipped for bonded
rgrover1	717:11b41f651697	1365	* devices. The callback is passed in the success/failure status of the
rgrover1	717:11b41f651697	1366	* security setup procedure.
rgrover1	717:11b41f651697	1367	*
rgrover1	717:11b41f651697	1368	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1369	* You should use the parallel API from SecurityManager directly. A former
rgrover1	717:11b41f651697	1370	* call to ble.onSecuritySetupCompleted(callback) should be replaced with
rgrover1	717:11b41f651697	1371	* ble.securityManager().onSecuritySetupCompleted(callback).
rgrover1	717:11b41f651697	1372	*/
rgrover1	717:11b41f651697	1373	void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
rgrover1	717:11b41f651697	1374	securityManager().onSecuritySetupCompleted(callback);
rgrover1	717:11b41f651697	1375	}
rgrover1	717:11b41f651697	1376
rgrover1	717:11b41f651697	1377	/**
vcoubard	1049:efb29faf12fc	1378	* Set up a callback for when a link with the peer is secured. For bonded
vcoubard	1049:efb29faf12fc	1379	* devices, subsequent reconnections with a bonded peer will result only in
vcoubard	1049:efb29faf12fc	1380	* this callback when the link is secured, and setup procedures will not
rgrover1	717:11b41f651697	1381	* occur unless the bonding information is either lost or deleted on either
rgrover1	717:11b41f651697	1382	* or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
rgrover1	717:11b41f651697	1383	* to the level of security in effect for the secured link.
rgrover1	717:11b41f651697	1384	*
rgrover1	717:11b41f651697	1385	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1386	* You should use the parallel API from SecurityManager directly. A former
rgrover1	717:11b41f651697	1387	* call to ble.onLinkSecured(callback) should be replaced with
rgrover1	717:11b41f651697	1388	* ble.securityManager().onLinkSecured(callback).
rgrover1	717:11b41f651697	1389	*/
rgrover1	717:11b41f651697	1390	void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
rgrover1	717:11b41f651697	1391	securityManager().onLinkSecured(callback);
rgrover1	717:11b41f651697	1392	}
rgrover1	717:11b41f651697	1393
rgrover1	717:11b41f651697	1394	/**
vcoubard	1049:efb29faf12fc	1395	* Set up a callback for successful bonding, meaning that link-specific security
rgrover1	717:11b41f651697	1396	* context is stored persistently for a peer device.
rgrover1	717:11b41f651697	1397	*
rgrover1	717:11b41f651697	1398	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1399	* You should use the parallel API from SecurityManager directly. A former
rgrover1	717:11b41f651697	1400	* call to ble.onSecurityContextStored(callback) should be replaced with
rgrover1	717:11b41f651697	1401	* ble.securityManager().onSecurityContextStored(callback).
rgrover1	717:11b41f651697	1402	*/
rgrover1	717:11b41f651697	1403	void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
rgrover1	717:11b41f651697	1404	securityManager().onSecurityContextStored(callback);
rgrover1	717:11b41f651697	1405	}
rgrover1	717:11b41f651697	1406
rgrover1	717:11b41f651697	1407	/**
vcoubard	1049:efb29faf12fc	1408	* Set up a callback for when the passkey needs to be displayed on a
rgrover1	717:11b41f651697	1409	* peripheral with DISPLAY capability. This happens when security is
vcoubard	1079:79c089630b38	1410	* configured to prevent Man-In-The-Middle attacks, and the peers need to exchange
vcoubard	1049:efb29faf12fc	1411	* a passkey (or PIN) to authenticate the connection
rgrover1	717:11b41f651697	1412	* attempt.
rgrover1	717:11b41f651697	1413	*
rgrover1	717:11b41f651697	1414	* @note: This API is now deprecated and will be dropped in the future.
rgrover1	717:11b41f651697	1415	* You should use the parallel API from SecurityManager directly. A former
rgrover1	717:11b41f651697	1416	* call to ble.onPasskeyDisplay(callback) should be replaced with
rgrover1	717:11b41f651697	1417	* ble.securityManager().onPasskeyDisplay(callback).
rgrover1	717:11b41f651697	1418	*/
rgrover1	717:11b41f651697	1419	void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
rgrover1	717:11b41f651697	1420	return securityManager().onPasskeyDisplay(callback);
rgrover1	717:11b41f651697	1421	}
rgrover1	717:11b41f651697	1422
rgrover1	717:11b41f651697	1423	private:
rgrover1	887:0a45c67b2301	1424	/**
rgrover1	887:0a45c67b2301	1425	* Implementation of init() [internal to BLE_API].
rgrover1	887:0a45c67b2301	1426	*
rgrover1	887:0a45c67b2301	1427	* The implementation is separated into a private method because it isn't
rgrover1	887:0a45c67b2301	1428	* suitable to be included in the header.
rgrover1	887:0a45c67b2301	1429	*/
rgrover1	887:0a45c67b2301	1430	ble_error_t initImplementation(FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback);
rgrover1	887:0a45c67b2301	1431
rgrover1	887:0a45c67b2301	1432	private:
rgrover1	807:50c121156a71	1433	BLE(const BLE&);
rgrover1	807:50c121156a71	1434	BLE &operator=(const BLE &);
rgrover1	807:50c121156a71	1435
rgrover1	807:50c121156a71	1436	private:
rgrover1	862:2afa79e3ed0a	1437	InstanceID_t instanceID;
vcoubard	1049:efb29faf12fc	1438	BLEInstanceBase transport; / The device-specific backend */
rgrover1	717:11b41f651697	1439	};
rgrover1	717:11b41f651697	1440
rgrover1	717:11b41f651697	1441	typedef BLE BLEDevice; /* DEPRECATED. This type alias is retained for the sake of compatibility with older
rgrover1	717:11b41f651697	1442	* code. Will be dropped at some point soon.*/
rgrover1	717:11b41f651697	1443
rgrover1	717:11b41f651697	1444	#endif // ifndef __BLE_H__

Repository toolbox

Export to desktop IDE

Repository details

Type:	Library
Created:	02 Mar 2016
Imports:	2
Forks:	0
Commits:	1132
Dependents:	0
Dependencies:	0
Followers:	1

ble/BLE.h@1116:82d4a8a56d91, 2016-01-11 (annotated)

Who changed what in which revision?

Repository toolbox

Repository details

Important Information for this Arm website

Access Warning