Javier Velasco
/
BLE_API
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of
BLE_API
by 
Bluetooth Low Energy
Diff: ble/BLE.h
- Revision:
- 1142:a358d0d20f62
- Parent:
- 1141:510f5d2d2732
- Child:
- 1144:249843612f87
--- a/ble/BLE.h Wed Apr 06 19:14:06 2016 +0100
+++ b/ble/BLE.h Wed Apr 06 19:14:07 2016 +0100
@@ -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
@@ -139,38 +139,69 @@
*
* @return A pointer to a const string representing the version.
*
- * @note: The string returned 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
@@ -182,10 +213,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
@@ -193,14 +233,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);
@@ -235,7 +275,7 @@
* 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.
+ * @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(...).
@@ -245,10 +285,10 @@
}
/**
- * 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.
+ * @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(...).
@@ -260,7 +300,7 @@
/**
* Set the GAP advertising mode to use for this device.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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(...).
@@ -280,16 +320,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.
+ * @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(...).
*
- * @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
@@ -302,7 +342,7 @@
/**
* @return Minimum Advertising interval in milliseconds.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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(...).
@@ -314,7 +354,7 @@
/**
* @return Minimum Advertising interval in milliseconds for non-connectible mode.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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(...).
@@ -326,7 +366,7 @@
/**
* @return Maximum Advertising interval in milliseconds.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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(...).
@@ -340,7 +380,7 @@
* 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.
+ * @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(...).
@@ -355,7 +395,7 @@
* 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.
+ * @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(...).
@@ -368,7 +408,7 @@
* @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.
+ * @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(...).
@@ -388,7 +428,7 @@
* 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.
+ * @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).
@@ -406,7 +446,7 @@
* @param[in] app
* The appearance of the peripheral.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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).
@@ -421,11 +461,11 @@
* 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.
+ * @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).
@@ -444,7 +484,7 @@
* @param data Data bytes.
* @param len Data length.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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(...).
@@ -458,7 +498,7 @@
* 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.
+ * @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(...).
@@ -471,7 +511,7 @@
* @return Read back advertising data. Useful for storing and
* restoring payload.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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()(...).
@@ -485,7 +525,7 @@
* 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.
+ * @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(...).
@@ -517,7 +557,7 @@
* @param[in] data Data bytes.
* @param[in] len Data length.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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(...).
@@ -530,7 +570,7 @@
* Reset any scan response prepared from prior calls to
* accumulateScanResponse().
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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(...).
@@ -542,7 +582,7 @@
/**
* Start advertising.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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(...).
@@ -554,7 +594,7 @@
/**
* Stop advertising.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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(...).
@@ -585,9 +625,9 @@
* 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.
+ * @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(...).
@@ -614,7 +654,7 @@
* 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.
+ * @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).
@@ -638,7 +678,7 @@
* 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.
+ * @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).
@@ -662,9 +702,9 @@
* 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.
+ * @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(...).
@@ -682,7 +722,7 @@
* 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.
+ * @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(...).
@@ -700,7 +740,7 @@
* 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.
+ * @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).
@@ -712,7 +752,7 @@
/**
* 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.
+ * @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).
@@ -725,7 +765,7 @@
*
* @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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().
@@ -748,7 +788,7 @@
* 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.
+ * @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(...).
@@ -781,12 +821,12 @@
* @param reason
* The reason for disconnection; sent back to the peer.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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).
*
- * @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.
@@ -796,10 +836,10 @@
}
/**
- * 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.
+ * @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().
@@ -820,7 +860,7 @@
* @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.
+ * @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().
@@ -837,7 +877,7 @@
* @param[in] params
* The structure containing the desired parameters.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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().
@@ -856,7 +896,7 @@
* 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.
+ * @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().
@@ -866,11 +906,11 @@
}
/**
- * 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.
+ * @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().
@@ -880,14 +920,14 @@
}
/**
- * 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).
@@ -897,7 +937,7 @@
* 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.
+ * @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().
@@ -907,11 +947,11 @@
}
/**
- * 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.
+ * @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().
@@ -921,11 +961,11 @@
}
/**
- * 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.
+ * @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().
@@ -938,7 +978,7 @@
* 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.
+ * @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().
@@ -955,7 +995,7 @@
* @param[out] countP
* Out parameter to receive the array's size.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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().
@@ -968,7 +1008,7 @@
* 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.
+ * @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().
@@ -983,7 +1023,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
@@ -992,7 +1032,7 @@
*
* @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.
+ * @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().
@@ -1009,7 +1049,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
@@ -1022,7 +1062,7 @@
* 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.
+ * @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().
@@ -1049,7 +1089,7 @@
*
* @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.
+ * @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().
@@ -1083,7 +1123,7 @@
*
* @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.
+ * @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().
@@ -1111,7 +1151,7 @@
*
* @return BLE_ERROR_NONE on success.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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(...).
@@ -1131,7 +1171,7 @@
*
* @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.
+ * @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(...).
@@ -1148,7 +1188,7 @@
* @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.
+ * @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().
@@ -1161,7 +1201,7 @@
* 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.
+ * @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).
@@ -1173,7 +1213,7 @@
/**
* 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.
+ * @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).
@@ -1185,7 +1225,7 @@
/**
* 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.
+ * @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).
@@ -1194,6 +1234,15 @@
gap().onDisconnection(disconnectionCallback);
}
+ /**
+ * The same as onDisconnection(), but allows an object reference and member function
+ * to be added to the chain of callbacks.
+ *
+ * @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).
+ */
template<typename T>
void onDisconnection(T *tptr, void (T::*mptr)(const Gap::DisconnectionCallbackParams_t*)) {
gap().onDisconnection(tptr, mptr);
@@ -1215,7 +1264,7 @@
* 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.
+ * @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(...).
@@ -1228,14 +1277,14 @@
* 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.
+ * @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(...).
@@ -1243,6 +1292,16 @@
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.
+ *
+ * @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(...).
+ */
template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) {
gattServer().onDataSent(objPtr, memberPtr);
}
@@ -1254,15 +1313,15 @@
* 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.
+ * @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(...).
@@ -1270,6 +1329,16 @@
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.
+ *
+ * @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(...).
+ */
template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
gattServer().onDataWritten(objPtr, memberPtr);
}
@@ -1278,22 +1347,22 @@
* 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.
+ * @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(...).
@@ -1301,6 +1370,16 @@
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.
+ *
+ * @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(...).
+ */
template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
return gattServer().onDataRead(objPtr, memberPtr);
}
@@ -1309,7 +1388,7 @@
* 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.
+ * @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).
@@ -1322,7 +1401,7 @@
* 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.
+ * @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).
@@ -1335,7 +1414,7 @@
* 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.
+ * @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).
@@ -1351,7 +1430,7 @@
* security request: bool allowBonding, bool requireMITM, and
* SecurityIOCapabilities_t.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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).
@@ -1366,7 +1445,7 @@
* 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.
+ * @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).
@@ -1383,7 +1462,7 @@
* 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.
+ * @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).
@@ -1396,7 +1475,7 @@
* 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.
+ * @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).
@@ -1412,7 +1491,7 @@
* a passkey (or PIN) to authenticate the connection
* attempt.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
+ * @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).