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:
- 1142:a358d0d20f62
- Parent:
- 1141:510f5d2d2732
- Child:
- 1144:249843612f87
diff -r 510f5d2d2732 -r a358d0d20f62 ble/BLE.h
--- 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).