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@1179:4ab722f8dca0, 2016-04-06 (annotated)

Committer:: vcoubard
Date:: Wed Apr 06 19:15:30 2016 +0100
Revision:: 1179:4ab722f8dca0
Parent:: 1176:8b308f971420
Child:: 1183:1589830dbdb7

Synchronized with git rev ca632aaf

Author: Andres Amaya Garcia

Update Gap state after advertising times out



The BLE API was not updating the Gap internal state when the advertising stops

because of a user timeout. This commit fixes the issue by updating the internal

state structure in Gap just before the registered callbacks are notified of the

advertising timeout.

Who changed what in which revision?

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