BLE_API - High level Bluetooth Low Energy API and radio abs…

Bluetooth Low Energy » Code » BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Dependents: BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate BLE_ANCS_SDAPI_IRC ... more

Overview

The BLE_API is a high level abstraction for using Bluetooth Low Energy on multiple platforms. For details and examples using the BLE_API please see the BLE_API Summary Page. Or click on the API Documentation tab above.

Supported Services

Supported services can be found in the BLE_API/services folder.

ble/BLE.h@1201:9b71aac42d14, 2016-09-14 (annotated)

Committer:: Vincent Coubard
Date:: Wed Sep 14 14:17:52 2016 +0100
Branch:: 2f55eed1fdde06fdabfb66d41ce6cd14e280978f
Revision:: 1201:9b71aac42d14
Parent:: 1183:1589830dbdb7
Child:: 1202:d5426bb4b03f

Sync with 2f55eed1fdde06fdabfb66d41ce6cd14e280978f



2016-06-06 09:36:57+01:00: Vincent Coubard

Add an interface which allows user code to customise the way BLE events

are processed.



The mechanism is quite simple:

  * user code can process all events pending in the internal BLE stack by

    calling the function BLE::processEvent.

  * user code can be notified when an event become available and the event

    stack has to be processed. The notification is issued by the port of

    mbed BLE.

Who changed what in which revision?

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

Repository toolbox

Export to desktop IDE

Repository details

Type:	Library
Created:	09 Jan 2014
Imports:	8130
Forks:	41
Commits:	1209
Dependents:	694
Dependencies:	0
Followers:	699
Issues:	0

The code in this repository is Apache licensed.