Bluetooth Low Energy
High level Bluetooth Low Energy API and radio abstraction layer
Dependents: BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate BLE_ANCS_SDAPI_IRC ... more
Overview
The BLE_API is a high level abstraction for using Bluetooth Low Energy on multiple platforms. For details and examples using the BLE_API please see the BLE_API Summary Page. Or click on the API Documentation tab above.
Supported Services
Supported services can be found in the BLE_API/services folder.
Revision 1155:e28c7aac64ab, committed 2016-04-06
- Comitter:
- vcoubard
- Date:
- Wed Apr 06 19:14:34 2016 +0100
- Parent:
- 1154:702de9e6b049
- Child:
- 1156:e1ea38b576c6
- Commit message:
- Synchronized with git rev e20c8c58
Author: Vincent Coubard
Merge pull request #163 from ARMmbed/develop
merge version 2.5.0 into master
Changed in this revision
--- a/ble/BLE.h Wed Apr 06 19:14:32 2016 +0100
+++ b/ble/BLE.h Wed Apr 06 19:14:34 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
@@ -138,70 +138,38 @@
* 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 returned is owned by BLE API.
+ * Note: The string is owned by BLE_API.
*/
const char *getVersion(void);
- /**
- * Accessor to Gap. All Gap related functionality requires
+ /*
+ * Accessors to GAP. Please refer to Gap.h. 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();
- /**
- * Accessor to GattServer. All GattServer related functionality requires
- * going through this accessor.
- *
- * @return A reference to a GattServer object associated to this BLE instance.
- */
- GattServer& gattServer();
-
- /**
- * A const alternative to gattServer().
- *
- * @return A const reference to a GattServer object associated to this BLE instance.
+ /*
+ * Accessors to GATT Server. Please refer to GattServer.h. All GATTServer related
+ * functionality requires going through this accessor.
*/
const GattServer& gattServer() const;
+ GattServer& gattServer();
- /**
- * 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();
-
- /**
- * A const alternative to gattClient().
- *
- * @return A const reference to a GattClient object associated to this BLE instance.
+ /*
+ * Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related
+ * functionality requires going through this accessor.
*/
const GattClient& gattClient() const;
+ GattClient& gattClient();
- /**
- * 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.
+ /*
+ * Accessors to Security Manager. Please refer to SecurityManager.h. All
+ * SecurityManager related functionality requires going through this
+ * accessor.
*/
const SecurityManager& securityManager() const;
+ SecurityManager& securityManager();
/**
* Yield control to the BLE stack or to other tasks waiting for events. This
@@ -213,19 +181,10 @@
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
@@ -233,14 +192,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);
@@ -275,21 +234,23 @@
* Set the BTLE MAC address and type.
* @return BLE_ERROR_NONE on success.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setAddress(...) should be replaced with
- * ble.gap().setAddress(...).
+ * @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(...).
*/
ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
return gap().setAddress(type, address);
}
/**
- * Fetch the Bluetooth Low Energy MAC address and type.
+ * Fetch the BTLE MAC address and type.
* @return BLE_ERROR_NONE on success.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getAddress(...) should be replaced with
- * ble.gap().getAddress(...).
+ * @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(...).
*/
ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
return gap().getAddress(typeP, address);
@@ -298,9 +259,10 @@
/**
* Set the GAP advertising mode to use for this device.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingType(...) should be replaced with
- * ble.gap().setAdvertisingType(...).
+ * @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(...).
*/
void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
gap().setAdvertisingType(advType);
@@ -317,15 +279,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.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingInterval(...) should be replaced with
- * ble.gap().setAdvertisingInterval(...).
+ * @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
@@ -338,9 +301,10 @@
/**
* @return Minimum Advertising interval in milliseconds.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getMinAdvertisingInterval(...) should be replaced with
- * ble.gap().getMinAdvertisingInterval(...).
+ * @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(...).
*/
uint16_t getMinAdvertisingInterval(void) const {
return gap().getMinAdvertisingInterval();
@@ -349,9 +313,10 @@
/**
* @return Minimum Advertising interval in milliseconds for non-connectible mode.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
- * ble.gap().getMinNonConnectableAdvertisingInterval(...).
+ * @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(...).
*/
uint16_t getMinNonConnectableAdvertisingInterval(void) const {
return gap().getMinNonConnectableAdvertisingInterval();
@@ -360,9 +325,10 @@
/**
* @return Maximum Advertising interval in milliseconds.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getMaxAdvertisingInterval(...) should be replaced with
- * ble.gap().getMaxAdvertisingInterval(...).
+ * @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(...).
*/
uint16_t getMaxAdvertisingInterval(void) const {
return gap().getMaxAdvertisingInterval();
@@ -373,9 +339,10 @@
* Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
* and 16383). Use 0 to disable the advertising timeout.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingTimeout(...) should be replaced with
- * ble.gap().setAdvertisingTimeout(...).
+ * @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(...).
*/
void setAdvertisingTimeout(uint16_t timeout) {
gap().setAdvertisingTimeout(timeout);
@@ -387,9 +354,10 @@
* directly; there are other APIs to tweak advertisement parameters
* individually (see above).
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingParams(...) should be replaced with
- * ble.gap().setAdvertisingParams(...).
+ * @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(...).
*/
void setAdvertisingParams(const GapAdvertisingParams &advParams) {
gap().setAdvertisingParams(advParams);
@@ -399,9 +367,10 @@
* @return Read back advertising parameters. Useful for storing and
* restoring parameters rapidly.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getAdvertisingParams(...) should be replaced with
- * ble.gap().getAdvertisingParams(...).
+ * @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(...).
*/
const GapAdvertisingParams &getAdvertisingParams(void) const {
return gap().getAdvertisingParams();
@@ -418,9 +387,10 @@
* GapAdvertisingData::Flags for valid flags. Multiple
* flags may be specified in combination.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayload(flags) should be replaced with
- * ble.gap().accumulateAdvertisingPayload(flags).
+ * @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).
*/
ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
return gap().accumulateAdvertisingPayload(flags);
@@ -435,9 +405,10 @@
* @param[in] app
* The appearance of the peripheral.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayload(appearance) should be replaced with
- * ble.gap().accumulateAdvertisingPayload(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.accumulateAdvertisingPayload(appearance) should be replaced with
+ * ble.gap().accumulateAdvertisingPayload(appearance).
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
return gap().accumulateAdvertisingPayload(app);
@@ -449,13 +420,14 @@
* as an additional 31 bytes if the advertising payload is too
* small.
*
- * @param[in] power
+ * @param[in] app
* The max transmit power to be used by the controller. This
* is only a hint.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
- * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
+ * @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).
*/
ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
return gap().accumulateAdvertisingPayloadTxPower(power);
@@ -471,9 +443,10 @@
* @param data Data bytes.
* @param len Data length.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayload(...) should be replaced with
- * ble.gap().accumulateAdvertisingPayload(...).
+ * @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(...).
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
return gap().accumulateAdvertisingPayload(type, data, len);
@@ -484,9 +457,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).
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingData(...) should be replaced with
- * ble.gap().setAdvertisingPayload(...).
+ * @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(...).
*/
ble_error_t setAdvertisingData(const GapAdvertisingData &advData) {
return gap().setAdvertisingPayload(advData);
@@ -496,9 +470,10 @@
* @return Read back advertising data. Useful for storing and
* restoring payload.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getAdvertisingData(...) should be replaced with
- * ble.gap().getAdvertisingPayload()(...).
+ * @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()(...).
*/
const GapAdvertisingData &getAdvertisingData(void) const {
return gap().getAdvertisingPayload();
@@ -509,25 +484,24 @@
* accumulateAdvertisingPayload(). This automatically propagates the re-
* initialized advertising payload to the underlying stack.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.clearAdvertisingPayload(...) should be replaced with
- * ble.gap().clearAdvertisingPayload(...).
+ * @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(...).
*/
void clearAdvertisingPayload(void) {
gap().clearAdvertisingPayload();
}
/**
- * 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.
+ * 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.
*
- * @return BLE_ERROR_NONE when the advertising payload is set successfully.
- *
- * @deprecated You should use the parallel API from Gap directly.
- *
- * @note The new APIs in Gap update the underlying advertisement payload
+ * 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
* implicitly.
*/
ble_error_t setAdvertisingPayload(void) {
@@ -542,9 +516,10 @@
* @param[in] data Data bytes.
* @param[in] len Data length.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.accumulateScanResponse(...) should be replaced with
- * ble.gap().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.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);
@@ -554,9 +529,10 @@
* Reset any scan response prepared from prior calls to
* accumulateScanResponse().
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.clearScanResponse(...) should be replaced with
- * ble.gap().clearScanResponse(...).
+ * @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(...).
*/
void clearScanResponse(void) {
gap().clearScanResponse();
@@ -565,9 +541,10 @@
/**
* Start advertising.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.startAdvertising(...) should be replaced with
- * ble.gap().startAdvertising(...).
+ * @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(...).
*/
ble_error_t startAdvertising(void) {
return gap().startAdvertising();
@@ -576,9 +553,10 @@
/**
* Stop advertising.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.stopAdvertising(...) should be replaced with
- * ble.gap().stopAdvertising(...).
+ * @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(...).
*/
ble_error_t stopAdvertising(void) {
return gap().stopAdvertising();
@@ -606,11 +584,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.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setScanParams(...) should be replaced with
- * ble.gap().setScanParams(...).
+ * @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(...).
*/
ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
@@ -634,9 +613,10 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setScanInterval(interval) should be replaced with
- * ble.gap().setScanInterval(interval).
+ * @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).
*/
ble_error_t setScanInterval(uint16_t interval) {
return gap().setScanInterval(interval);
@@ -657,9 +637,10 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setScanWindow(window) should be replaced with
- * ble.gap().setScanWindow(window).
+ * @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).
*/
ble_error_t setScanWindow(uint16_t window) {
return gap().setScanWindow(window);
@@ -680,11 +661,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.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setScanTimeout(...) should be replaced with
- * ble.gap().setScanTimeout(...).
+ * @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(...).
*/
ble_error_t setScanTimeout(uint16_t timeout) {
return gap().setScanTimeout(timeout);
@@ -699,9 +681,10 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setActiveScan(...) should be replaced with
- * ble.gap().setActiveScanning(...).
+ * @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(...).
*/
void setActiveScan(bool activeScanning) {
gap().setActiveScanning(activeScanning);
@@ -716,9 +699,10 @@
* receiving every advertisement report. This can be passed in
* as NULL, in which case scanning may not be enabled at all.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.startScan(callback) should be replaced with
- * ble.gap().startScan(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(callback).
*/
ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) {
return gap().startScan(callback);
@@ -727,9 +711,10 @@
/**
* Same as above, but this takes an (object, method) pair for a callback.
*
- * @deprecated 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).
+ * @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).
*/
template<typename T>
ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
@@ -739,9 +724,10 @@
*
* @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.stopScan() should be replaced with
- * ble.gap().stopScan().
+ * @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().
*/
ble_error_t stopScan(void) {
return gap().stopScan();
@@ -761,9 +747,10 @@
* successfully. The onConnection callback (if set) is invoked upon
* a connection event.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.connect(...) should be replaced with
- * ble.gap().connect(...).
+ * @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(...).
*/
ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
@@ -793,27 +780,28 @@
* @param reason
* The reason for disconnection; sent back to the peer.
*
- * @deprecated 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 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.
- *
- * @deprecated You should use the parallel API from Gap directly.
+ * connection. This API should be considered *deprecated* in favour of the
+ * alternative, which takes a connection handle. It will be dropped in the future.
*/
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.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getGapState() should be replaced with
- * ble.gap().getState().
+ * @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().
*/
Gap::GapState_t getGapState(void) const {
return gap().getState();
@@ -831,9 +819,10 @@
* @return BLE_ERROR_NONE if the parameters were successfully filled into
* the given structure pointed to by params.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getPreferredConnectionParams() should be replaced with
- * ble.gap().getPreferredConnectionParams().
+ * @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().
*/
ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) {
return gap().getPreferredConnectionParams(params);
@@ -847,9 +836,10 @@
* @param[in] params
* The structure containing the desired parameters.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setPreferredConnectionParams() should be replaced with
- * ble.gap().setPreferredConnectionParams().
+ * @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().
*/
ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) {
return gap().setPreferredConnectionParams(params);
@@ -865,36 +855,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.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.updateConnectionParams() should be replaced with
- * ble.gap().updateConnectionParams().
+ * @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().
*/
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.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setDeviceName() should be replaced with
- * ble.gap().setDeviceName().
+ * @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().
*/
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).
@@ -904,35 +896,38 @@
* number of bytes actually returned in deviceName. The application may
* use this information to retry with a suitable buffer size.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getDeviceName() should be replaced with
- * ble.gap().getDeviceName().
+ * @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().
*/
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.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setAppearance() should be replaced with
- * ble.gap().setAppearance().
+ * @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().
*/
ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
return gap().setAppearance(appearance);
}
/**
- * Get the appearance characteristic in the Gap service.
- * @param[out] appearanceP
+ * Get the appearance characteristic in the GAP service.
+ * @param[out] appearance
* The new value for the device-appearance.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getAppearance() should be replaced with
- * ble.gap().getAppearance().
+ * @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().
*/
ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
return gap().getAppearance(appearanceP);
@@ -942,9 +937,10 @@
* Set the radio's transmit power.
* @param[in] txPower Radio transmit power in dBm.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.setTxPower() should be replaced with
- * ble.gap().setTxPower().
+ * @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().
*/
ble_error_t setTxPower(int8_t txPower) {
return gap().setTxPower(txPower);
@@ -958,9 +954,10 @@
* @param[out] countP
* Out parameter to receive the array's size.
*
- * @deprecated You should use the parallel API from Gap directly. A former call to
- * ble.getPermittedTxPowerValues() should be replaced with
- * ble.gap().getPermittedTxPowerValues().
+ * @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().
*/
void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
gap().getPermittedTxPowerValues(valueArrayPP, countP);
@@ -970,9 +967,10 @@
* Add a service declaration to the local server ATT table. Also add the
* characteristics contained within.
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.addService() should be replaced with
- * ble.gattServer().addService().
+ * @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().
*/
ble_error_t addService(GattService &service) {
return gattServer().addService(service);
@@ -984,7 +982,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
@@ -993,9 +991,10 @@
*
* @return BLE_ERROR_NONE if a value was read successfully into the buffer.
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.readCharacteristicValue() should be replaced with
- * ble.gattServer().read().
+ * @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().
*/
ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
return gattServer().read(attributeHandle, buffer, lengthP);
@@ -1009,7 +1008,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,9 +1021,10 @@
* parameter to allow fetches for connection-specific multivalued
* attributes (such as the CCCDs).
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.readCharacteristicValue() should be replaced with
- * ble.gattServer().read().
+ * @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().
*/
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,9 +1048,10 @@
*
* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.updateCharacteristicValue() should be replaced with
- * ble.gattServer().write().
+ * @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().
*/
ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle,
const uint8_t *value,
@@ -1081,9 +1082,10 @@
*
* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.updateCharacteristicValue() should be replaced with
- * ble.gattServer().write().
+ * @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().
*/
ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle,
GattAttribute::Handle_t attributeHandle,
@@ -1108,9 +1110,10 @@
*
* @return BLE_ERROR_NONE on success.
*
- * @deprecated You should use the parallel API from SecurityManager directly. A former
- * call to ble.initializeSecurity(...) should be replaced with
- * ble.securityManager().init(...).
+ * @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(...).
*/
ble_error_t initializeSecurity(bool enableBonding = true,
bool requireMITM = true,
@@ -1127,9 +1130,10 @@
*
* @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
*
- * @deprecated You should use the parallel API from SecurityManager directly. A former
- * call to ble.getLinkSecurity(...) should be replaced with
- * ble.securityManager().getLinkSecurity(...).
+ * @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(...).
*/
ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) {
return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
@@ -1143,9 +1147,10 @@
* @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
* application registration.
*
- * @deprecated You should use the parallel API from SecurityManager directly. A former
- * call to ble.purgeAllBondingState() should be replaced with
- * ble.securityManager().purgeAllBondingState().
+ * @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().
*/
ble_error_t purgeAllBondingState(void) {
return securityManager().purgeAllBondingState();
@@ -1155,9 +1160,10 @@
* Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
* possible event types.
*
- * @deprecated You should use the parallel API from Gap directly. A former call
- * to ble.onTimeout(callback) should be replaced with
- * ble.gap().onTimeout(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.onTimeout(callback) should be replaced with
+ * ble.gap().onTimeout(callback).
*/
void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) {
gap().onTimeout(timeoutCallback);
@@ -1166,9 +1172,10 @@
/**
* Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
*
- * @deprecated You should use the parallel API from Gap directly. A former call
- * to ble.onConnection(callback) should be replaced with
- * ble.gap().onConnection(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.onConnection(callback) should be replaced with
+ * ble.gap().onConnection(callback).
*/
void onConnection(Gap::ConnectionEventCallback_t connectionCallback) {
gap().onConnection(connectionCallback);
@@ -1177,22 +1184,15 @@
/**
* Append to a chain of callbacks to be invoked upon GAP disconnection.
*
- * @deprecated You should use the parallel API from Gap directly. A former call
- * to ble.onDisconnection(callback) should be replaced with
- * ble.gap().onDisconnection(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.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. 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,9 +1214,10 @@
* The application handler to be invoked in response to a radio
* ACTIVE/INACTIVE event.
*
- * @deprecated You should use the parallel API from Gap directly. A former call
- * to ble.onRadioNotification(...) should be replaced with
- * ble.gap().onRadioNotification(...).
+ * @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(...).
*/
void onRadioNotification(void (*callback)(bool)) {
gap().onRadioNotification(callback);
@@ -1226,29 +1227,21 @@
* 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.
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.onDataSent(...) should be replaced with
- * ble.gattServer().onDataSent(...).
+ * @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(...).
*/
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. 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);
}
@@ -1260,30 +1253,22 @@
* 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.
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.onDataWritten(...) should be replaced with
- * ble.gattServer().onDataWritten(...).
+ * @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(...).
*/
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. 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);
}
@@ -1292,37 +1277,29 @@
* 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.
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.onDataRead(...) should be replaced with
- * ble.gattServer().onDataRead(...).
+ * @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(...).
*/
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. 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);
}
@@ -1331,9 +1308,10 @@
* Set up a callback for when notifications or indications are enabled for a
* characteristic on the local GattServer.
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.onUpdatesEnabled(callback) should be replaced with
- * ble.gattServer().onUpdatesEnabled(callback).
+ * @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).
*/
void onUpdatesEnabled(GattServer::EventCallback_t callback) {
gattServer().onUpdatesEnabled(callback);
@@ -1343,9 +1321,10 @@
* Set up a callback for when notifications or indications are disabled for a
* characteristic on the local GattServer.
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.onUpdatesEnabled(callback) should be replaced with
- * ble.gattServer().onUpdatesEnabled(callback).
+ * @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).
*/
void onUpdatesDisabled(GattServer::EventCallback_t callback) {
gattServer().onUpdatesDisabled(callback);
@@ -1355,9 +1334,10 @@
* Set up a callback for when the GATT server receives a response for an
* indication event sent previously.
*
- * @deprecated You should use the parallel API from GattServer directly. A former call
- * to ble.onConfirmationReceived(callback) should be replaced with
- * ble.gattServer().onConfirmationReceived(callback).
+ * @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).
*/
void onConfirmationReceived(GattServer::EventCallback_t callback) {
gattServer().onConfirmationReceived(callback);
@@ -1370,9 +1350,10 @@
* security request: bool allowBonding, bool requireMITM, and
* SecurityIOCapabilities_t.
*
- * @deprecated You should use the parallel API from SecurityManager directly. A former
- * call to ble.onSecuritySetupInitiated(callback) should be replaced with
- * ble.securityManager().onSecuritySetupInitiated(callback).
+ * @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).
*/
void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
securityManager().onSecuritySetupInitiated(callback);
@@ -1384,9 +1365,10 @@
* devices. The callback is passed in the success/failure status of the
* security setup procedure.
*
- * @deprecated You should use the parallel API from SecurityManager directly. A former
- * call to ble.onSecuritySetupCompleted(callback) should be replaced with
- * ble.securityManager().onSecuritySetupCompleted(callback).
+ * @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).
*/
void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
securityManager().onSecuritySetupCompleted(callback);
@@ -1400,9 +1382,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.
*
- * @deprecated You should use the parallel API from SecurityManager directly. A former
- * call to ble.onLinkSecured(callback) should be replaced with
- * ble.securityManager().onLinkSecured(callback).
+ * @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).
*/
void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
securityManager().onLinkSecured(callback);
@@ -1412,9 +1395,10 @@
* Set up a callback for successful bonding, meaning that link-specific security
* context is stored persistently for a peer device.
*
- * @deprecated You should use the parallel API from SecurityManager directly. A former
- * call to ble.onSecurityContextStored(callback) should be replaced with
- * ble.securityManager().onSecurityContextStored(callback).
+ * @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).
*/
void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
securityManager().onSecurityContextStored(callback);
@@ -1427,9 +1411,10 @@
* a passkey (or PIN) to authenticate the connection
* attempt.
*
- * @deprecated You should use the parallel API from SecurityManager directly. A former
- * call to ble.onPasskeyDisplay(callback) should be replaced with
- * ble.securityManager().onPasskeyDisplay(callback).
+ * @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).
*/
void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
return securityManager().onPasskeyDisplay(callback);
@@ -1453,8 +1438,7 @@
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
--- a/ble/BLEInstanceBase.h Wed Apr 06 19:14:32 2016 +0100
+++ b/ble/BLEInstanceBase.h Wed Apr 06 19:14:34 2016 +0100
@@ -32,104 +32,18 @@
class BLEInstanceBase
{
public:
- /**
- * Initialize the underlying BLE stack. This should be called before
- * anything else in the BLE API.
- *
- * @param[in] instanceID
- * The ID of the instance to initialize.
- * @param[in] initCallback
- * A callback for when initialization completes for a BLE
- * instance. This is an optional parameter set to NULL when not
- * supplied.
- *
- * @return BLE_ERROR_NONE if the initialization procedure was started
- * successfully.
- */
virtual ble_error_t init(BLE::InstanceID_t instanceID,
FunctionPointerWithContext<BLE::InitializationCompleteCallbackContext *> initCallback) = 0;
-
- /**
- * Check whether the underlying stack has already been initialized,
- * possible with a call to init().
- *
- * @return true if the initialization has completed for the underlying BLE
- * stack.
- */
virtual bool hasInitialized(void) const = 0;
-
- /**
- * Shutdown the underlying BLE stack. This includes purging the stack of
- * GATT and GAP state and clearing all state from other BLE components
- * such as the SecurityManager. init() must be called afterwards to
- * re-instantiate services and GAP state.
- *
- * @return BLE_ERROR_NONE if the underlying stack and all other services of
- * the BLE API were shutdown correctly.
- */
virtual ble_error_t shutdown(void) = 0;
-
- /**
- * Fetches a string representation of the underlying BLE stack's version.
- *
- * @return A pointer to the string representation of the underlying
- * BLE stack's version.
- */
virtual const char * getVersion(void) = 0;
-
- /**
- * Accessor to Gap. This function is used by BLE::gap().
- *
- * @return A reference to a Gap object associated to this BLE instance.
- */
virtual Gap& getGap() = 0;
-
- /**
- * A const alternative to getGap().
- *
- * @return A const reference to a Gap object associated to this BLE instance.
- */
virtual const Gap& getGap() const = 0;
-
- /**
- * Accessor to GattServer. This function is used by BLE::gattServer().
- *
- * @return A reference to a GattServer object associated to this BLE instance.
- */
virtual GattServer& getGattServer() = 0;
-
- /**
- * A const alternative to getGattServer().
- *
- * @return A const reference to a GattServer object associated to this BLE instance.
- */
virtual const GattServer& getGattServer() const = 0;
-
- /**
- * Accessors to GattClient. This function is used by BLE::gattClient().
- *
- * @return A reference to a GattClient object associated to this BLE instance.
- */
virtual GattClient& getGattClient() = 0;
-
- /**
- * Accessors to SecurityManager. This function is used by BLE::securityManager().
- *
- * @return A reference to a SecurityManager object associated to this BLE instance.
- */
virtual SecurityManager& getSecurityManager() = 0;
-
- /**
- * A const alternative to getSecurityManager().
- *
- * @return A const reference to a SecurityManager object associated to this BLE instance.
- */
virtual const SecurityManager& getSecurityManager() const = 0;
-
- /**
- * Yield control to the BLE stack or to other tasks waiting for events.
- * refer to BLE::waitForEvent().
- */
virtual void waitForEvent(void) = 0;
};
--- a/ble/CallChainOfFunctionPointersWithContext.h Wed Apr 06 19:14:32 2016 +0100
+++ b/ble/CallChainOfFunctionPointersWithContext.h Wed Apr 06 19:14:34 2016 +0100
@@ -55,17 +55,16 @@
* }
* @endcode
*/
+
template <typename ContextType>
class CallChainOfFunctionPointersWithContext : public SafeBool<CallChainOfFunctionPointersWithContext<ContextType> > {
public:
- /**
- * The type of each callback in the callchain.
- */
typedef FunctionPointerWithContext<ContextType> *pFunctionPointerWithContext_t;
public:
- /**
- * Create an empty chain.
+ /** Create an empty chain.
+ *
+ * @param size (optional) Initial size of the chain.
*/
CallChainOfFunctionPointersWithContext() : chainHead(NULL) {
/* empty */
@@ -75,66 +74,58 @@
clear();
}
- /**
- * Add a function at the front of the chain.
+ /** Add a function at the front of the chain.
*
- * @param[in] function
- * A pointer to a void function.
+ * @param function A pointer to a void function.
*
- * @return The function object created for @p function.
+ * @returns
+ * The function object created for 'function'.
*/
pFunctionPointerWithContext_t add(void (*function)(ContextType context)) {
return common_add(new FunctionPointerWithContext<ContextType>(function));
}
- /**
- * Add a function at the front of the chain.
+ /** Add a function at the front of the chain.
*
- * @param[in] tptr
- * Pointer to the object to call the member function on.
- * @param[in] mptr
- * Pointer to the member function to be called.
+ * @param tptr Pointer to the object to call the member function on.
+ * @param mptr Pointer to the member function to be called.
*
- * @return The function object created for @p tptr and @p mptr.
+ * @returns
+ * The function object created for 'tptr' and 'mptr'.
*/
template<typename T>
pFunctionPointerWithContext_t add(T *tptr, void (T::*mptr)(ContextType context)) {
return common_add(new FunctionPointerWithContext<ContextType>(tptr, mptr));
}
- /**
- * Add a function at the front of the chain.
+ /** Add a function at the front of the chain.
*
- * @param[in] func
- * The FunctionPointerWithContext to add.
- *
- * @return The function object created for @p func.
+ * @param func The FunctionPointerWithContext to add.
*/
pFunctionPointerWithContext_t add(const FunctionPointerWithContext<ContextType>& func) {
return common_add(new FunctionPointerWithContext<ContextType>(func));
}
- /**
- * Detach a function pointer from a callchain.
- *
- * @param[in] toDetach
- * FunctionPointerWithContext to detach from this callchain.
- *
- * @return true if a function pointer has been detached and false otherwise.
- */
- bool detach(const FunctionPointerWithContext<ContextType>& toDetach) {
+ /**
+ * Detach a function pointer from a callchain
+ *
+ * @oaram toDetach FunctionPointerWithContext to detach from this callchain
+ *
+ * @return true if a function pointer has been detached and false otherwise
+ */
+ bool detach(const FunctionPointerWithContext<ContextType>& toDetach) {
pFunctionPointerWithContext_t current = chainHead;
pFunctionPointerWithContext_t previous = NULL;
while (current) {
- if(*current == toDetach) {
+ if(*current == toDetach) {
if(previous == NULL) {
- if(currentCalled == current) {
+ if(currentCalled == current) {
currentCalled = NULL;
}
chainHead = current->getNext();
} else {
- if(currentCalled == current) {
+ if(currentCalled == current) {
currentCalled = previous;
}
previous->chainAsNext(current->getNext());
@@ -150,8 +141,7 @@
return false;
}
- /**
- * Clear the call chain (remove all functions in the chain).
+ /** Clear the call chain (remove all functions in the chain).
*/
void clear(void) {
pFunctionPointerWithContext_t fptr = chainHead;
@@ -164,32 +154,26 @@
chainHead = NULL;
}
- /**
- * Check whether the callchain contains any callbacks.
- *
- * @return true if the callchain is not empty and false otherwise.
- */
bool hasCallbacksAttached(void) const {
return (chainHead != NULL);
}
- /**
- * Call all the functions in the chain in sequence.
+ /** Call all the functions in the chain in sequence
*/
void call(ContextType context) {
((const CallChainOfFunctionPointersWithContext*) this)->call(context);
}
/**
- * Same as call() above, but const.
+ * @brief same as above but const
*/
void call(ContextType context) const {
currentCalled = chainHead;
- while(currentCalled) {
+ while(currentCalled) {
currentCalled->call(context);
// if this was the head and the call removed the head
- if(currentCalled == NULL) {
+ if(currentCalled == NULL) {
currentCalled = chainHead;
} else {
currentCalled = currentCalled->getNext();
@@ -198,41 +182,34 @@
}
/**
- * Same as call(), but with function call operator.
- * @code
- *
+ * @brief same as above but with function call operator
+ * \code
+ *
* void first(bool);
* void second(bool);
- *
+ *
* CallChainOfFunctionPointerWithContext<bool> foo;
- *
+ *
* foo.attach(first);
* foo.attach(second);
- *
+ *
* // call the callchain like a function
* foo(true);
- *
- * @endcode
+ *
+ * \endcode
*/
void operator()(ContextType context) const {
call(context);
}
/**
- * Bool conversion operation.
- *
- * @return true if the callchain is not empty and false otherwise.
+ * @brief bool conversion operation
*/
bool toBool() const {
return chainHead != NULL;
}
private:
- /**
- * Add a callback to the head of the callchain.
- *
- * @return A pointer to the head of the callchain.
- */
pFunctionPointerWithContext_t common_add(pFunctionPointerWithContext_t pf) {
if (chainHead == NULL) {
chainHead = pf;
@@ -245,17 +222,10 @@
}
private:
- /**
- * A pointer to the first callback in the callchain or NULL if the callchain is empty.
- */
pFunctionPointerWithContext_t chainHead;
-
- /**
- * Iterator during a function call, this has to be mutable because the call function is const.
- *
- * @note Mutable is the correct behaviour here, the iterator never leaks outside the object.
- * so the object can still be seen as logically const even if it is modified.
- */
+ // iterator during a function call, this has to be mutable because the call function is const.
+ // Note: mutable is the correct behaviour here, the iterator never leak outside the object.
+ // So the object can still be seen as logically const even if it change its internal state
mutable pFunctionPointerWithContext_t currentCalled;
--- a/ble/CharacteristicDescriptorDiscovery.h Wed Apr 06 19:14:32 2016 +0100
+++ b/ble/CharacteristicDescriptorDiscovery.h Wed Apr 06 19:14:34 2016 +0100
@@ -36,7 +36,7 @@
public:
/**
* @brief Parameter type of CharacteristicDescriptorDiscovery::DiscoveryCallback_t.
- * @details Every time a characteristic descriptor has been discovered, the callback
+ * @detail Every time a characteristic descriptor has been discovered, the callback
* registered for the discovery operation through GattClient::discoverCharacteristicDescriptors
* or DiscoveredCharacteristic::discoverDescriptors will be called with this parameter.
*
--- a/ble/DiscoveredCharacteristic.h Wed Apr 06 19:14:32 2016 +0100
+++ b/ble/DiscoveredCharacteristic.h Wed Apr 06 19:14:34 2016 +0100
@@ -28,7 +28,7 @@
* @brief Representation of a characteristic discovered during a GattClient
* discovery procedure (see GattClient::launchServiceDiscovery ).
*
- * @details Provide detailed informations about a discovered characteristic like:
+ * @detail Provide detailed informations about a discovered characteristic like:
* - Its UUID (see #getUUID).
* - The most important handles of the characteristic definition
* (see #getDeclHandle, #getValueHandle, #getLastHandle )
@@ -52,88 +52,19 @@
uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
public:
- /**
- * @brief Check the value of the Properties_t::_broadcast property
- * of the discovered characteristic.
- *
- * @return true if broadcasting the value is permitted, and false
- * otherwise.
- */
- bool broadcast(void) const {
- return _broadcast;
- }
-
- /**
- * @brief Check the value of the Properties_t::_read property of the
- * discovered characteristic.
- *
- * @return true if reading the value is permitted, and false
- * otherwise.
- */
- bool read(void) const {
- return _read;
- }
-
- /**
- * @brief Check the value of the Properties_t::_writeWoResp property
- * of the discovered characteristic.
- *
- * @return true if writing the value with Write Command is permitted,
- * false otherwise.
- */
- bool writeWoResp(void) const {
- return _writeWoResp;
- }
-
- /**
- * @brief Check the value of the Properties_t::_write property of the
- * discovered characteristic.
- *
- * @return true if writing the value with Write Request is permitted,
- * false otherwise.
- */
- bool write(void) const {
- return _write;
- }
-
- /**
- * @brief Check the value of the Properties_t::_notify property of the
- * discovered characteristic.
- *
- * @return true if notifications of the value are permitted, false
- * otherwise.
- */
- bool notify(void) const {
- return _notify;
- }
-
- /**
- * @brief Check the value of the Properties_t::_indicate property of
- * the discovered characteristic.
- *
- * @return true if indications of the value are permitted, false
- * otherwise.
- */
- bool indicate(void) const {
- return _indicate;
- }
-
- /**
- * @brief Check the value of the Properties_t::_authSignedWrite
- * property of the discovered characteristic.
- *
- * @return true if writing the value with Signed Write Command is
- * permitted, false otherwise.
- */
- bool authSignedWrite(void) const {
- return _authSignedWrite;
- }
+ bool broadcast(void) const {return _broadcast; }
+ bool read(void) const {return _read; }
+ bool writeWoResp(void) const {return _writeWoResp; }
+ bool write(void) const {return _write; }
+ bool notify(void) const {return _notify; }
+ bool indicate(void) const {return _indicate; }
+ bool authSignedWrite(void) const {return _authSignedWrite;}
/**
* @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t
*
- * @param[in] lhs The left hand side of the equality expression
- * @param[in] rhs The right hand side of the equality expression
+ * @param lhs[in] The left hand side of the equality expression
+ * @param rhs[in] The right hand side of the equality expression
*
* @return true if operands are equals, false otherwise.
*/
@@ -170,9 +101,8 @@
* than ATT_MTU - 1, this function must be called multiple times with
* appropriate offset to read the complete value.
*
- * @param[in] offset
- * The position - in the characteristic value bytes stream - where
- * the read operation begin.
+ * @param offset[in] The position - in the characteristic value bytes stream - where
+ * the read operation begin.
*
* @return BLE_ERROR_NONE if a read has been initiated, or
* BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
@@ -185,11 +115,9 @@
* @brief Same as #read(uint16_t) const but allow the user to register a callback
* which will be fired once the read is done.
*
- * @param[in] offset
- * The position - in the characteristic value bytes stream - where
- * the read operation begin.
- * @param[in] onRead
- * Continuation of the read operation
+ * @param offset[in] The position - in the characteristic value bytes stream - where
+ * the read operation begin.
+ * @param onRead[in] Continuation of the read operation
*/
ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const;
@@ -246,21 +174,12 @@
ble_error_t write(uint16_t length, const uint8_t *value) const;
/**
- * Same as write(uint16_t, const uint8_t *) const but register a callback
+ * Same as #write(uint16_t, const uint8_t *) const but register a callback
* which will be called once the data has been written.
*
- * @param[in] length
- * The amount of bytes to write.
- * @param[in] value
- * The bytes to write.
- * @param[in] onWrite
- * Continuation callback for the write operation
- *
- * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
- * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
- * BLE_STACK_BUSY if some client procedure is already in progress, or
- * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
- * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
+ * @param[in] length The amount of bytes to write.
+ * @param[in] value The bytes to write.
+ * @param[in] onRead Continuation callback for the write operation
*/
ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onWrite) const;
@@ -287,7 +206,7 @@
/**
* @brief Get the declaration handle of this characteristic.
- * @details The declaration handle is the first handle of a characteristic
+ * @detail The declaration handle is the first handle of a characteristic
* definition. The value accessible at this handle contains the following
* informations:
* - The characteristics properties (see Properties_t). This value can
@@ -356,10 +275,8 @@
/**
* @brief "Equal to" operator for DiscoveredCharacteristic
*
- * @param[in] lhs
- * The left hand side of the equality expression
- * @param[in] rhs
- * The right hand side of the equality expression
+ * @param lhs[in] The left hand side of the equality expression
+ * @param rhs[in] The right hand side of the equality expression
*
* @return true if operands are equals, false otherwise.
*/
@@ -376,12 +293,10 @@
/**
* @brief "Not equal to" operator for DiscoveredCharacteristic
*
- * @param[in] lhs
- * The right hand side of the expression
- * @param[in] rhs
- * The left hand side of the expression
+ * @param lhs[in] The right hand side of the expression
+ * @param rhs[in] The left hand side of the expression
*
- * @return true if operands are not equal, false otherwise.
+ * @return true if operands are not equals, false otherwise.
*/
friend bool operator !=(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) {
return !(lhs == rhs);
@@ -399,37 +314,15 @@
}
protected:
- /**
- * Pointer to the underlying GattClient for this DiscoveredCharacteristic object.
- */
GattClient *gattc;
protected:
- /**
- * Discovered characteristic's UUID.
- */
UUID uuid;
- /**
- * Hold the configured properties of the discovered characteristic.
- * For more information refer to Properties_t.
- */
Properties_t props;
- /**
- * Value handle of the discovered characteristic's declaration attribute.
- */
GattAttribute::Handle_t declHandle;
- /**
- * Value handle of the discovered characteristic's value attribute.
- */
GattAttribute::Handle_t valueHandle;
- /**
- * Value handle of the discovered characteristic's last attribute.
- */
GattAttribute::Handle_t lastHandle;
- /**
- * Handle for the connection where the characteristic was discovered.
- */
Gap::Handle_t connHandle;
};
--- a/ble/DiscoveredCharacteristicDescriptor.h Wed Apr 06 19:14:32 2016 +0100 +++ b/ble/DiscoveredCharacteristicDescriptor.h Wed Apr 06 19:14:34 2016 +0100 @@ -28,7 +28,7 @@ * discovery procedure (see GattClient::discoverCharacteristicDescriptors or * DiscoveredCharacteristic::discoverDescriptors ). * - * @details Provide detailed informations about a discovered characteristic descriptor + * @detail Provide detailed informations about a discovered characteristic descriptor * like: * - Its UUID (see #getUUID). * - Its handle (see #getAttributeHandle)
--- a/ble/GattClient.h Wed Apr 06 19:14:32 2016 +0100
+++ b/ble/GattClient.h Wed Apr 06 19:14:34 2016 +0100
@@ -351,7 +351,7 @@
/**
* @brief Terminate an ongoing characteristic descriptor discovery.
- * @details This should result in an invocation of the TerminationCallback if
+ * @detail This should result in an invocation of the TerminationCallback if
* the characteristic descriptor discovery is active.
* @param characteristic[in] The characteristic on which the running descriptors
* discovery should be stopped.
--- a/ble/SafeBool.h Wed Apr 06 19:14:32 2016 +0100
+++ b/ble/SafeBool.h Wed Apr 06 19:14:34 2016 +0100
@@ -17,32 +17,26 @@
#ifndef BLE_API_SAFE_BOOL_H_
#define BLE_API_SAFE_BOOL_H_
-/* Safe bool idiom, see : http://www.artima.com/cppsource/safebool.html */
+//safe bool idiom, see : http://www.artima.com/cppsource/safebool.html
namespace SafeBool_ {
/**
- * @brief Base class for all intances of SafeBool.
- * This base class reduces instantiation of trueTag function.
+ * @brief Base class for all intances of SafeBool,
+ * This base class reduce instantiation of trueTag function
*/
class base {
template<typename>
friend class SafeBool;
protected:
- /**
- * The bool type is a pointer to method which can be used in boolean context.
- */
- typedef void (base::*BoolType_t)() const;
+ //the bool type is a pointer to method which can be used in boolean context
+ typedef void (base::*BoolType_t)() const;
- /**
- * Non implemented call, use to disallow conversion between unrelated types.
- */
- void invalidTag() const;
+ // non implemented call, use to disallow conversion between unrelated types
+ void invalidTag() const;
- /**
- * Member function which indicate true value.
- */
- void trueTag() const {}
+ // member function which indicate true value
+ void trueTag() const {}
};
@@ -50,75 +44,71 @@
/**
* @brief template class SafeBool use CRTP to made boolean conversion easy and correct.
- * Derived class should implement the function bool toBool() const to make this work. Inheritance
+ * Derived class should implement the function bool toBool() const to make this work. Inheritance
* should be public.
*
* @tparam T Type of the derived class
- *
- * @code
- *
- * class A : public SafeBool<A> {
+ *
+ * \code
+ *
+ * class A : public SafeBool<A> {
* public:
- *
+ *
* // boolean conversion
- * bool toBool() {
- *
- * }
+ * bool toBool() {
+ *
+ * }
* };
- *
- * class B : public SafeBool<B> {
+ *
+ * class B : public SafeBool<B> {
* public:
- *
+ *
* // boolean conversion
- * bool toBool() const {
- *
- * }
+ * bool toBool() const {
+ *
+ * }
* };
- *
+ *
* A a;
* B b;
- *
- * // will compile
- * if(a) {
- *
+ *
+ * // will compile
+ * if(a) {
+ *
* }
- *
- * // compilation error
- * if(a == b) {
- *
+ *
+ * // compilation error
+ * if(a == b) {
+ *
* }
- *
- *
- * @endcode
+ *
+ *
+ * \endcode
*/
-template <typename T>
+template <typename T>
class SafeBool : public SafeBool_::base {
public:
- /**
- * Bool operator implementation, derived class has to provide bool toBool() const function.
- */
- operator BoolType_t() const {
- return (static_cast<const T*>(this))->toBool()
- ? &SafeBool<T>::trueTag : 0;
- }
+ /**
+ * bool operator implementation, derived class has to provide bool toBool() const function.
+ */
+ operator BoolType_t() const {
+ return (static_cast<const T*>(this))->toBool()
+ ? &SafeBool<T>::trueTag : 0;
+ }
};
-/**
- * Avoid conversion to bool between different classes.
- */
+//Avoid conversion to bool between different classes
template <typename T, typename U>
void operator==(const SafeBool<T>& lhs,const SafeBool<U>& rhs) {
lhs.invalidTag();
- // return false;
+// return false;
}
-/**
- * Avoid conversion to bool between different classes.
- */
+//Avoid conversion to bool between different classes
template <typename T,typename U>
void operator!=(const SafeBool<T>& lhs,const SafeBool<U>& rhs) {
- lhs.invalidTag();
- // return false;
+ lhs.invalidTag();
+// return false;
}
#endif /* BLE_API_SAFE_BOOL_H_ */
\ No newline at end of file
--- a/ble/services/BatteryService.h Wed Apr 06 19:14:32 2016 +0100
+++ b/ble/services/BatteryService.h Wed Apr 06 19:14:34 2016 +0100
@@ -28,7 +28,7 @@
class BatteryService {
public:
/**
- * @param[in] _ble
+ * @param[ref] _ble
* BLE object for the underlying controller.
* @param[in] level
* 8bit batterly level. Usually used to represent percentage of batterly charge remaining.
@@ -45,7 +45,7 @@
}
/**
- * @brief Update the battery level with a new value. Valid values lie between 0 and 100,
+ * @brief Update the battery level with a new value. [Valid values lie between 0 and 100];
* anything outside this range will be ignored.
*
* @param newLevel
@@ -57,20 +57,9 @@
}
protected:
- /**
- * A reference to the underlying BLE instance that this object is attached to.
- * The services and characteristics will be registered in this BLE instance.
- */
BLE &ble;
- /**
- * The current battery level represented as an integer from 0% to 100%.
- */
uint8_t batteryLevel;
- /**
- * A ReadOnlyGattCharacteristic that allows access to the peer device to the
- * batteryLevel value through BLE.
- */
ReadOnlyGattCharacteristic<uint8_t> batteryLevelCharacteristic;
};
--- a/ble/services/DeviceInformationService.h Wed Apr 06 19:14:32 2016 +0100
+++ b/ble/services/DeviceInformationService.h Wed Apr 06 19:14:34 2016 +0100
@@ -28,21 +28,21 @@
class DeviceInformationService {
public:
/**
- * @brief Device Information Service Constructor: copies device-specific information
+ * @brief Device Information Service Constructor: copies device-specific information
* into the BLE stack.
*
- * @param[in] _ble
- * A reference to a BLE object for the underlying controller.
+ * @param[ref] _ble
+ * BLE object for the underlying controller.
* @param[in] manufacturersName
* The name of the manufacturer of the device.
* @param[in] modelNumber
* The model number that is assigned by the device vendor.
* @param[in] serialNumber
- * The serial number for a particular instance of the device.
+ * The serial number for a particular instance of the device.
* @param[in] hardwareRevision
* The hardware revision for the hardware within the device.
* @param[in] firmwareRevision
- * The device's firmware version.
+ * The device's firmware version.
* @param[in] softwareRevision
* The device's software version.
*/
@@ -104,34 +104,12 @@
}
protected:
- /**
- * A reference to the BLE instance object to which the services and
- * characteristics will be added.
- */
BLE &ble;
- /**
- * BLE characterising to allow BLE peers access to the manufacturer's name.
- */
GattCharacteristic manufacturersNameStringCharacteristic;
- /**
- * BLE characterising to allow BLE peers access to the model number.
- */
GattCharacteristic modelNumberStringCharacteristic;
- /**
- * BLE characterising to allow BLE peers access to the serial number.
- */
GattCharacteristic serialNumberStringCharacteristic;
- /**
- * BLE characterising to allow BLE peers access to the hardware revision string.
- */
GattCharacteristic hardwareRevisionStringCharacteristic;
- /**
- * BLE characterising to allow BLE peers access to the firmware revision string.
- */
GattCharacteristic firmwareRevisionStringCharacteristic;
- /**
- * BLE characterising to allow BLE peers access to the software revision string.
- */
GattCharacteristic softwareRevisionStringCharacteristic;
};
--- a/module.json Wed Apr 06 19:14:32 2016 +0100
+++ b/module.json Wed Apr 06 19:14:34 2016 +0100
@@ -1,6 +1,6 @@
{
"name": "ble",
- "version": "2.4.0",
+ "version": "2.5.0",
"description": "The BLE module offers a high level abstraction for using Bluetooth Low Energy on multiple platforms.",
"keywords": [
"Bluetooth",