Wang Xinglu
High level Bluetooth Low Energy API and radio abstraction layer
Fork of
BLE_API
by 
Bluetooth Low Energy
Diff: ble/BLE.h
- Revision:
- 1183:1589830dbdb7
- Parent:
- 1179:4ab722f8dca0
--- a/ble/BLE.h Wed Apr 06 19:15:34 2016 +0100
+++ b/ble/BLE.h Wed Apr 06 19:15:36 2016 +0100
@@ -40,7 +40,7 @@
class BLE
{
public:
- typedef unsigned InstanceID_t; /** The type returned by BLE::getInstanceID(). */
+ typedef unsigned InstanceID_t; /**< The type returned by BLE::getInstanceID(). */
/**
* The context provided to init-completion-callbacks (see init() below).
@@ -53,8 +53,8 @@
* the error value is implementation specific.
*/
struct InitializationCompleteCallbackContext {
- BLE& ble; /* Reference to the BLE object that has been initialized */
- ble_error_t error; /* Error status of the initialization. It is set to BLE_ERROR_NONE if initialization completed successfully. */
+ BLE& ble; /**< Reference to the BLE object that has been initialized */
+ ble_error_t error; /**< Error status of the initialization. It is set to BLE_ERROR_NONE if initialization completed successfully. */
};
/**
@@ -68,7 +68,7 @@
/**
* Initialize the BLE controller. This should be called before using
- * anything else in the BLE_API.
+ * anything else in the BLE API.
*
* init() hands control to the underlying BLE module to accomplish
* initialization. This initialization may tacitly depend on other hardware
@@ -89,11 +89,6 @@
* @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke
* the initialization completion callback at some point.
*
- * @note In some cases, initialization is instantaneous (or blocking); if
- * so, it is acceptable for the stack-specific implementation of init()
- * to invoke the completion callback directly (within its own
- * context).
- *
* @note Nearly all BLE APIs would return
* BLE_ERROR_INITIALIZATION_INCOMPLETE if used on an instance before the
* corresponding transport is initialized.
@@ -138,38 +133,70 @@
* This call allows the application to get the BLE stack version information.
*
* @return A pointer to a const string representing the version.
- * Note: The string is owned by BLE_API.
+ *
+ * @note The string returned is owned by BLE API.
*/
const char *getVersion(void);
- /*
- * Accessors to GAP. Please refer to Gap.h. All GAP related functionality requires
+ /**
+ * Accessor to Gap. All Gap related functionality requires
* going through this accessor.
+ *
+ * @return A reference to a Gap object associated to this BLE instance.
+ */
+ Gap &gap();
+
+ /**
+ * A const alternative to gap().
+ *
+ * @return A const reference to a Gap object associated to this BLE instance.
*/
const Gap &gap() const;
- Gap &gap();
- /*
- * Accessors to GATT Server. Please refer to GattServer.h. All GATTServer related
- * functionality requires going through this accessor.
+ /**
+ * Accessor to GattServer. All GattServer related functionality requires
+ * going through this accessor.
+ *
+ * @return A reference to a GattServer object associated to this BLE instance.
*/
- const GattServer& gattServer() const;
GattServer& gattServer();
- /*
- * Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related
- * functionality requires going through this accessor.
+ /**
+ * A const alternative to gattServer().
+ *
+ * @return A const reference to a GattServer object associated to this BLE instance.
*/
- const GattClient& gattClient() const;
+ const GattServer& gattServer() const;
+
+ /**
+ * Accessors to GattClient. All GattClient related functionality requires going
+ * through this accessor.
+ *
+ * @return A reference to a GattClient object associated to this BLE instance.
+ */
GattClient& gattClient();
- /*
- * Accessors to Security Manager. Please refer to SecurityManager.h. All
- * SecurityManager related functionality requires going through this
- * accessor.
+ /**
+ * A const alternative to gattClient().
+ *
+ * @return A const reference to a GattClient object associated to this BLE instance.
+ */
+ const GattClient& gattClient() const;
+
+ /**
+ * Accessors to SecurityManager. All SecurityManager related functionality requires
+ * going through this accessor.
+ *
+ * @return A reference to a SecurityManager object associated to this BLE instance.
+ */
+ SecurityManager& securityManager();
+
+ /**
+ * A const alternative to securityManager().
+ *
+ * @return A const reference to a SecurityManager object associated to this BLE instance.
*/
const SecurityManager& securityManager() const;
- SecurityManager& securityManager();
/**
* Yield control to the BLE stack or to other tasks waiting for events. This
@@ -181,10 +208,19 @@
void waitForEvent(void);
public:
+ /**
+ * The value of the BLE::InstanceID_t for the default BLE instance.
+ */
static const InstanceID_t DEFAULT_INSTANCE = 0;
#ifndef YOTTA_CFG_BLE_INSTANCES_COUNT
+ /**
+ * The number of permitted BLE instances for the application.
+ */
static const InstanceID_t NUM_INSTANCES = 1;
#else
+ /**
+ * The number of permitted BLE instances for the application.
+ */
static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT;
#endif
@@ -192,14 +228,14 @@
* Get a reference to the BLE singleton corresponding to a given interface.
* There is a static array of BLE singletons.
*
- * @Note: Calling Instance() is preferred over constructing a BLE object
+ * @note Calling Instance() is preferred over constructing a BLE object
* directly, as it returns references to singletons.
*
* @param[in] id
* Instance-ID. This should be less than NUM_INSTANCES
* for the returned BLE singleton to be useful.
*
- * @return a reference to a single object.
+ * @return A reference to a single object.
*/
static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE);
@@ -234,23 +270,23 @@
* Set the BTLE MAC address and type.
* @return BLE_ERROR_NONE on success.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAddress(...) should be replaced with
- * ble.gap().setAddress(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setAddress(). A former call to
+ * ble.setAddress(...) should be replaced with
+ * ble.gap().setAddress(...).
*/
ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
return gap().setAddress(type, address);
}
/**
- * Fetch the BTLE MAC address and type.
+ * Fetch the Bluetooth Low Energy MAC address and type.
* @return BLE_ERROR_NONE on success.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getAddress(...) should be replaced with
- * ble.gap().getAddress(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::getAddress(). A former call to
+ * ble.getAddress(...) should be replaced with
+ * ble.gap().getAddress(...).
*/
ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
return gap().getAddress(typeP, address);
@@ -259,10 +295,10 @@
/**
* Set the GAP advertising mode to use for this device.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingType(...) should be replaced with
- * ble.gap().setAdvertisingType(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setAdvertisingType(). A former call to
+ * ble.setAdvertisingType(...) should be replaced with
+ * ble.gap().setAdvertisingType(...).
*/
void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
gap().setAdvertisingType(advType);
@@ -279,16 +315,16 @@
* This field must be set to 0 if connectionMode is equal
* to ADV_CONNECTABLE_DIRECTED.
*
- * @note: Decreasing this value allows central devices to detect a
+ * @note Decreasing this value allows central devices to detect a
* peripheral faster, at the expense of more power being used by the radio
* due to the higher data transmit rate.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingInterval(...) should be replaced with
- * ble.gap().setAdvertisingInterval(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setAdvertisingInterval(). A former call to
+ * ble.setAdvertisingInterval(...) should be replaced with
+ * ble.gap().setAdvertisingInterval(...).
*
- * @note: [WARNING] This API previously used 0.625ms as the unit for its
+ * @note WARNING: This API previously used 0.625ms as the unit for its
* 'interval' argument. That required an explicit conversion from
* milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
* no longer required as the new units are milliseconds. Any application
@@ -301,10 +337,10 @@
/**
* @return Minimum Advertising interval in milliseconds.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getMinAdvertisingInterval(...) should be replaced with
- * ble.gap().getMinAdvertisingInterval(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::getMinAdvertisingInterval(). A former call to
+ * ble.getMinAdvertisingInterval(...) should be replaced with
+ * ble.gap().getMinAdvertisingInterval(...).
*/
uint16_t getMinAdvertisingInterval(void) const {
return gap().getMinAdvertisingInterval();
@@ -313,10 +349,10 @@
/**
* @return Minimum Advertising interval in milliseconds for non-connectible mode.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
- * ble.gap().getMinNonConnectableAdvertisingInterval(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::MinNonConnectableAdvertisingInterval(). A former call to
+ * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
+ * ble.gap().getMinNonConnectableAdvertisingInterval(...).
*/
uint16_t getMinNonConnectableAdvertisingInterval(void) const {
return gap().getMinNonConnectableAdvertisingInterval();
@@ -325,10 +361,10 @@
/**
* @return Maximum Advertising interval in milliseconds.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getMaxAdvertisingInterval(...) should be replaced with
- * ble.gap().getMaxAdvertisingInterval(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::getMaxAdvertisingInterval(). A former call to
+ * ble.getMaxAdvertisingInterval(...) should be replaced with
+ * ble.gap().getMaxAdvertisingInterval(...).
*/
uint16_t getMaxAdvertisingInterval(void) const {
return gap().getMaxAdvertisingInterval();
@@ -339,10 +375,10 @@
* Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
* and 16383). Use 0 to disable the advertising timeout.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingTimeout(...) should be replaced with
- * ble.gap().setAdvertisingTimeout(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setAdvertisingTimeout(). A former call to
+ * ble.setAdvertisingTimeout(...) should be replaced with
+ * ble.gap().setAdvertisingTimeout(...).
*/
void setAdvertisingTimeout(uint16_t timeout) {
gap().setAdvertisingTimeout(timeout);
@@ -354,10 +390,10 @@
* directly; there are other APIs to tweak advertisement parameters
* individually (see above).
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingParams(...) should be replaced with
- * ble.gap().setAdvertisingParams(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setAdvertisingParams(). A former call to
+ * ble.setAdvertisingParams(...) should be replaced with
+ * ble.gap().setAdvertisingParams(...).
*/
void setAdvertisingParams(const GapAdvertisingParams &advParams) {
gap().setAdvertisingParams(advParams);
@@ -367,10 +403,10 @@
* @return Read back advertising parameters. Useful for storing and
* restoring parameters rapidly.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getAdvertisingParams(...) should be replaced with
- * ble.gap().getAdvertisingParams(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::getAdvertisingParams(). A former call to
+ * ble.getAdvertisingParams(...) should be replaced with
+ * ble.gap().getAdvertisingParams(...).
*/
const GapAdvertisingParams &getAdvertisingParams(void) const {
return gap().getAdvertisingParams();
@@ -387,10 +423,10 @@
* GapAdvertisingData::Flags for valid flags. Multiple
* flags may be specified in combination.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayload(flags) should be replaced with
- * ble.gap().accumulateAdvertisingPayload(flags).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::accumulateAdvertisingPayload(uint8_t). A former call to
+ * ble.accumulateAdvertisingPayload(flags) should be replaced with
+ * ble.gap().accumulateAdvertisingPayload(flags).
*/
ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
return gap().accumulateAdvertisingPayload(flags);
@@ -405,10 +441,11 @@
* @param[in] app
* The appearance of the peripheral.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayload(appearance) should be replaced with
- * ble.gap().accumulateAdvertisingPayload(appearance).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::accumulateAdvertisingPayload(GapAdvertisingData::Appearance).
+ * A former call to ble.accumulateAdvertisingPayload(appearance)
+ * should be replaced with
+ * ble.gap().accumulateAdvertisingPayload(appearance).
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
return gap().accumulateAdvertisingPayload(app);
@@ -420,14 +457,14 @@
* as an additional 31 bytes if the advertising payload is too
* small.
*
- * @param[in] app
+ * @param[in] power
* The max transmit power to be used by the controller. This
* is only a hint.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
- * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::accumulateAdvertisingPayloadTxPower(). A former call to
+ * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
+ * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
*/
ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
return gap().accumulateAdvertisingPayloadTxPower(power);
@@ -443,10 +480,10 @@
* @param data Data bytes.
* @param len Data length.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayload(...) should be replaced with
- * ble.gap().accumulateAdvertisingPayload(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::accumulateAdvertisingPayload(GapAdvertisingData::DataType, const uint8_t, uint8_t).
+ * A former call to ble.accumulateAdvertisingPayload(...) should
+ * be replaced with ble.gap().accumulateAdvertisingPayload(...).
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
return gap().accumulateAdvertisingPayload(type, data, len);
@@ -457,10 +494,10 @@
* underlying stack. It would be uncommon for this API to be used directly;
* there are other APIs to build an advertisement payload (see above).
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingData(...) should be replaced with
- * ble.gap().setAdvertisingPayload(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setAdvertisingData(). A former call to
+ * ble.setAdvertisingData(...) should be replaced with
+ * ble.gap().setAdvertisingPayload(...).
*/
ble_error_t setAdvertisingData(const GapAdvertisingData &advData) {
return gap().setAdvertisingPayload(advData);
@@ -470,10 +507,10 @@
* @return Read back advertising data. Useful for storing and
* restoring payload.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getAdvertisingData(...) should be replaced with
- * ble.gap().getAdvertisingPayload()(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::getAdvertisingData(). A former call to
+ * ble.getAdvertisingData(...) should be replaced with
+ * ble.gap().getAdvertisingPayload()(...).
*/
const GapAdvertisingData &getAdvertisingData(void) const {
return gap().getAdvertisingPayload();
@@ -484,24 +521,27 @@
* accumulateAdvertisingPayload(). This automatically propagates the re-
* initialized advertising payload to the underlying stack.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.clearAdvertisingPayload(...) should be replaced with
- * ble.gap().clearAdvertisingPayload(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::clearAdvertisingPayload(). A former call to
+ * ble.clearAdvertisingPayload(...) should be replaced with
+ * ble.gap().clearAdvertisingPayload(...).
*/
void clearAdvertisingPayload(void) {
gap().clearAdvertisingPayload();
}
/**
- * This API is *deprecated* and resolves to a no-operation. It is left here
- * to allow older code to compile. Please avoid using this API in new code.
- * This API will be dropped in a future release.
+ * Dynamically reset the accumulated advertising
+ * payload and scanResponse. The application must clear and re-
+ * accumulates a new advertising payload (and scanResponse) before using this
+ * API.
*
- * Formerly, it would be used to dynamically reset the accumulated advertising
- * payload and scanResponse; to do this, the application would clear and re-
- * accumulate a new advertising payload (and scanResponse) before using this
- * API. Updates to the underlying advertisement payload now happen
+ * @return BLE_ERROR_NONE when the advertising payload is set successfully.
+ *
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setAdvertisingPayload().
+ *
+ * @note The new APIs in Gap update the underlying advertisement payload
* implicitly.
*/
ble_error_t setAdvertisingPayload(void) {
@@ -516,10 +556,10 @@
* @param[in] data Data bytes.
* @param[in] len Data length.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.accumulateScanResponse(...) should be replaced with
- * ble.gap().accumulateScanResponse(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::accumulateScanResponse(). A former call to
+ * ble.accumulateScanResponse(...) should be replaced with
+ * ble.gap().accumulateScanResponse(...).
*/
ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
return gap().accumulateScanResponse(type, data, len);
@@ -529,10 +569,10 @@
* Reset any scan response prepared from prior calls to
* accumulateScanResponse().
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.clearScanResponse(...) should be replaced with
- * ble.gap().clearScanResponse(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::clearScanResponse(). A former call to
+ * ble.clearScanResponse(...) should be replaced with
+ * ble.gap().clearScanResponse(...).
*/
void clearScanResponse(void) {
gap().clearScanResponse();
@@ -541,10 +581,10 @@
/**
* Start advertising.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.startAdvertising(...) should be replaced with
- * ble.gap().startAdvertising(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::startAdvertising(). A former call to
+ * ble.startAdvertising(...) should be replaced with
+ * ble.gap().startAdvertising(...).
*/
ble_error_t startAdvertising(void) {
return gap().startAdvertising();
@@ -553,10 +593,10 @@
/**
* Stop advertising.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.stopAdvertising(...) should be replaced with
- * ble.gap().stopAdvertising(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::stopAdvertising(). A former call to
+ * ble.stopAdvertising(...) should be replaced with
+ * ble.gap().stopAdvertising(...).
*/
ble_error_t stopAdvertising(void) {
return gap().stopAdvertising();
@@ -584,12 +624,12 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @Note: The scan interval and window are recommendations to the BLE stack.
+ * @note The scan interval and window are recommendations to the BLE stack.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setScanParams(...) should be replaced with
- * ble.gap().setScanParams(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setScanParams(). A former call to
+ * ble.setScanParams(...) should be replaced with
+ * ble.gap().setScanParams(...).
*/
ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
@@ -613,10 +653,10 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setScanInterval(interval) should be replaced with
- * ble.gap().setScanInterval(interval).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setScanInterval(). A former call to
+ * ble.setScanInterval(interval) should be replaced with
+ * ble.gap().setScanInterval(interval).
*/
ble_error_t setScanInterval(uint16_t interval) {
return gap().setScanInterval(interval);
@@ -637,10 +677,10 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setScanWindow(window) should be replaced with
- * ble.gap().setScanWindow(window).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setScanWindow(). A former call to
+ * ble.setScanWindow(window) should be replaced with
+ * ble.gap().setScanWindow(window).
*/
ble_error_t setScanWindow(uint16_t window) {
return gap().setScanWindow(window);
@@ -661,12 +701,12 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @Note: The scan interval and window are recommendations to the BLE stack.
+ * @note The scan interval and window are recommendations to the BLE stack.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setScanTimeout(...) should be replaced with
- * ble.gap().setScanTimeout(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setScanTimeout(). A former call to
+ * ble.setScanTimeout(...) should be replaced with
+ * ble.gap().setScanTimeout(...).
*/
ble_error_t setScanTimeout(uint16_t timeout) {
return gap().setScanTimeout(timeout);
@@ -681,10 +721,10 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setActiveScan(...) should be replaced with
- * ble.gap().setActiveScanning(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setActiveScan(). A former call to
+ * ble.setActiveScan(...) should be replaced with
+ * ble.gap().setActiveScanning(...).
*/
void setActiveScan(bool activeScanning) {
gap().setActiveScanning(activeScanning);
@@ -699,10 +739,10 @@
* receiving every advertisement report. This can be passed in
* as NULL, in which case scanning may not be enabled at all.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.startScan(callback) should be replaced with
- * ble.gap().startScan(callback).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::startScan(). A former call to
+ * ble.startScan(callback) should be replaced with
+ * ble.gap().startScan(callback).
*/
ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) {
return gap().startScan(callback);
@@ -711,10 +751,10 @@
/**
* Same as above, but this takes an (object, method) pair for a callback.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.startScan(callback) should be replaced with
- * ble.gap().startScan(object, callback).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::startScan(). A former call to
+ * ble.startScan(callback) should be replaced with
+ * ble.gap().startScan(object, callback).
*/
template<typename T>
ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
@@ -724,10 +764,10 @@
*
* @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.stopScan() should be replaced with
- * ble.gap().stopScan().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::stopScan(). A former call to
+ * ble.stopScan() should be replaced with
+ * ble.gap().stopScan().
*/
ble_error_t stopScan(void) {
return gap().stopScan();
@@ -747,10 +787,10 @@
* successfully. The onConnection callback (if set) is invoked upon
* a connection event.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.connect(...) should be replaced with
- * ble.gap().connect(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::connect(). A former call to
+ * ble.connect(...) should be replaced with
+ * ble.gap().connect(...).
*/
ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
@@ -780,28 +820,27 @@
* @param reason
* The reason for disconnection; sent back to the peer.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.disconnect(reason) should be replaced with
- * ble.gap().disconnect(reason).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::disconnect(). A former call to
+ * ble.disconnect(reason) should be replaced with
+ * ble.gap().disconnect(reason).
*
- * @note: This version of disconnect() doesn't take a connection handle. It
+ * @note This version of disconnect() doesn't take a connection handle. It
* works reliably only for stacks that are limited to a single
- * connection. This API should be considered *deprecated* in favour of the
- * alternative, which takes a connection handle. It will be dropped in the future.
+ * connection.
*/
ble_error_t disconnect(Gap::DisconnectionReason_t reason) {
return gap().disconnect(reason);
}
/**
- * Returns the current GAP state of the device using a bitmask that
+ * Returns the current Gap state of the device using a bitmask that
* describes whether the device is advertising or connected.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getGapState() should be replaced with
- * ble.gap().getState().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::getState(). A former call to
+ * ble.getGapState() should be replaced with
+ * ble.gap().getState().
*/
Gap::GapState_t getGapState(void) const {
return gap().getState();
@@ -819,10 +858,10 @@
* @return BLE_ERROR_NONE if the parameters were successfully filled into
* the given structure pointed to by params.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getPreferredConnectionParams() should be replaced with
- * ble.gap().getPreferredConnectionParams().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::getPreferredConnectionParams(). A former call to
+ * ble.getPreferredConnectionParams() should be replaced with
+ * ble.gap().getPreferredConnectionParams().
*/
ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) {
return gap().getPreferredConnectionParams(params);
@@ -836,10 +875,10 @@
* @param[in] params
* The structure containing the desired parameters.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setPreferredConnectionParams() should be replaced with
- * ble.gap().setPreferredConnectionParams().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setPreferredConnectionParams(). A former call to
+ * ble.setPreferredConnectionParams() should be replaced with
+ * ble.gap().setPreferredConnectionParams().
*/
ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) {
return gap().setPreferredConnectionParams(params);
@@ -855,38 +894,38 @@
* Pointer to desired connection parameters. If NULL is provided on a peripheral role,
* the parameters in the PPCP characteristic of the GAP service will be used instead.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.updateConnectionParams() should be replaced with
- * ble.gap().updateConnectionParams().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::updateConnectionParams(). A former call to
+ * ble.updateConnectionParams() should be replaced with
+ * ble.gap().updateConnectionParams().
*/
ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
return gap().updateConnectionParams(handle, params);
}
/**
- * Set the device name characteristic in the GAP service.
+ * Set the device name characteristic in the Gap service.
* @param[in] deviceName
* The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setDeviceName() should be replaced with
- * ble.gap().setDeviceName().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setDeviceName(). A former call to
+ * ble.setDeviceName() should be replaced with
+ * ble.gap().setDeviceName().
*/
ble_error_t setDeviceName(const uint8_t *deviceName) {
return gap().setDeviceName(deviceName);
}
/**
- * Get the value of the device name characteristic in the GAP service.
+ * Get the value of the device name characteristic in the Gap service.
* @param[out] deviceName
* Pointer to an empty buffer where the UTF-8 *non NULL-
* terminated* string will be placed. Set this
* value to NULL in order to obtain the deviceName-length
* from the 'length' parameter.
*
- * @param[in/out] lengthP
+ * @param[in,out] lengthP
* (on input) Length of the buffer pointed to by deviceName;
* (on output) the complete device name length (without the
* null terminator).
@@ -896,38 +935,38 @@
* number of bytes actually returned in deviceName. The application may
* use this information to retry with a suitable buffer size.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getDeviceName() should be replaced with
- * ble.gap().getDeviceName().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::getDeviceName(). A former call to
+ * ble.getDeviceName() should be replaced with
+ * ble.gap().getDeviceName().
*/
ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
return gap().getDeviceName(deviceName, lengthP);
}
/**
- * Set the appearance characteristic in the GAP service.
+ * Set the appearance characteristic in the Gap service.
* @param[in] appearance
* The new value for the device-appearance.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAppearance() should be replaced with
- * ble.gap().setAppearance().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setAppearance(). A former call to
+ * ble.setAppearance() should be replaced with
+ * ble.gap().setAppearance().
*/
ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
return gap().setAppearance(appearance);
}
/**
- * Get the appearance characteristic in the GAP service.
- * @param[out] appearance
+ * Get the appearance characteristic in the Gap service.
+ * @param[out] appearanceP
* The new value for the device-appearance.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getAppearance() should be replaced with
- * ble.gap().getAppearance().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::getAppearance(). A former call to
+ * ble.getAppearance() should be replaced with
+ * ble.gap().getAppearance().
*/
ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
return gap().getAppearance(appearanceP);
@@ -937,10 +976,10 @@
* Set the radio's transmit power.
* @param[in] txPower Radio transmit power in dBm.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setTxPower() should be replaced with
- * ble.gap().setTxPower().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::setTxPower(). A former call to
+ * ble.setTxPower() should be replaced with
+ * ble.gap().setTxPower().
*/
ble_error_t setTxPower(int8_t txPower) {
return gap().setTxPower(txPower);
@@ -954,10 +993,10 @@
* @param[out] countP
* Out parameter to receive the array's size.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getPermittedTxPowerValues() should be replaced with
- * ble.gap().getPermittedTxPowerValues().
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::getPermittedTxPowerValues(). A former call to
+ * ble.getPermittedTxPowerValues() should be replaced with
+ * ble.gap().getPermittedTxPowerValues().
*/
void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
gap().getPermittedTxPowerValues(valueArrayPP, countP);
@@ -967,10 +1006,10 @@
* Add a service declaration to the local server ATT table. Also add the
* characteristics contained within.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.addService() should be replaced with
- * ble.gattServer().addService().
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::addService(). A former call
+ * to ble.addService() should be replaced with
+ * ble.gattServer().addService().
*/
ble_error_t addService(GattService &service) {
return gattServer().addService(service);
@@ -982,7 +1021,7 @@
* Attribute handle for the value attribute of the characteristic.
* @param[out] buffer
* A buffer to hold the value being read.
- * @param[in/out] lengthP
+ * @param[in,out] lengthP
* Length of the buffer being supplied. If the attribute
* value is longer than the size of the supplied buffer,
* this variable will return the total attribute value length
@@ -991,10 +1030,10 @@
*
* @return BLE_ERROR_NONE if a value was read successfully into the buffer.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.readCharacteristicValue() should be replaced with
- * ble.gattServer().read().
+ * @deprecated You should use the parallel API from GattServer directly,
+ * GattServer::read(GattAttribute::Handle_t,uint8_t,uint16_t). A former call
+ * to ble.readCharacteristicValue() should be replaced with
+ * ble.gattServer().read().
*/
ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
return gattServer().read(attributeHandle, buffer, lengthP);
@@ -1008,7 +1047,7 @@
* Attribute handle for the value attribute of the characteristic.
* @param[out] buffer
* A buffer to hold the value being read.
- * @param[in/out] lengthP
+ * @param[in,out] lengthP
* Length of the buffer being supplied. If the attribute
* value is longer than the size of the supplied buffer,
* this variable will return the total attribute value length
@@ -1021,10 +1060,10 @@
* parameter to allow fetches for connection-specific multivalued
* attributes (such as the CCCDs).
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.readCharacteristicValue() should be replaced with
- * ble.gattServer().read().
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::read(Gap::Handle_t,GattAttribute::Handle_t,uint8_t,uint16_t).
+ * A former call to ble.readCharacteristicValue() should be replaced with
+ * ble.gattServer().read().
*/
ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP);
@@ -1048,10 +1087,10 @@
*
* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.updateCharacteristicValue() should be replaced with
- * ble.gattServer().write().
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::write(GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
+ * A former call to ble.updateCharacteristicValue() should be replaced with
+ * ble.gattServer().write().
*/
ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle,
const uint8_t *value,
@@ -1082,10 +1121,10 @@
*
* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.updateCharacteristicValue() should be replaced with
- * ble.gattServer().write().
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::write(Gap::Handle_t,GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
+ * A former call to ble.updateCharacteristicValue() should be replaced with
+ * ble.gattServer().write().
*/
ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle,
GattAttribute::Handle_t attributeHandle,
@@ -1110,10 +1149,10 @@
*
* @return BLE_ERROR_NONE on success.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.initializeSecurity(...) should be replaced with
- * ble.securityManager().init(...).
+ * @deprecated You should use the parallel API from SecurityManager directly, refer to
+ * SecurityManager.init(). A former
+ * call to ble.initializeSecurity(...) should be replaced with
+ * ble.securityManager().init(...).
*/
ble_error_t initializeSecurity(bool enableBonding = true,
bool requireMITM = true,
@@ -1130,10 +1169,10 @@
*
* @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.getLinkSecurity(...) should be replaced with
- * ble.securityManager().getLinkSecurity(...).
+ * @deprecated You should use the parallel API from SecurityManager directly, refer to
+ * SecurityManager::getLinkSecurity(). A former
+ * call to ble.getLinkSecurity(...) should be replaced with
+ * ble.securityManager().getLinkSecurity(...).
*/
ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) {
return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
@@ -1147,10 +1186,10 @@
* @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
* application registration.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.purgeAllBondingState() should be replaced with
- * ble.securityManager().purgeAllBondingState().
+ * @deprecated You should use the parallel API from SecurityManager directly, refer to
+ * SecurityManager::purgeAllBondingState(). A former
+ * call to ble.purgeAllBondingState() should be replaced with
+ * ble.securityManager().purgeAllBondingState().
*/
ble_error_t purgeAllBondingState(void) {
return securityManager().purgeAllBondingState();
@@ -1160,10 +1199,10 @@
* Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
* possible event types.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call
- * to ble.onTimeout(callback) should be replaced with
- * ble.gap().onTimeout(callback).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::onTimeout(). A former call
+ * to ble.onTimeout(callback) should be replaced with
+ * ble.gap().onTimeout(callback).
*/
void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) {
gap().onTimeout(timeoutCallback);
@@ -1172,10 +1211,10 @@
/**
* Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call
- * to ble.onConnection(callback) should be replaced with
- * ble.gap().onConnection(callback).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::onConnection(). A former call
+ * to ble.onConnection(callback) should be replaced with
+ * ble.gap().onConnection(callback).
*/
void onConnection(Gap::ConnectionEventCallback_t connectionCallback) {
gap().onConnection(connectionCallback);
@@ -1184,15 +1223,24 @@
/**
* Append to a chain of callbacks to be invoked upon GAP disconnection.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call
- * to ble.onDisconnection(callback) should be replaced with
- * ble.gap().onDisconnection(callback).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::onDisconnection(). A former call
+ * to ble.onDisconnection(callback) should be replaced with
+ * ble.gap().onDisconnection(callback).
*/
void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) {
gap().onDisconnection(disconnectionCallback);
}
+ /**
+ * The same as onDisconnection(), but allows an object reference and member function
+ * to be added to the chain of callbacks.
+ *
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::onDisconnection(). A former call
+ * to ble.onDisconnection(callback) should be replaced with
+ * ble.gap().onDisconnection(callback).
+ */
template<typename T>
void onDisconnection(T *tptr, void (T::*mptr)(const Gap::DisconnectionCallbackParams_t*)) {
gap().onDisconnection(tptr, mptr);
@@ -1214,10 +1262,10 @@
* The application handler to be invoked in response to a radio
* ACTIVE/INACTIVE event.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call
- * to ble.onRadioNotification(...) should be replaced with
- * ble.gap().onRadioNotification(...).
+ * @deprecated You should use the parallel API from Gap directly, refer to
+ * Gap::onRadioNotification(). A former call
+ * to ble.onRadioNotification(...) should be replaced with
+ * ble.gap().onRadioNotification(...).
*/
void onRadioNotification(void (*callback)(bool)) {
gap().onRadioNotification(callback);
@@ -1227,21 +1275,31 @@
* Add a callback for the GATT event DATA_SENT (which is triggered when
* updates are sent out by GATT in the form of notifications).
*
- * @Note: It is possible to chain together multiple onDataSent callbacks
+ * @note It is possible to chain together multiple onDataSent callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics.
*
- * @Note: It is also possible to set up a callback into a member function of
+ * @note It is also possible to set up a callback into a member function of
* some object.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onDataSent(...) should be replaced with
- * ble.gattServer().onDataSent(...).
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::onDataSent(). A former call
+ * to ble.onDataSent(...) should be replaced with
+ * ble.gattServer().onDataSent(...).
*/
void onDataSent(void (*callback)(unsigned count)) {
gattServer().onDataSent(callback);
}
+
+ /**
+ * The same as onDataSent(), but allows an object reference and member function
+ * to be added to the chain of callbacks.
+ *
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::onDataSent(). A former call
+ * to ble.onDataSent(...) should be replaced with
+ * ble.gattServer().onDataSent(...).
+ */
template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) {
gattServer().onDataSent(objPtr, memberPtr);
}
@@ -1253,22 +1311,32 @@
* For a Central, this callback is triggered when a response is received for
* a write request.
*
- * @Note: It is possible to chain together multiple onDataWritten callbacks
+ * @note It is possible to chain together multiple onDataWritten callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics. Many services, such as DFU and UART, add their own
* onDataWritten callbacks behind the scenes to trap interesting events.
*
- * @Note: It is also possible to set up a callback into a member function of
+ * @note It is also possible to set up a callback into a member function of
* some object.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onDataWritten(...) should be replaced with
- * ble.gattServer().onDataWritten(...).
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::onDataWritten(). A former call
+ * to ble.onDataWritten(...) should be replaced with
+ * ble.gattServer().onDataWritten(...).
*/
void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {
gattServer().onDataWritten(callback);
}
+
+ /**
+ * The same as onDataWritten(), but allows an object reference and member function
+ * to be added to the chain of callbacks.
+ *
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::onDataWritten(). A former call
+ * to ble.onDataWritten(...) should be replaced with
+ * ble.gattServer().onDataWritten(...).
+ */
template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
gattServer().onDataWritten(objPtr, memberPtr);
}
@@ -1277,29 +1345,39 @@
* Set up a callback to be invoked on the peripheral when an attribute is
* being read by a remote client.
*
- * @Note: This functionality may not be available on all underlying stacks.
+ * @note This functionality may not be available on all underlying stacks.
* You could use GattCharacteristic::setReadAuthorizationCallback() as an
* alternative.
*
- * @Note: It is possible to chain together multiple onDataRead callbacks
+ * @note It is possible to chain together multiple onDataRead callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics. Services may add their own onDataRead callbacks
* behind the scenes to trap interesting events.
*
- * @Note: It is also possible to set up a callback into a member function of
+ * @note It is also possible to set up a callback into a member function of
* some object.
*
* @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
* else BLE_ERROR_NONE.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onDataRead(...) should be replaced with
- * ble.gattServer().onDataRead(...).
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::onDataRead(). A former call
+ * to ble.onDataRead(...) should be replaced with
+ * ble.gattServer().onDataRead(...).
*/
ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
return gattServer().onDataRead(callback);
}
+
+ /**
+ * The same as onDataRead(), but allows an object reference and member function
+ * to be added to the chain of callbacks.
+ *
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::onDataRead(). A former call
+ * to ble.onDataRead(...) should be replaced with
+ * ble.gattServer().onDataRead(...).
+ */
template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
return gattServer().onDataRead(objPtr, memberPtr);
}
@@ -1308,10 +1386,10 @@
* Set up a callback for when notifications or indications are enabled for a
* characteristic on the local GattServer.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onUpdatesEnabled(callback) should be replaced with
- * ble.gattServer().onUpdatesEnabled(callback).
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::onUpdatesEnabled(). A former call
+ * to ble.onUpdatesEnabled(callback) should be replaced with
+ * ble.gattServer().onUpdatesEnabled(callback).
*/
void onUpdatesEnabled(GattServer::EventCallback_t callback) {
gattServer().onUpdatesEnabled(callback);
@@ -1321,10 +1399,10 @@
* Set up a callback for when notifications or indications are disabled for a
* characteristic on the local GattServer.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onUpdatesEnabled(callback) should be replaced with
- * ble.gattServer().onUpdatesEnabled(callback).
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::onUpdatesDisabled(). A former call
+ * to ble.onUpdatesEnabled(callback) should be replaced with
+ * ble.gattServer().onUpdatesEnabled(callback).
*/
void onUpdatesDisabled(GattServer::EventCallback_t callback) {
gattServer().onUpdatesDisabled(callback);
@@ -1334,10 +1412,10 @@
* Set up a callback for when the GATT server receives a response for an
* indication event sent previously.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onConfirmationReceived(callback) should be replaced with
- * ble.gattServer().onConfirmationReceived(callback).
+ * @deprecated You should use the parallel API from GattServer directly, refer to
+ * GattServer::onConfirmationReceived(). A former call
+ * to ble.onConfirmationReceived(callback) should be replaced with
+ * ble.gattServer().onConfirmationReceived(callback).
*/
void onConfirmationReceived(GattServer::EventCallback_t callback) {
gattServer().onConfirmationReceived(callback);
@@ -1350,10 +1428,10 @@
* security request: bool allowBonding, bool requireMITM, and
* SecurityIOCapabilities_t.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.onSecuritySetupInitiated(callback) should be replaced with
- * ble.securityManager().onSecuritySetupInitiated(callback).
+ * @deprecated You should use the parallel API from SecurityManager directly, refer to
+ * SecurityManager::onSecuritySetupInitiated(). A former
+ * call to ble.onSecuritySetupInitiated(callback) should be replaced with
+ * ble.securityManager().onSecuritySetupInitiated(callback).
*/
void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
securityManager().onSecuritySetupInitiated(callback);
@@ -1365,10 +1443,10 @@
* devices. The callback is passed in the success/failure status of the
* security setup procedure.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.onSecuritySetupCompleted(callback) should be replaced with
- * ble.securityManager().onSecuritySetupCompleted(callback).
+ * @deprecated You should use the parallel API from SecurityManager directly, refer to
+ * SecurityManager::onSecuritySetupCompleted(). A former
+ * call to ble.onSecuritySetupCompleted(callback) should be replaced with
+ * ble.securityManager().onSecuritySetupCompleted(callback).
*/
void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
securityManager().onSecuritySetupCompleted(callback);
@@ -1382,10 +1460,10 @@
* or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
* to the level of security in effect for the secured link.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.onLinkSecured(callback) should be replaced with
- * ble.securityManager().onLinkSecured(callback).
+ * @deprecated You should use the parallel API from SecurityManager directly, refer to
+ * SecurityManager::onLinkSecured(). A former
+ * call to ble.onLinkSecured(callback) should be replaced with
+ * ble.securityManager().onLinkSecured(callback).
*/
void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
securityManager().onLinkSecured(callback);
@@ -1395,10 +1473,10 @@
* Set up a callback for successful bonding, meaning that link-specific security
* context is stored persistently for a peer device.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.onSecurityContextStored(callback) should be replaced with
- * ble.securityManager().onSecurityContextStored(callback).
+ * @deprecated You should use the parallel API from SecurityManager directly, refer to
+ * SecurityManager::onSecurityContextStored(). A former
+ * call to ble.onSecurityContextStored(callback) should be replaced with
+ * ble.securityManager().onSecurityContextStored(callback).
*/
void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
securityManager().onSecurityContextStored(callback);
@@ -1411,10 +1489,10 @@
* a passkey (or PIN) to authenticate the connection
* attempt.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.onPasskeyDisplay(callback) should be replaced with
- * ble.securityManager().onPasskeyDisplay(callback).
+ * @deprecated You should use the parallel API from SecurityManager directly, refer to
+ * SecurityManager::onPasskeyDisplay(). A former
+ * call to ble.onPasskeyDisplay(callback) should be replaced with
+ * ble.securityManager().onPasskeyDisplay(callback).
*/
void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
return securityManager().onPasskeyDisplay(callback);
@@ -1438,7 +1516,8 @@
BLEInstanceBase *transport; /* The device-specific backend */
};
-typedef BLE BLEDevice; /* DEPRECATED. This type alias is retained for the sake of compatibility with older
+typedef BLE BLEDevice; /**< @deprecated This type alias is retained for the
+ * sake of compatibility with older
* code. Will be dropped at some point soon.*/
-#endif // ifndef __BLE_H__
\ No newline at end of file
+#endif /* ifndef __BLE_H__ */
\ No newline at end of file