Alex Cordonnier
/
BLE_API
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of
BLE_API
by 
Bluetooth Low Energy
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",