Marco Ferreira
just a fork
Fork of
BLE_API
by 
Bluetooth Low Energy
Revision 1156:e1ea38b576c6, committed 2016-04-06
- Comitter:
- vcoubard
- Date:
- Wed Apr 06 19:14:38 2016 +0100
- Parent:
- 1155:e28c7aac64ab
- Child:
- 1157:a37be30efc66
- Commit message:
- Synchronized with git rev 5749d87d
Author: Andres Amaya Garcia
Add missing documentation to Gap.h and fix doxygen warnings
Changed in this revision
--- a/ble/BLE.h Wed Apr 06 19:14:34 2016 +0100
+++ b/ble/BLE.h Wed Apr 06 19:14:38 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,38 +138,70 @@
* This call allows the application to get the BLE stack version information.
*
* @return A pointer to a const string representing the version.
- * Note: The string is owned by BLE_API.
+ *
+ * @note The string returned is owned by BLE API.
*/
const char *getVersion(void);
- /*
- * Accessors to GAP. Please refer to Gap.h. All GAP related functionality requires
+ /**
+ * Accessor to Gap. All Gap related functionality requires
* going through this accessor.
+ *
+ * @return A reference to a Gap object associated to this BLE instance.
+ */
+ Gap &gap();
+
+ /**
+ * A const alternative to gap().
+ *
+ * @return A const reference to a Gap object associated to this BLE instance.
*/
const Gap &gap() const;
- Gap &gap();
- /*
- * Accessors to GATT Server. Please refer to GattServer.h. All GATTServer related
- * functionality requires going through this accessor.
+ /**
+ * Accessor to GattServer. All GattServer related functionality requires
+ * going through this accessor.
+ *
+ * @return A reference to a GattServer object associated to this BLE instance.
*/
- const GattServer& gattServer() const;
GattServer& gattServer();
- /*
- * Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related
- * functionality requires going through this accessor.
+ /**
+ * A const alternative to gattServer().
+ *
+ * @return A const reference to a GattServer object associated to this BLE instance.
*/
- const GattClient& gattClient() const;
+ const GattServer& gattServer() const;
+
+ /**
+ * Accessors to GattClient. All GattClient related functionality requires going
+ * through this accessor.
+ *
+ * @return A reference to a GattClient object associated to this BLE instance.
+ */
GattClient& gattClient();
- /*
- * Accessors to Security Manager. Please refer to SecurityManager.h. All
- * SecurityManager related functionality requires going through this
- * accessor.
+ /**
+ * A const alternative to gattClient().
+ *
+ * @return A const reference to a GattClient object associated to this BLE instance.
+ */
+ const GattClient& gattClient() const;
+
+ /**
+ * Accessors to SecurityManager. All SecurityManager related functionality requires
+ * going through this accessor.
+ *
+ * @return A reference to a SecurityManager object associated to this BLE instance.
+ */
+ SecurityManager& securityManager();
+
+ /**
+ * A const alternative to securityManager().
+ *
+ * @return A const reference to a SecurityManager object associated to this BLE instance.
*/
const SecurityManager& securityManager() const;
- SecurityManager& securityManager();
/**
* Yield control to the BLE stack or to other tasks waiting for events. This
@@ -181,10 +213,19 @@
void waitForEvent(void);
public:
+ /**
+ * The value of the BLE::InstanceID_t for the default BLE instance.
+ */
static const InstanceID_t DEFAULT_INSTANCE = 0;
#ifndef YOTTA_CFG_BLE_INSTANCES_COUNT
+ /**
+ * The number of permitted BLE instances for the application.
+ */
static const InstanceID_t NUM_INSTANCES = 1;
#else
+ /**
+ * The number of permitted BLE instances for the application.
+ */
static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT;
#endif
@@ -192,14 +233,14 @@
* Get a reference to the BLE singleton corresponding to a given interface.
* There is a static array of BLE singletons.
*
- * @Note: Calling Instance() is preferred over constructing a BLE object
+ * @note Calling Instance() is preferred over constructing a BLE object
* directly, as it returns references to singletons.
*
* @param[in] id
* Instance-ID. This should be less than NUM_INSTANCES
* for the returned BLE singleton to be useful.
*
- * @return a reference to a single object.
+ * @return A reference to a single object.
*/
static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE);
@@ -234,23 +275,21 @@
* Set the BTLE MAC address and type.
* @return BLE_ERROR_NONE on success.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAddress(...) should be replaced with
- * ble.gap().setAddress(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setAddress(...) should be replaced with
+ * ble.gap().setAddress(...).
*/
ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
return gap().setAddress(type, address);
}
/**
- * Fetch the BTLE MAC address and type.
+ * Fetch the Bluetooth Low Energy MAC address and type.
* @return BLE_ERROR_NONE on success.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getAddress(...) should be replaced with
- * ble.gap().getAddress(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getAddress(...) should be replaced with
+ * ble.gap().getAddress(...).
*/
ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
return gap().getAddress(typeP, address);
@@ -259,10 +298,9 @@
/**
* Set the GAP advertising mode to use for this device.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingType(...) should be replaced with
- * ble.gap().setAdvertisingType(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setAdvertisingType(...) should be replaced with
+ * ble.gap().setAdvertisingType(...).
*/
void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
gap().setAdvertisingType(advType);
@@ -279,16 +317,15 @@
* This field must be set to 0 if connectionMode is equal
* to ADV_CONNECTABLE_DIRECTED.
*
- * @note: Decreasing this value allows central devices to detect a
+ * @note Decreasing this value allows central devices to detect a
* peripheral faster, at the expense of more power being used by the radio
* due to the higher data transmit rate.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingInterval(...) should be replaced with
- * ble.gap().setAdvertisingInterval(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setAdvertisingInterval(...) should be replaced with
+ * ble.gap().setAdvertisingInterval(...).
*
- * @note: [WARNING] This API previously used 0.625ms as the unit for its
+ * @note WARNING: This API previously used 0.625ms as the unit for its
* 'interval' argument. That required an explicit conversion from
* milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
* no longer required as the new units are milliseconds. Any application
@@ -301,10 +338,9 @@
/**
* @return Minimum Advertising interval in milliseconds.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getMinAdvertisingInterval(...) should be replaced with
- * ble.gap().getMinAdvertisingInterval(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getMinAdvertisingInterval(...) should be replaced with
+ * ble.gap().getMinAdvertisingInterval(...).
*/
uint16_t getMinAdvertisingInterval(void) const {
return gap().getMinAdvertisingInterval();
@@ -313,10 +349,9 @@
/**
* @return Minimum Advertising interval in milliseconds for non-connectible mode.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
- * ble.gap().getMinNonConnectableAdvertisingInterval(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
+ * ble.gap().getMinNonConnectableAdvertisingInterval(...).
*/
uint16_t getMinNonConnectableAdvertisingInterval(void) const {
return gap().getMinNonConnectableAdvertisingInterval();
@@ -325,10 +360,9 @@
/**
* @return Maximum Advertising interval in milliseconds.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getMaxAdvertisingInterval(...) should be replaced with
- * ble.gap().getMaxAdvertisingInterval(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getMaxAdvertisingInterval(...) should be replaced with
+ * ble.gap().getMaxAdvertisingInterval(...).
*/
uint16_t getMaxAdvertisingInterval(void) const {
return gap().getMaxAdvertisingInterval();
@@ -339,10 +373,9 @@
* Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
* and 16383). Use 0 to disable the advertising timeout.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingTimeout(...) should be replaced with
- * ble.gap().setAdvertisingTimeout(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setAdvertisingTimeout(...) should be replaced with
+ * ble.gap().setAdvertisingTimeout(...).
*/
void setAdvertisingTimeout(uint16_t timeout) {
gap().setAdvertisingTimeout(timeout);
@@ -354,10 +387,9 @@
* directly; there are other APIs to tweak advertisement parameters
* individually (see above).
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingParams(...) should be replaced with
- * ble.gap().setAdvertisingParams(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setAdvertisingParams(...) should be replaced with
+ * ble.gap().setAdvertisingParams(...).
*/
void setAdvertisingParams(const GapAdvertisingParams &advParams) {
gap().setAdvertisingParams(advParams);
@@ -367,10 +399,9 @@
* @return Read back advertising parameters. Useful for storing and
* restoring parameters rapidly.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getAdvertisingParams(...) should be replaced with
- * ble.gap().getAdvertisingParams(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getAdvertisingParams(...) should be replaced with
+ * ble.gap().getAdvertisingParams(...).
*/
const GapAdvertisingParams &getAdvertisingParams(void) const {
return gap().getAdvertisingParams();
@@ -387,10 +418,9 @@
* GapAdvertisingData::Flags for valid flags. Multiple
* flags may be specified in combination.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayload(flags) should be replaced with
- * ble.gap().accumulateAdvertisingPayload(flags).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.accumulateAdvertisingPayload(flags) should be replaced with
+ * ble.gap().accumulateAdvertisingPayload(flags).
*/
ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
return gap().accumulateAdvertisingPayload(flags);
@@ -405,10 +435,9 @@
* @param[in] app
* The appearance of the peripheral.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayload(appearance) should be replaced with
- * ble.gap().accumulateAdvertisingPayload(appearance).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.accumulateAdvertisingPayload(appearance) should be replaced with
+ * ble.gap().accumulateAdvertisingPayload(appearance).
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
return gap().accumulateAdvertisingPayload(app);
@@ -420,14 +449,13 @@
* as an additional 31 bytes if the advertising payload is too
* small.
*
- * @param[in] app
+ * @param[in] power
* The max transmit power to be used by the controller. This
* is only a hint.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
- * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
+ * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
*/
ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
return gap().accumulateAdvertisingPayloadTxPower(power);
@@ -443,10 +471,9 @@
* @param data Data bytes.
* @param len Data length.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.accumulateAdvertisingPayload(...) should be replaced with
- * ble.gap().accumulateAdvertisingPayload(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.accumulateAdvertisingPayload(...) should be replaced with
+ * ble.gap().accumulateAdvertisingPayload(...).
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
return gap().accumulateAdvertisingPayload(type, data, len);
@@ -457,10 +484,9 @@
* underlying stack. It would be uncommon for this API to be used directly;
* there are other APIs to build an advertisement payload (see above).
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAdvertisingData(...) should be replaced with
- * ble.gap().setAdvertisingPayload(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setAdvertisingData(...) should be replaced with
+ * ble.gap().setAdvertisingPayload(...).
*/
ble_error_t setAdvertisingData(const GapAdvertisingData &advData) {
return gap().setAdvertisingPayload(advData);
@@ -470,10 +496,9 @@
* @return Read back advertising data. Useful for storing and
* restoring payload.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getAdvertisingData(...) should be replaced with
- * ble.gap().getAdvertisingPayload()(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getAdvertisingData(...) should be replaced with
+ * ble.gap().getAdvertisingPayload()(...).
*/
const GapAdvertisingData &getAdvertisingData(void) const {
return gap().getAdvertisingPayload();
@@ -484,24 +509,25 @@
* accumulateAdvertisingPayload(). This automatically propagates the re-
* initialized advertising payload to the underlying stack.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.clearAdvertisingPayload(...) should be replaced with
- * ble.gap().clearAdvertisingPayload(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.clearAdvertisingPayload(...) should be replaced with
+ * ble.gap().clearAdvertisingPayload(...).
*/
void clearAdvertisingPayload(void) {
gap().clearAdvertisingPayload();
}
/**
- * This API is *deprecated* and resolves to a no-operation. It is left here
- * to allow older code to compile. Please avoid using this API in new code.
- * This API will be dropped in a future release.
+ * Dynamically reset the accumulated advertising
+ * payload and scanResponse. The application must clear and re-
+ * accumulates a new advertising payload (and scanResponse) before using this
+ * API.
*
- * Formerly, it would be used to dynamically reset the accumulated advertising
- * payload and scanResponse; to do this, the application would clear and re-
- * accumulate a new advertising payload (and scanResponse) before using this
- * API. Updates to the underlying advertisement payload now happen
+ * @return BLE_ERROR_NONE when the advertising payload is set successfully.
+ *
+ * @deprecated You should use the parallel API from Gap directly.
+ *
+ * @note The new APIs in Gap update the underlying advertisement payload
* implicitly.
*/
ble_error_t setAdvertisingPayload(void) {
@@ -516,10 +542,9 @@
* @param[in] data Data bytes.
* @param[in] len Data length.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.accumulateScanResponse(...) should be replaced with
- * ble.gap().accumulateScanResponse(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.accumulateScanResponse(...) should be replaced with
+ * ble.gap().accumulateScanResponse(...).
*/
ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
return gap().accumulateScanResponse(type, data, len);
@@ -529,10 +554,9 @@
* Reset any scan response prepared from prior calls to
* accumulateScanResponse().
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.clearScanResponse(...) should be replaced with
- * ble.gap().clearScanResponse(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.clearScanResponse(...) should be replaced with
+ * ble.gap().clearScanResponse(...).
*/
void clearScanResponse(void) {
gap().clearScanResponse();
@@ -541,10 +565,9 @@
/**
* Start advertising.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.startAdvertising(...) should be replaced with
- * ble.gap().startAdvertising(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.startAdvertising(...) should be replaced with
+ * ble.gap().startAdvertising(...).
*/
ble_error_t startAdvertising(void) {
return gap().startAdvertising();
@@ -553,10 +576,9 @@
/**
* Stop advertising.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.stopAdvertising(...) should be replaced with
- * ble.gap().stopAdvertising(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.stopAdvertising(...) should be replaced with
+ * ble.gap().stopAdvertising(...).
*/
ble_error_t stopAdvertising(void) {
return gap().stopAdvertising();
@@ -584,12 +606,11 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @Note: The scan interval and window are recommendations to the BLE stack.
+ * @note The scan interval and window are recommendations to the BLE stack.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setScanParams(...) should be replaced with
- * ble.gap().setScanParams(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setScanParams(...) should be replaced with
+ * ble.gap().setScanParams(...).
*/
ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
@@ -613,10 +634,9 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setScanInterval(interval) should be replaced with
- * ble.gap().setScanInterval(interval).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setScanInterval(interval) should be replaced with
+ * ble.gap().setScanInterval(interval).
*/
ble_error_t setScanInterval(uint16_t interval) {
return gap().setScanInterval(interval);
@@ -637,10 +657,9 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setScanWindow(window) should be replaced with
- * ble.gap().setScanWindow(window).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setScanWindow(window) should be replaced with
+ * ble.gap().setScanWindow(window).
*/
ble_error_t setScanWindow(uint16_t window) {
return gap().setScanWindow(window);
@@ -661,12 +680,11 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @Note: The scan interval and window are recommendations to the BLE stack.
+ * @note The scan interval and window are recommendations to the BLE stack.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setScanTimeout(...) should be replaced with
- * ble.gap().setScanTimeout(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setScanTimeout(...) should be replaced with
+ * ble.gap().setScanTimeout(...).
*/
ble_error_t setScanTimeout(uint16_t timeout) {
return gap().setScanTimeout(timeout);
@@ -681,10 +699,9 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setActiveScan(...) should be replaced with
- * ble.gap().setActiveScanning(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setActiveScan(...) should be replaced with
+ * ble.gap().setActiveScanning(...).
*/
void setActiveScan(bool activeScanning) {
gap().setActiveScanning(activeScanning);
@@ -699,10 +716,9 @@
* receiving every advertisement report. This can be passed in
* as NULL, in which case scanning may not be enabled at all.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.startScan(callback) should be replaced with
- * ble.gap().startScan(callback).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.startScan(callback) should be replaced with
+ * ble.gap().startScan(callback).
*/
ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) {
return gap().startScan(callback);
@@ -711,10 +727,9 @@
/**
* Same as above, but this takes an (object, method) pair for a callback.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.startScan(callback) should be replaced with
- * ble.gap().startScan(object, callback).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.startScan(callback) should be replaced with
+ * ble.gap().startScan(object, callback).
*/
template<typename T>
ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
@@ -724,10 +739,9 @@
*
* @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.stopScan() should be replaced with
- * ble.gap().stopScan().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.stopScan() should be replaced with
+ * ble.gap().stopScan().
*/
ble_error_t stopScan(void) {
return gap().stopScan();
@@ -747,10 +761,9 @@
* successfully. The onConnection callback (if set) is invoked upon
* a connection event.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.connect(...) should be replaced with
- * ble.gap().connect(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.connect(...) should be replaced with
+ * ble.gap().connect(...).
*/
ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
@@ -780,28 +793,27 @@
* @param reason
* The reason for disconnection; sent back to the peer.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.disconnect(reason) should be replaced with
- * ble.gap().disconnect(reason).
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.disconnect(reason) should be replaced with
+ * ble.gap().disconnect(reason).
*
- * @note: This version of disconnect() doesn't take a connection handle. It
+ * @note This version of disconnect() doesn't take a connection handle. It
* works reliably only for stacks that are limited to a single
- * connection. This API should be considered *deprecated* in favour of the
- * alternative, which takes a connection handle. It will be dropped in the future.
+ * connection.
+ *
+ * @deprecated You should use the parallel API from Gap directly.
*/
ble_error_t disconnect(Gap::DisconnectionReason_t reason) {
return gap().disconnect(reason);
}
/**
- * Returns the current GAP state of the device using a bitmask that
+ * Returns the current Gap state of the device using a bitmask that
* describes whether the device is advertising or connected.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getGapState() should be replaced with
- * ble.gap().getState().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getGapState() should be replaced with
+ * ble.gap().getState().
*/
Gap::GapState_t getGapState(void) const {
return gap().getState();
@@ -819,10 +831,9 @@
* @return BLE_ERROR_NONE if the parameters were successfully filled into
* the given structure pointed to by params.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getPreferredConnectionParams() should be replaced with
- * ble.gap().getPreferredConnectionParams().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getPreferredConnectionParams() should be replaced with
+ * ble.gap().getPreferredConnectionParams().
*/
ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) {
return gap().getPreferredConnectionParams(params);
@@ -836,10 +847,9 @@
* @param[in] params
* The structure containing the desired parameters.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setPreferredConnectionParams() should be replaced with
- * ble.gap().setPreferredConnectionParams().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setPreferredConnectionParams() should be replaced with
+ * ble.gap().setPreferredConnectionParams().
*/
ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) {
return gap().setPreferredConnectionParams(params);
@@ -855,38 +865,36 @@
* Pointer to desired connection parameters. If NULL is provided on a peripheral role,
* the parameters in the PPCP characteristic of the GAP service will be used instead.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.updateConnectionParams() should be replaced with
- * ble.gap().updateConnectionParams().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.updateConnectionParams() should be replaced with
+ * ble.gap().updateConnectionParams().
*/
ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
return gap().updateConnectionParams(handle, params);
}
/**
- * Set the device name characteristic in the GAP service.
+ * Set the device name characteristic in the Gap service.
* @param[in] deviceName
* The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setDeviceName() should be replaced with
- * ble.gap().setDeviceName().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setDeviceName() should be replaced with
+ * ble.gap().setDeviceName().
*/
ble_error_t setDeviceName(const uint8_t *deviceName) {
return gap().setDeviceName(deviceName);
}
/**
- * Get the value of the device name characteristic in the GAP service.
+ * Get the value of the device name characteristic in the Gap service.
* @param[out] deviceName
* Pointer to an empty buffer where the UTF-8 *non NULL-
* terminated* string will be placed. Set this
* value to NULL in order to obtain the deviceName-length
* from the 'length' parameter.
*
- * @param[in/out] lengthP
+ * @param[in,out] lengthP
* (on input) Length of the buffer pointed to by deviceName;
* (on output) the complete device name length (without the
* null terminator).
@@ -896,38 +904,35 @@
* number of bytes actually returned in deviceName. The application may
* use this information to retry with a suitable buffer size.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getDeviceName() should be replaced with
- * ble.gap().getDeviceName().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getDeviceName() should be replaced with
+ * ble.gap().getDeviceName().
*/
ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
return gap().getDeviceName(deviceName, lengthP);
}
/**
- * Set the appearance characteristic in the GAP service.
+ * Set the appearance characteristic in the Gap service.
* @param[in] appearance
* The new value for the device-appearance.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setAppearance() should be replaced with
- * ble.gap().setAppearance().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setAppearance() should be replaced with
+ * ble.gap().setAppearance().
*/
ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
return gap().setAppearance(appearance);
}
/**
- * Get the appearance characteristic in the GAP service.
- * @param[out] appearance
+ * Get the appearance characteristic in the Gap service.
+ * @param[out] appearanceP
* The new value for the device-appearance.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getAppearance() should be replaced with
- * ble.gap().getAppearance().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getAppearance() should be replaced with
+ * ble.gap().getAppearance().
*/
ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
return gap().getAppearance(appearanceP);
@@ -937,10 +942,9 @@
* Set the radio's transmit power.
* @param[in] txPower Radio transmit power in dBm.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.setTxPower() should be replaced with
- * ble.gap().setTxPower().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.setTxPower() should be replaced with
+ * ble.gap().setTxPower().
*/
ble_error_t setTxPower(int8_t txPower) {
return gap().setTxPower(txPower);
@@ -954,10 +958,9 @@
* @param[out] countP
* Out parameter to receive the array's size.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call to
- * ble.getPermittedTxPowerValues() should be replaced with
- * ble.gap().getPermittedTxPowerValues().
+ * @deprecated You should use the parallel API from Gap directly. A former call to
+ * ble.getPermittedTxPowerValues() should be replaced with
+ * ble.gap().getPermittedTxPowerValues().
*/
void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
gap().getPermittedTxPowerValues(valueArrayPP, countP);
@@ -967,10 +970,9 @@
* Add a service declaration to the local server ATT table. Also add the
* characteristics contained within.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.addService() should be replaced with
- * ble.gattServer().addService().
+ * @deprecated You should use the parallel API from GattServer directly. A former call
+ * to ble.addService() should be replaced with
+ * ble.gattServer().addService().
*/
ble_error_t addService(GattService &service) {
return gattServer().addService(service);
@@ -982,7 +984,7 @@
* Attribute handle for the value attribute of the characteristic.
* @param[out] buffer
* A buffer to hold the value being read.
- * @param[in/out] lengthP
+ * @param[in,out] lengthP
* Length of the buffer being supplied. If the attribute
* value is longer than the size of the supplied buffer,
* this variable will return the total attribute value length
@@ -991,10 +993,9 @@
*
* @return BLE_ERROR_NONE if a value was read successfully into the buffer.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.readCharacteristicValue() should be replaced with
- * ble.gattServer().read().
+ * @deprecated You should use the parallel API from GattServer directly. A former call
+ * to ble.readCharacteristicValue() should be replaced with
+ * ble.gattServer().read().
*/
ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
return gattServer().read(attributeHandle, buffer, lengthP);
@@ -1008,7 +1009,7 @@
* Attribute handle for the value attribute of the characteristic.
* @param[out] buffer
* A buffer to hold the value being read.
- * @param[in/out] lengthP
+ * @param[in,out] lengthP
* Length of the buffer being supplied. If the attribute
* value is longer than the size of the supplied buffer,
* this variable will return the total attribute value length
@@ -1021,10 +1022,9 @@
* parameter to allow fetches for connection-specific multivalued
* attributes (such as the CCCDs).
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.readCharacteristicValue() should be replaced with
- * ble.gattServer().read().
+ * @deprecated You should use the parallel API from GattServer directly. A former call
+ * to ble.readCharacteristicValue() should be replaced with
+ * ble.gattServer().read().
*/
ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP);
@@ -1048,10 +1048,9 @@
*
* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.updateCharacteristicValue() should be replaced with
- * ble.gattServer().write().
+ * @deprecated You should use the parallel API from GattServer directly. A former call
+ * to ble.updateCharacteristicValue() should be replaced with
+ * ble.gattServer().write().
*/
ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle,
const uint8_t *value,
@@ -1082,10 +1081,9 @@
*
* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.updateCharacteristicValue() should be replaced with
- * ble.gattServer().write().
+ * @deprecated You should use the parallel API from GattServer directly. A former call
+ * to ble.updateCharacteristicValue() should be replaced with
+ * ble.gattServer().write().
*/
ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle,
GattAttribute::Handle_t attributeHandle,
@@ -1110,10 +1108,9 @@
*
* @return BLE_ERROR_NONE on success.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.initializeSecurity(...) should be replaced with
- * ble.securityManager().init(...).
+ * @deprecated You should use the parallel API from SecurityManager directly. A former
+ * call to ble.initializeSecurity(...) should be replaced with
+ * ble.securityManager().init(...).
*/
ble_error_t initializeSecurity(bool enableBonding = true,
bool requireMITM = true,
@@ -1130,10 +1127,9 @@
*
* @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.getLinkSecurity(...) should be replaced with
- * ble.securityManager().getLinkSecurity(...).
+ * @deprecated You should use the parallel API from SecurityManager directly. A former
+ * call to ble.getLinkSecurity(...) should be replaced with
+ * ble.securityManager().getLinkSecurity(...).
*/
ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) {
return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
@@ -1147,10 +1143,9 @@
* @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
* application registration.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.purgeAllBondingState() should be replaced with
- * ble.securityManager().purgeAllBondingState().
+ * @deprecated You should use the parallel API from SecurityManager directly. A former
+ * call to ble.purgeAllBondingState() should be replaced with
+ * ble.securityManager().purgeAllBondingState().
*/
ble_error_t purgeAllBondingState(void) {
return securityManager().purgeAllBondingState();
@@ -1160,10 +1155,9 @@
* Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
* possible event types.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call
- * to ble.onTimeout(callback) should be replaced with
- * ble.gap().onTimeout(callback).
+ * @deprecated You should use the parallel API from Gap directly. A former call
+ * to ble.onTimeout(callback) should be replaced with
+ * ble.gap().onTimeout(callback).
*/
void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) {
gap().onTimeout(timeoutCallback);
@@ -1172,10 +1166,9 @@
/**
* Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call
- * to ble.onConnection(callback) should be replaced with
- * ble.gap().onConnection(callback).
+ * @deprecated You should use the parallel API from Gap directly. A former call
+ * to ble.onConnection(callback) should be replaced with
+ * ble.gap().onConnection(callback).
*/
void onConnection(Gap::ConnectionEventCallback_t connectionCallback) {
gap().onConnection(connectionCallback);
@@ -1184,15 +1177,22 @@
/**
* Append to a chain of callbacks to be invoked upon GAP disconnection.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call
- * to ble.onDisconnection(callback) should be replaced with
- * ble.gap().onDisconnection(callback).
+ * @deprecated You should use the parallel API from Gap directly. 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,10 +1214,9 @@
* The application handler to be invoked in response to a radio
* ACTIVE/INACTIVE event.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from Gap directly. A former call
- * to ble.onRadioNotification(...) should be replaced with
- * ble.gap().onRadioNotification(...).
+ * @deprecated You should use the parallel API from Gap directly. A former call
+ * to ble.onRadioNotification(...) should be replaced with
+ * ble.gap().onRadioNotification(...).
*/
void onRadioNotification(void (*callback)(bool)) {
gap().onRadioNotification(callback);
@@ -1227,21 +1226,29 @@
* Add a callback for the GATT event DATA_SENT (which is triggered when
* updates are sent out by GATT in the form of notifications).
*
- * @Note: It is possible to chain together multiple onDataSent callbacks
+ * @note It is possible to chain together multiple onDataSent callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics.
*
- * @Note: It is also possible to set up a callback into a member function of
+ * @note It is also possible to set up a callback into a member function of
* some object.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onDataSent(...) should be replaced with
- * ble.gattServer().onDataSent(...).
+ * @deprecated You should use the parallel API from GattServer directly. 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);
}
@@ -1253,22 +1260,30 @@
* For a Central, this callback is triggered when a response is received for
* a write request.
*
- * @Note: It is possible to chain together multiple onDataWritten callbacks
+ * @note It is possible to chain together multiple onDataWritten callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics. Many services, such as DFU and UART, add their own
* onDataWritten callbacks behind the scenes to trap interesting events.
*
- * @Note: It is also possible to set up a callback into a member function of
+ * @note It is also possible to set up a callback into a member function of
* some object.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onDataWritten(...) should be replaced with
- * ble.gattServer().onDataWritten(...).
+ * @deprecated You should use the parallel API from GattServer directly. 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);
}
@@ -1277,29 +1292,37 @@
* Set up a callback to be invoked on the peripheral when an attribute is
* being read by a remote client.
*
- * @Note: This functionality may not be available on all underlying stacks.
+ * @note This functionality may not be available on all underlying stacks.
* You could use GattCharacteristic::setReadAuthorizationCallback() as an
* alternative.
*
- * @Note: It is possible to chain together multiple onDataRead callbacks
+ * @note It is possible to chain together multiple onDataRead callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics. Services may add their own onDataRead callbacks
* behind the scenes to trap interesting events.
*
- * @Note: It is also possible to set up a callback into a member function of
+ * @note It is also possible to set up a callback into a member function of
* some object.
*
* @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
* else BLE_ERROR_NONE.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onDataRead(...) should be replaced with
- * ble.gattServer().onDataRead(...).
+ * @deprecated You should use the parallel API from GattServer directly. 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);
}
@@ -1308,10 +1331,9 @@
* Set up a callback for when notifications or indications are enabled for a
* characteristic on the local GattServer.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onUpdatesEnabled(callback) should be replaced with
- * ble.gattServer().onUpdatesEnabled(callback).
+ * @deprecated You should use the parallel API from GattServer directly. A former call
+ * to ble.onUpdatesEnabled(callback) should be replaced with
+ * ble.gattServer().onUpdatesEnabled(callback).
*/
void onUpdatesEnabled(GattServer::EventCallback_t callback) {
gattServer().onUpdatesEnabled(callback);
@@ -1321,10 +1343,9 @@
* Set up a callback for when notifications or indications are disabled for a
* characteristic on the local GattServer.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onUpdatesEnabled(callback) should be replaced with
- * ble.gattServer().onUpdatesEnabled(callback).
+ * @deprecated You should use the parallel API from GattServer directly. A former call
+ * to ble.onUpdatesEnabled(callback) should be replaced with
+ * ble.gattServer().onUpdatesEnabled(callback).
*/
void onUpdatesDisabled(GattServer::EventCallback_t callback) {
gattServer().onUpdatesDisabled(callback);
@@ -1334,10 +1355,9 @@
* Set up a callback for when the GATT server receives a response for an
* indication event sent previously.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from GattServer directly. A former call
- * to ble.onConfirmationReceived(callback) should be replaced with
- * ble.gattServer().onConfirmationReceived(callback).
+ * @deprecated You should use the parallel API from GattServer directly. A former call
+ * to ble.onConfirmationReceived(callback) should be replaced with
+ * ble.gattServer().onConfirmationReceived(callback).
*/
void onConfirmationReceived(GattServer::EventCallback_t callback) {
gattServer().onConfirmationReceived(callback);
@@ -1350,10 +1370,9 @@
* security request: bool allowBonding, bool requireMITM, and
* SecurityIOCapabilities_t.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.onSecuritySetupInitiated(callback) should be replaced with
- * ble.securityManager().onSecuritySetupInitiated(callback).
+ * @deprecated You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onSecuritySetupInitiated(callback) should be replaced with
+ * ble.securityManager().onSecuritySetupInitiated(callback).
*/
void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
securityManager().onSecuritySetupInitiated(callback);
@@ -1365,10 +1384,9 @@
* devices. The callback is passed in the success/failure status of the
* security setup procedure.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.onSecuritySetupCompleted(callback) should be replaced with
- * ble.securityManager().onSecuritySetupCompleted(callback).
+ * @deprecated You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onSecuritySetupCompleted(callback) should be replaced with
+ * ble.securityManager().onSecuritySetupCompleted(callback).
*/
void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
securityManager().onSecuritySetupCompleted(callback);
@@ -1382,10 +1400,9 @@
* or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
* to the level of security in effect for the secured link.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.onLinkSecured(callback) should be replaced with
- * ble.securityManager().onLinkSecured(callback).
+ * @deprecated You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onLinkSecured(callback) should be replaced with
+ * ble.securityManager().onLinkSecured(callback).
*/
void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
securityManager().onLinkSecured(callback);
@@ -1395,10 +1412,9 @@
* Set up a callback for successful bonding, meaning that link-specific security
* context is stored persistently for a peer device.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.onSecurityContextStored(callback) should be replaced with
- * ble.securityManager().onSecurityContextStored(callback).
+ * @deprecated You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onSecurityContextStored(callback) should be replaced with
+ * ble.securityManager().onSecurityContextStored(callback).
*/
void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
securityManager().onSecurityContextStored(callback);
@@ -1411,10 +1427,9 @@
* a passkey (or PIN) to authenticate the connection
* attempt.
*
- * @note: This API is now *deprecated* and will be dropped in the future.
- * You should use the parallel API from SecurityManager directly. A former
- * call to ble.onPasskeyDisplay(callback) should be replaced with
- * ble.securityManager().onPasskeyDisplay(callback).
+ * @deprecated You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onPasskeyDisplay(callback) should be replaced with
+ * ble.securityManager().onPasskeyDisplay(callback).
*/
void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
return securityManager().onPasskeyDisplay(callback);
@@ -1438,7 +1453,8 @@
BLEInstanceBase *transport; /* The device-specific backend */
};
-typedef BLE BLEDevice; /* DEPRECATED. This type alias is retained for the sake of compatibility with older
+typedef BLE BLEDevice; /**< @deprecated This type alias is retained for the
+ * sake of compatibility with older
* code. Will be dropped at some point soon.*/
#endif // ifndef __BLE_H__
\ No newline at end of file
--- a/ble/BLEInstanceBase.h Wed Apr 06 19:14:34 2016 +0100
+++ b/ble/BLEInstanceBase.h Wed Apr 06 19:14:38 2016 +0100
@@ -32,18 +32,104 @@
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:34 2016 +0100
+++ b/ble/CallChainOfFunctionPointersWithContext.h Wed Apr 06 19:14:38 2016 +0100
@@ -55,16 +55,17 @@
* }
* @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.
- *
- * @param size (optional) Initial size of the chain.
+ /**
+ * Create an empty chain.
*/
CallChainOfFunctionPointersWithContext() : chainHead(NULL) {
/* empty */
@@ -74,58 +75,66 @@
clear();
}
- /** Add a function at the front of the chain.
+ /**
+ * Add a function at the front of the chain.
*
- * @param function A pointer to a void function.
+ * @param[in] function
+ * A pointer to a void function.
*
- * @returns
- * The function object created for 'function'.
+ * @return The function object created for @p 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 tptr Pointer to the object to call the member function on.
- * @param mptr Pointer to the member function to be called.
+ * @param[in] tptr
+ * Pointer to the object to call the member function on.
+ * @param[in] mptr
+ * Pointer to the member function to be called.
*
- * @returns
- * The function object created for 'tptr' and 'mptr'.
+ * @return The function object created for @p tptr and @p 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 func The FunctionPointerWithContext to add.
+ * @param[in] func
+ * The FunctionPointerWithContext to add.
+ *
+ * @return The function object created for @p func.
*/
pFunctionPointerWithContext_t add(const FunctionPointerWithContext<ContextType>& func) {
return common_add(new FunctionPointerWithContext<ContextType>(func));
}
- /**
- * 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) {
+ /**
+ * 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) {
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());
@@ -141,7 +150,8 @@
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;
@@ -154,26 +164,32 @@
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);
}
/**
- * @brief same as above but const
+ * Same as call() 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();
@@ -182,34 +198,41 @@
}
/**
- * @brief same as above but with function call operator
- * \code
- *
+ * Same as call(), 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);
}
/**
- * @brief bool conversion operation
+ * Bool conversion operation.
+ *
+ * @return true if the callchain is not empty and false otherwise.
*/
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;
@@ -222,10 +245,17 @@
}
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 leak outside the object.
- // So the object can still be seen as logically const even if it change its internal state
+
+ /**
+ * 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.
+ */
mutable pFunctionPointerWithContext_t currentCalled;
--- a/ble/CharacteristicDescriptorDiscovery.h Wed Apr 06 19:14:34 2016 +0100
+++ b/ble/CharacteristicDescriptorDiscovery.h Wed Apr 06 19:14:38 2016 +0100
@@ -36,7 +36,7 @@
public:
/**
* @brief Parameter type of CharacteristicDescriptorDiscovery::DiscoveryCallback_t.
- * @detail Every time a characteristic descriptor has been discovered, the callback
+ * @details 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:34 2016 +0100
+++ b/ble/DiscoveredCharacteristic.h Wed Apr 06 19:14:38 2016 +0100
@@ -28,7 +28,7 @@
* @brief Representation of a characteristic discovered during a GattClient
* discovery procedure (see GattClient::launchServiceDiscovery ).
*
- * @detail Provide detailed informations about a discovered characteristic like:
+ * @details 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,19 +52,88 @@
uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
public:
- 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 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;
+ }
/**
* @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t
*
- * @param lhs[in] The left hand side of the equality expression
- * @param rhs[in] The right hand side of the equality expression
+ * @param[in] lhs The left hand side of the equality expression
+ * @param[in] rhs The right hand side of the equality expression
*
* @return true if operands are equals, false otherwise.
*/
@@ -101,8 +170,9 @@
* than ATT_MTU - 1, this function must be called multiple times with
* appropriate offset to read the complete value.
*
- * @param offset[in] The position - in the characteristic value bytes stream - where
- * the read operation begin.
+ * @param[in] offset
+ * 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
@@ -115,9 +185,11 @@
* @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 offset[in] The position - in the characteristic value bytes stream - where
- * the read operation begin.
- * @param onRead[in] Continuation of the read operation
+ * @param[in] offset
+ * The position - in the characteristic value bytes stream - where
+ * the read operation begin.
+ * @param[in] onRead
+ * Continuation of the read operation
*/
ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const;
@@ -174,12 +246,21 @@
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] onRead Continuation callback for the write operation
+ * @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.
*/
ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onWrite) const;
@@ -206,7 +287,7 @@
/**
* @brief Get the declaration handle of this characteristic.
- * @detail The declaration handle is the first handle of a characteristic
+ * @details 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
@@ -275,8 +356,10 @@
/**
* @brief "Equal to" operator for DiscoveredCharacteristic
*
- * @param lhs[in] The left hand side of the equality expression
- * @param rhs[in] The right hand side of the equality expression
+ * @param[in] lhs
+ * The left hand side of the equality expression
+ * @param[in] rhs
+ * The right hand side of the equality expression
*
* @return true if operands are equals, false otherwise.
*/
@@ -293,10 +376,12 @@
/**
* @brief "Not equal to" operator for DiscoveredCharacteristic
*
- * @param lhs[in] The right hand side of the expression
- * @param rhs[in] The left hand side of the expression
+ * @param[in] lhs
+ * The right hand side of the expression
+ * @param[in] rhs
+ * The left hand side of the expression
*
- * @return true if operands are not equals, false otherwise.
+ * @return true if operands are not equal, false otherwise.
*/
friend bool operator !=(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) {
return !(lhs == rhs);
@@ -314,15 +399,37 @@
}
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:34 2016 +0100 +++ b/ble/DiscoveredCharacteristicDescriptor.h Wed Apr 06 19:14:38 2016 +0100 @@ -28,7 +28,7 @@ * discovery procedure (see GattClient::discoverCharacteristicDescriptors or * DiscoveredCharacteristic::discoverDescriptors ). * - * @detail Provide detailed informations about a discovered characteristic descriptor + * @details Provide detailed informations about a discovered characteristic descriptor * like: * - Its UUID (see #getUUID). * - Its handle (see #getAttributeHandle)
--- a/ble/Gap.h Wed Apr 06 19:14:34 2016 +0100
+++ b/ble/Gap.h Wed Apr 06 19:14:38 2016 +0100
@@ -40,23 +40,24 @@
/**
* Address-type for BLEProtocol addresses.
*
- * @note: deprecated. Use BLEProtocol::AddressType_t instead.
+ * @deprecated Use BLEProtocol::AddressType_t instead.
*/
typedef BLEProtocol::AddressType_t AddressType_t;
/**
* Address-type for BLEProtocol addresses.
- * @note: deprecated. Use BLEProtocol::AddressType_t instead.
+ *
+ * @deprecated Use BLEProtocol::AddressType_t instead.
*/
typedef BLEProtocol::AddressType_t addr_type_t;
/**
* Address-type for BLEProtocol addresses.
- * \deprecated: Use BLEProtocol::AddressType_t instead.
*
- * DEPRECATION ALERT: The following constants have been left in their
- * deprecated state to transparenly support existing applications which may
- * have used Gap::ADDR_TYPE_*.
+ * @deprecated Use BLEProtocol::AddressType_t instead. The following
+ * constants have been left in their deprecated state to
+ * transparenly support existing applications which may have
+ * used Gap::ADDR_TYPE_*.
*/
enum DeprecatedAddressType_t {
ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC,
@@ -65,11 +66,27 @@
ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE
};
- static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN; /**< Length (in octets) of the BLE MAC address. */
- typedef BLEProtocol::AddressBytes_t Address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::AddressBytes_t instead. */
- typedef BLEProtocol::AddressBytes_t address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::AddressBytes_t instead. */
+ /**
+ * Length (in octets) of the BLE MAC address.
+ */
+ static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN;
+ /**
+ * 48-bit address, LSB format.
+ *
+ * @deprecated Use BLEProtocol::AddressBytes_t instead.
+ */
+ typedef BLEProtocol::AddressBytes_t Address_t;
+ /**
+ * 48-bit address, LSB format.
+ *
+ * @deprecated Use BLEProtocol::AddressBytes_t instead.
+ */
+ typedef BLEProtocol::AddressBytes_t address_t;
public:
+ /**
+ * Enumeration for timeout sources.
+ */
enum TimeoutSource_t {
TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */
TIMEOUT_SRC_SECURITY_REQUEST = 0x01, /**< Security request timeout. */
@@ -137,51 +154,94 @@
* @experimental
*/
struct Whitelist_t {
- BLEProtocol::Address_t *addresses;
- uint8_t size;
- uint8_t capacity;
+ BLEProtocol::Address_t *addresses; /**< List of BLE addresses in the whitelist. */
+ uint8_t size; /**< Total number of BLE addresses in this whitelist */
+ uint8_t capacity; /**< Maximum number of BLE addresses that can be added to this whitelist. */
};
- /* Describes the current state of the device (more than one bit can be set). */
+ /**
+ * Describes the current state of the device (more than one bit can be set).
+ */
struct GapState_t {
unsigned advertising : 1; /**< Peripheral is currently advertising. */
unsigned connected : 1; /**< Peripheral is connected to a central. */
};
- typedef uint16_t Handle_t; /* Type for connection handle. */
+ /**
+ * Type for connection handle.
+ */
+ typedef uint16_t Handle_t;
+ /**
+ * Structure containing GAP connection parameters. When in peripheral role
+ * the connection parameters are suggestions. The choice of the connection
+ * parameters is eventually up to the central.
+ */
typedef struct {
- uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
- uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
- uint16_t slaveLatency; /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
- uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
+ uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see BLE_GAP_CP_LIMITS.*/
+ uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see BLE_GAP_CP_LIMITS.*/
+ uint16_t slaveLatency; /**< Slave Latency in number of connection events, see BLE_GAP_CP_LIMITS.*/
+ uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see BLE_GAP_CP_LIMITS.*/
} ConnectionParams_t;
+ /**
+ * Enumeration for the possible GAP roles of a BLE device.
+ */
enum Role_t {
PERIPHERAL = 0x1, /**< Peripheral Role. */
CENTRAL = 0x2, /**< Central Role. */
};
+ /**
+ * Structure containing data and metadata of a scanned advertising packet.
+ */
struct AdvertisementCallbackParams_t {
- BLEProtocol::AddressBytes_t peerAddr;
- int8_t rssi;
- bool isScanResponse;
- GapAdvertisingParams::AdvertisingType_t type;
- uint8_t advertisingDataLen;
- const uint8_t *advertisingData;
+ BLEProtocol::AddressBytes_t peerAddr; /**< The peer's BLE address. */
+ int8_t rssi; /**< The advertisement packet RSSI value. */
+ bool isScanResponse; /**< Whether this packet is the response to a scan request. */
+ GapAdvertisingParams::AdvertisingType_t type; /**< The type of advertisement. */
+ uint8_t advertisingDataLen; /**< Length of the advertisement data. */
+ const uint8_t *advertisingData; /**< Pointer to the advertisement packet's data. */
};
+
+ /**
+ * Type for the handlers of advertisement callback events. Refer to
+ * Gap::startScan().
+ */
typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> AdvertisementReportCallback_t;
+ /**
+ * Encapsulates the parameters of a connection. This information is passed
+ * to the registered handler of connection events. Refer to Gap::onConnection().
+ */
struct ConnectionCallbackParams_t {
- Handle_t handle;
- Role_t role;
- BLEProtocol::AddressType_t peerAddrType;
- BLEProtocol::AddressBytes_t peerAddr;
- BLEProtocol::AddressType_t ownAddrType;
- BLEProtocol::AddressBytes_t ownAddr;
- const ConnectionParams_t *connectionParams;
+ Handle_t handle; /**< The ID for this connection */
+ Role_t role; /**< This device's role in the connection */
+ BLEProtocol::AddressType_t peerAddrType; /**< The peer's BLE address type */
+ BLEProtocol::AddressBytes_t peerAddr; /**< The peer's BLE address */
+ BLEProtocol::AddressType_t ownAddrType; /**< This device's BLE address type */
+ BLEProtocol::AddressBytes_t ownAddr; /**< This devices's BLE address */
+ const ConnectionParams_t *connectionParams; /**< The currently configured connection parameters */
+ /**
+ * Constructor for ConnectionCallbackParams_t.
+ *
+ * @param[in] handleIn
+ * Value for ConnectionCallbackParams_t::handle
+ * @param[in] roleIn
+ * Value for ConnectionCallbackParams_t::role
+ * @param[in] peerAddrTypeIn
+ * Value for ConnectionCallbackParams_t::peerAddrType
+ * @param[in] peerAddrIn
+ * Value for ConnectionCallbackParams_t::peerAddr
+ * @param[in] ownAddrTypeIn
+ * Value for ConnectionCallbackParams_t::ownAddrType
+ * @param[in] ownAddrIn
+ * Value for ConnectionCallbackParams_t::ownAddr
+ * @param[in] connectionParamsIn
+ * Value for ConnectionCallbackParams_t::connectionParams
+ */
ConnectionCallbackParams_t(Handle_t handleIn,
Role_t roleIn,
BLEProtocol::AddressType_t peerAddrTypeIn,
@@ -201,10 +261,22 @@
}
};
+ /**
+ * Structure that encapsulates information about a disconnection event.
+ * Refer to Gap::onDisconnection().
+ */
struct DisconnectionCallbackParams_t {
- Handle_t handle;
- DisconnectionReason_t reason;
+ Handle_t handle; /**< The ID of the connection that caused the disconnection event */
+ DisconnectionReason_t reason; /**< The reason of the disconnection event */
+ /**
+ * Constructor for DisconnectionCallbackParams_t.
+ *
+ * @param[in] handleIn
+ * Value for DisconnectionCallbackParams_t::handle.
+ * @param[in] reasonIn
+ * Value for DisconnectionCallbackParams_t::reason.
+ */
DisconnectionCallbackParams_t(Handle_t handleIn,
DisconnectionReason_t reasonIn) :
handle(handleIn),
@@ -213,22 +285,63 @@
};
static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
+ /**
+ * Helper function to convert from units of milliseconds to GAP duration
+ * units.
+ *
+ * @param[in] durationInMillis
+ * The duration in milliseconds.
+ *
+ * @return The duration in GAP duration units.
+ */
static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
return (durationInMillis * 1000) / UNIT_1_25_MS;
}
+ /**
+ * Type for the registered callbacks added to the timeout event callchain.
+ * Refer to Gap::onTimeout().
+ */
typedef FunctionPointerWithContext<TimeoutSource_t> TimeoutEventCallback_t;
+ /**
+ * Type for the timeout event callchain. Refer to Gap::onTimeout().
+ */
typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> TimeoutEventCallbackChain_t;
+ /**
+ * Type for the registered callbacks added to the connection event
+ * callchain. Refer to Gap::onConnection().
+ */
typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallback_t;
+ /**
+ * Type for the connection event callchain. Refer to Gap::onConnection().
+ */
typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t;
+ /**
+ * Type for the registered callbacks added to the disconnection event
+ * callchain. Refer to Gap::onDisconnetion().
+ */
typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
+ /**
+ * Type for the disconnection event callchain. Refer to Gap::onDisconnection().
+ */
typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t;
+ /**
+ * Type for the handlers of radio notification callback events. Refer to
+ * Gap::onRadioNotification().
+ */
typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
+ /**
+ * Type for the handlers of shutdown callback events. Refer to
+ * Gap::onShutdown().
+ */
typedef FunctionPointerWithContext<const Gap *> GapShutdownCallback_t;
+ /**
+ * Type for the shutdown event callchain. Refer to Gap::onShutdown().
+ */
typedef CallChainOfFunctionPointersWithContext<const Gap *> GapShutdownCallbackChain_t;
/*
@@ -239,6 +352,11 @@
* Set the BTLE MAC address and type. Please note that the address format is
* least significant byte first (LSB). Please refer to BLEProtocol::AddressBytes_t.
*
+ * @param[in] type
+ * The type of the BLE address to set.
+ * @param[in] address
+ * The BLE address to set.
+ *
* @return BLE_ERROR_NONE on success.
*/
virtual ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
@@ -252,6 +370,11 @@
/**
* Fetch the BTLE MAC address and type.
*
+ * @param[out] typeP
+ * The current BLE address type.
+ * @param[out] address
+ * The current BLE address.
+ *
* @return BLE_ERROR_NONE on success.
*/
virtual ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
@@ -263,28 +386,44 @@
}
/**
+ * Get the minimum advertising interval in milliseconds for connectable
+ * undirected and connectable directed event types supported by the
+ * underlying BLE stack.
+ *
* @return Minimum Advertising interval in milliseconds for connectable
- * undirected and connectable directed event types.
+ * undirected and connectable directed event types.
*/
virtual uint16_t getMinAdvertisingInterval(void) const {
return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
}
/**
+ * Get the minimum advertising interval in milliseconds for scannable
+ * undirected and non-connectable undirected even types supported by the
+ * underlying BLE stack.
+ *
* @return Minimum Advertising interval in milliseconds for scannable
- * undirected and non-connectable undirected event types.
+ * undirected and non-connectable undirected event types.
*/
virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const {
return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
}
/**
+ * Get the maximum advertising interval in milliseconds for all event types
+ * supported by the underlying BLE stack.
+ *
* @return Maximum Advertising interval in milliseconds.
*/
virtual uint16_t getMaxAdvertisingInterval(void) const {
return 0xFFFF; /* Requesting action from porter(s): override this API if this capability is supported. */
}
+ /**
+ * Stop advertising. The current advertising parameters remain in effect.
+ *
+ * @retval BLE_ERROR_NONE if successfully stopped advertising procedure.
+ */
virtual ble_error_t stopAdvertising(void) {
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
}
@@ -301,17 +440,18 @@
/**
* Create a connection (GAP Link Establishment).
*
- * @param peerAddr
- * 48-bit address, LSB format.
- * @param peerAddrType
- * Address type of the peer.
- * @param connectionParams
- * Connection parameters.
- * @param scanParams
- * Paramters to be used while scanning for the peer.
+ * @param[in] peerAddr
+ * 48-bit address, LSB format.
+ * @param[in] peerAddrType
+ * Address type of the peer.
+ * @param[in] connectionParams
+ * Connection parameters.
+ * @param[in] scanParams
+ * Paramters to be used while scanning for the peer.
+ *
* @return BLE_ERROR_NONE if connection establishment procedure is started
- * successfully. The connectionCallChain (if set) will be invoked upon
- * a connection event.
+ * successfully. The connectionCallChain (if set) will be invoked upon
+ * a connection event.
*/
virtual ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
BLEProtocol::AddressType_t peerAddrType,
@@ -329,11 +469,12 @@
/**
* Create a connection (GAP Link Establishment).
*
- * \deprecated: This funtion overloads Gap::connect(const BLEProtocol::Address_t peerAddr,
- BLEProtocol::AddressType_t peerAddrType,
- const ConnectionParams_t *connectionParams,
- const GapScanningParams *scanParams)
- * to maintain backward compatibility for change from Gap::AddressType_t to BLEProtocol::AddressType_t
+ * @deprecated This funtion overloads Gap::connect(const BLEProtocol::Address_t peerAddr,
+ * BLEProtocol::AddressType_t peerAddrType,
+ * const ConnectionParams_t *connectionParams,
+ * const GapScanningParams *scanParams)
+ * to maintain backward compatibility for change from Gap::AddressType_t to
+ * BLEProtocol::AddressType_t.
*/
ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
DeprecatedAddressType_t peerAddrType,
@@ -348,8 +489,12 @@
* be communicated to the application with an invocation of the
* disconnectionCallback.
*
- * @param reason
- * The reason for disconnection; to be sent back to the peer.
+ * @param[in] reason
+ * The reason for disconnection; to be sent back to the peer.
+ * @param[in] connectionHandle
+ * The handle of the connection to disconnect from.
+ *
+ * @return BLE_ERROR_NONE if disconnection was successful.
*/
virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
/* avoid compiler warnings about unused variables */
@@ -364,13 +509,15 @@
* be communicated to the application with an invocation of the
* disconnectionCallback.
*
- * @param reason
- * The reason for disconnection; to be sent back to the peer.
+ * @param[in] reason
+ * The reason for disconnection; to be sent back to the peer.
+ *
+ * @return BLE_ERROR_NONE if disconnection was successful.
*
- * @note: This version of disconnect() doesn't take a connection handle. It
- * works reliably only for stacks that are limited to a single
- * connection. This API should be considered *deprecated* in favour of the
- * alternative, which takes a connection handle. It will be dropped in the future.
+ * @deprecated This version of disconnect() doesn't take a connection handle. It
+ * works reliably only for stacks that are limited to a single
+ * connection. Use instead Gap::disconnect(Handle_t connectionHandle,
+ * DisconnectionReason_t reason) instead.
*/
virtual ble_error_t disconnect(DisconnectionReason_t reason) {
/* Avoid compiler warnings about unused variables. */
@@ -389,7 +536,7 @@
* for this is owned by the caller.
*
* @return BLE_ERROR_NONE if the parameters were successfully filled into
- * the given structure pointed to by params.
+ * the given structure pointed to by params.
*/
virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
/* Avoid compiler warnings about unused variables. */
@@ -405,6 +552,9 @@
*
* @param[in] params
* The structure containing the desired parameters.
+ *
+ * @return BLE_ERROR_NONE if the preferred connection params were set
+ * correctly.
*/
virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
/* Avoid compiler warnings about unused variables. */
@@ -414,16 +564,18 @@
}
/**
- * Update connection parameters.
- * In the central role this will initiate a Link Layer connection parameter update procedure.
- * In the peripheral role, this will send the corresponding L2CAP request and wait for
- * the central to perform the procedure.
+ * Update connection parameters. In the central role this will initiate a
+ * Link Layer connection parameter update procedure. In the peripheral role,
+ * this will send the corresponding L2CAP request and wait for the central
+ * to perform the procedure.
*
* @param[in] handle
* Connection Handle.
* @param[in] params
* 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.
+ *
+ * @return BLE_ERROR_NONE if the connection parameters were updated correctly.
*/
virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) {
/* avoid compiler warnings about unused variables */
@@ -435,8 +587,11 @@
/**
* 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.
+ *
+ * @return BLE_ERROR_NONE if the device name was set correctly.
*/
virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
/* Avoid compiler warnings about unused variables. */
@@ -447,21 +602,25 @@
/**
* 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).
*
+ * @return BLE_ERROR_NONE if the device name was fetched correctly from the
+ * underlying BLE stack.
+ *
* @note If the device name is longer than the size of the supplied buffer,
- * length will return the complete device name length, and not the
- * number of bytes actually returned in deviceName. The application may
- * use this information to retry with a suitable buffer size.
+ * length will return the complete device name length, and not the
+ * number of bytes actually returned in deviceName. The application may
+ * use this information to retry with a suitable buffer size.
*/
virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
/* avoid compiler warnings about unused variables */
@@ -473,8 +632,11 @@
/**
* Set the appearance characteristic in the GAP service.
+ *
* @param[in] appearance
* The new value for the device-appearance.
+ *
+ * @return BLE_ERROR_NONE if the new appearance was set correctly.
*/
virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
/* Avoid compiler warnings about unused variables. */
@@ -485,8 +647,12 @@
/**
* Get the appearance characteristic in the GAP service.
+ *
* @param[out] appearance
- * The new value for the device-appearance.
+ * The current device-appearance value.
+ *
+ * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
+ * from the underlying BLE stack.
*/
virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
/* Avoid compiler warnings about unused variables. */
@@ -497,7 +663,12 @@
/**
* Set the radio's transmit power.
- * @param[in] txPower Radio transmit power in dBm.
+ *
+ * @param[in] txPower
+ * Radio's transmit power in dBm.
+ *
+ * @return BLE_ERROR_NONE if the new radio's transmit power was set
+ * correctly.
*/
virtual ble_error_t setTxPower(int8_t txPower) {
/* Avoid compiler warnings about unused variables. */
@@ -523,8 +694,14 @@
}
/**
+ * Get the maximum size of the whitelist.
+ *
* @return Maximum size of the whitelist.
*
+ * @note If using mbed OS the size of the whitelist can be configured by
+ * setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta
+ * config file.
+ *
* @experimental
*/
virtual uint8_t getMaxWhitelistSize(void) const
@@ -536,7 +713,7 @@
* Get the internal whitelist to be used by the Link Layer when scanning,
* advertising or initiating a connection depending on the filter policies.
*
- * @param[in/out] whitelist
+ * @param[in,out] whitelist
* (on input) whitelist.capacity contains the maximum number
* of addresses to be returned.
* (on output) The populated whitelist with copies of the
@@ -674,6 +851,15 @@
protected:
/* Override the following in the underlying adaptation layer to provide the functionality of scanning. */
+
+ /**
+ * Start scanning procedure in the underlying BLE stack.
+ *
+ * @param[in] scanningParams
+ * The GAP scanning parameters.
+ *
+ * @return BLE_ERROR_NONE if the scan procedure started successfully.
+ */
virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams) {
(void)scanningParams;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -684,8 +870,10 @@
*/
public:
/**
- * Returns the current GAP state of the device using a bitmask that
+ * Get the current GAP state of the device using a bitmask that
* describes whether the device is advertising or connected.
+ *
+ * @return The current GAP state of the device.
*/
GapState_t getState(void) const {
return state;
@@ -693,12 +881,17 @@
/**
* Set the GAP advertising mode to use for this device.
+ *
+ * @param[in] advType
+ * The new type of the advertising packets.
*/
void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType) {
_advParams.setAdvertisingType(advType);
}
/**
+ * Set the advertising interval.
+ *
* @param[in] interval
* Advertising interval in units of milliseconds. Advertising
* is disabled if interval is 0. If interval is smaller than
@@ -709,15 +902,15 @@
* This field must be set to 0 if connectionMode is equal
* to ADV_CONNECTABLE_DIRECTED.
*
- * @note: Decreasing this value will allow central devices to detect a
- * peripheral faster, at the expense of more power being used by the radio
- * due to the higher data transmit rate.
+ * @note Decreasing this value will allow central devices to detect a
+ * peripheral faster, at the expense of more power being used by the radio
+ * due to the higher data transmit rate.
*
- * @Note: [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
- * code depending on the old semantics needs to be updated accordingly.
+ * @note [WARNING] This API previously used 0.625ms as the unit for its
+ * @p 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
+ * code depending on the old semantics needs to be updated accordingly.
*/
void setAdvertisingInterval(uint16_t interval) {
if (interval == 0) {
@@ -729,6 +922,9 @@
}
/**
+ * Set the advertising timeout. The length of time to advertise for before
+ * a timeout event is generated.
+ *
* @param[in] timeout
* Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
* and 16383). Use 0 to disable the advertising timeout.
@@ -739,6 +935,8 @@
/**
* Start advertising.
+ *
+ * @return BLE_ERROR_NONE if the device started advertising successfully.
*/
ble_error_t startAdvertising(void) {
setAdvertisingData(); /* Update the underlying stack. */
@@ -765,6 +963,9 @@
* The flags to be added. Please refer to
* GapAdvertisingData::Flags for valid flags. Multiple
* flags may be specified in combination.
+ *
+ * @return BLE_ERROR_NONE if the data was successfully added to the
+ * advertising payload.
*/
ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
ble_error_t rc;
@@ -781,8 +982,11 @@
* as an additional 31 bytes if the advertising payload is too
* small.
*
- * @param app
- * The appearance of the peripheral.
+ * @param[in] app
+ * The appearance of the peripheral.
+ *
+ * @return BLE_ERROR_NONE if the data was successfully added to the
+ * advertising payload.
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
setAppearance(app);
@@ -801,8 +1005,11 @@
* as an additional 31 bytes if the advertising payload is too
* small.
*
- * @param power
- * The max transmit power to be used by the controller (in dBm).
+ * @param[in] power
+ * The max transmit power to be used by the controller (in dBm).
+ *
+ * @return BLE_ERROR_NONE if the data was successfully added to the
+ * advertising payload.
*/
ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
ble_error_t rc;
@@ -819,9 +1026,12 @@
* The SCAN_RESPONSE message may be used as an additional 31 bytes if the
* advertising payload is too small.
*
- * @param type The type describing the variable length data.
- * @param data Data bytes.
- * @param len Length of data.
+ * @param[in] type
+ * The type describing the variable length data.
+ * @param[in] data
+ * Data bytes.
+ * @param[in] len
+ * Length of data.
*
* @return BLE_ERROR_NONE if the advertisement payload was updated based on
* matching AD type; otherwise, an appropriate error.
@@ -850,11 +1060,14 @@
* Update a particular ADV field in the advertising payload (based on
* matching type).
*
- * @param[in] type The ADV type field describing the variable length data.
- * @param[in] data Data bytes.
- * @param[in] len Length of data.
+ * @param[in] type
+ * The ADV type field describing the variable length data.
+ * @param[in] data
+ * Data bytes.
+ * @param[in] len
+ * Length of data.
*
- * @note: If advertisements are enabled, then the update will take effect immediately.
+ * @note If advertisements are enabled, then the update will take effect immediately.
*
* @return BLE_ERROR_NONE if the advertisement payload was updated based on
* matching AD type; otherwise, an appropriate error.
@@ -875,7 +1088,15 @@
/**
* Set up a particular, user-constructed advertisement payload for the
* underlying stack. It would be uncommon for this API to be used directly;
- * there are other APIs to build an advertisement payload (see above).
+ * there are other APIs to build an advertisement payload (refer to
+ * Gap::accumulateAdvertisingPayload()).
+ *
+ * @param[in] payload
+ * A reference to a user constructed advertisement
+ * payload.
+ *
+ * @return BLE_ERROR_NONE if the advertisement payload was successfully
+ * set.
*/
ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) {
_advPayload = payload;
@@ -883,8 +1104,11 @@
}
/**
- * @return Read back advertising data. Useful for storing and
- * restoring payload.
+ * Get a reference to the advertising payload.
+ *
+ * @return Read back advertising data.
+ *
+ * @note Useful for storing and restoring payload.
*/
const GapAdvertisingData &getAdvertisingPayload(void) const {
return _advPayload;
@@ -894,9 +1118,15 @@
* Accumulate a variable length byte-stream as an AD structure in the
* scanResponse payload.
*
- * @param[in] type The type describing the variable length data.
- * @param[in] data Data bytes.
- * @param[in] len Length of data.
+ * @param[in] type
+ * The type describing the variable length data.
+ * @param[in] data
+ * Data bytes.
+ * @param[in] len
+ * Length of data.
+ *
+ * @return BLE_ERROR_NONE if the data was successfully added to the scan
+ * response payload.
*/
ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
ble_error_t rc;
@@ -909,10 +1139,10 @@
/**
* Reset any scan response prepared from prior calls to
- * accumulateScanResponse().
+ * Gap::accumulateScanResponse().
*
- * Note: This should be followed by a call to setAdvertisingPayload() or
- * startAdvertising() before the update takes effect.
+ * @note This should be followed by a call to Gap::setAdvertisingPayload() or
+ * Gap::startAdvertising() before the update takes effect.
*/
void clearScanResponse(void) {
_scanResponse.clear();
@@ -921,6 +1151,7 @@
/**
* Set up parameters for GAP scanning (observer mode).
+ *
* @param[in] interval
* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
* @param[in] window
@@ -931,17 +1162,19 @@
* Set to True if active-scanning is required. This is used to fetch the
* scan response from a peer if possible.
*
- * The scanning window divided by the interval determines the duty cycle for
- * scanning. For example, if the interval is 100ms and the window is 10ms,
- * then the controller will scan for 10 percent of the time. It is possible
- * to have the interval and window set to the same value. In this case,
- * scanning is continuous, with a change of scanning frequency once every
- * interval.
+ * @return BLE_ERROR_NONE if the scan parameters were correctly set.
*
- * Once the scanning parameters have been configured, scanning can be
- * enabled by using startScan().
+ * @note The scanning window divided by the interval determines the duty cycle for
+ * scanning. For example, if the interval is 100ms and the window is 10ms,
+ * then the controller will scan for 10 percent of the time. It is possible
+ * to have the interval and window set to the same value. In this case,
+ * scanning is continuous, with a change of scanning frequency once every
+ * interval.
*
- * @Note: The scan interval and window are recommendations to the BLE stack.
+ * @note 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.
*/
ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
@@ -960,18 +1193,21 @@
/**
* Set up the scanInterval parameter for GAP scanning (observer mode).
+ *
* @param[in] interval
* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
*
- * The scanning window divided by the interval determines the duty cycle for
- * scanning. For example, if the interval is 100ms and the window is 10ms,
- * then the controller will scan for 10 percent of the time. It is possible
- * to have the interval and window set to the same value. In this case,
- * scanning is continuous, with a change of scanning frequency once every
- * interval.
+ * @return BLE_ERROR_NONE if the scan interval was correctly set.
*
- * Once the scanning parameters have been configured, scanning can be
- * enabled by using startScan().
+ * @note The scanning window divided by the interval determines the duty cycle for
+ * scanning. For example, if the interval is 100ms and the window is 10ms,
+ * then the controller will scan for 10 percent of the time. It is possible
+ * to have the interval and window set to the same value. In this case,
+ * scanning is continuous, with a change of scanning frequency once every
+ * interval.
+ *
+ * @note Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
*/
ble_error_t setScanInterval(uint16_t interval) {
return _scanningParams.setInterval(interval);
@@ -979,21 +1215,24 @@
/**
* Set up the scanWindow parameter for GAP scanning (observer mode).
+ *
* @param[in] window
* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
*
- * The scanning window divided by the interval determines the duty cycle for
- * scanning. For example, if the interval is 100ms and the window is 10ms,
- * then the controller will scan for 10 percent of the time. It is possible
- * to have the interval and window set to the same value. In this case,
- * scanning is continuous, with a change of scanning frequency once every
- * interval.
+ * @return BLE_ERROR_NONE if the scan window was correctly set.
*
- * Once the scanning parameters have been configured, scanning can be
- * enabled by using startScan().
+ * @note The scanning window divided by the interval determines the duty cycle for
+ * scanning. For example, if the interval is 100ms and the window is 10ms,
+ * then the controller will scan for 10 percent of the time. It is possible
+ * to have the interval and window set to the same value. In this case,
+ * scanning is continuous, with a change of scanning frequency once every
+ * interval.
*
- * If scanning is already active, the updated value of scanWindow will be
- * propagated to the underlying BLE stack.
+ * @note Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
+ *
+ * @note If scanning is already active, the updated value of scanWindow will be
+ * propagated to the underlying BLE stack.
*/
ble_error_t setScanWindow(uint16_t window) {
ble_error_t rc;
@@ -1011,14 +1250,17 @@
/**
* Set up parameters for GAP scanning (observer mode).
+ *
* @param[in] timeout
* Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
*
- * Once the scanning parameters have been configured, scanning can be
- * enabled by using startScan().
+ * @return BLE_ERROR_NONE if the scan timeout was correctly set.
*
- * If scanning is already active, the updated value of scanTimeout will be
- * propagated to the underlying BLE stack.
+ * @note Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
+ *
+ * @note If scanning is already active, the updated value of scanTimeout will be
+ * propagated to the underlying BLE stack.
*/
ble_error_t setScanTimeout(uint16_t timeout) {
ble_error_t rc;
@@ -1035,16 +1277,19 @@
}
/**
- * Set up parameters for GAP scanning (observer mode).
+ * Modify the active scanning parameter for GAP scanning (observer mode).
+ * This is used to fetch the scan response from a peer if possible.
+ *
* @param[in] activeScanning
- * Set to True if active-scanning is required. This is used to fetch the
- * scan response from a peer if possible.
+ * Set to True if active-scanning is required.
*
- * Once the scanning parameters have been configured, scanning can be
- * enabled by using startScan().
+ * @return BLE_ERROR_NONE if active scanning was successfully set.
*
- * If scanning is already in progress, then active-scanning will be enabled
- * for the underlying BLE stack.
+ * @note Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
+ *
+ * @note If scanning is already in progress, then active-scanning will be enabled
+ * for the underlying BLE stack.
*/
ble_error_t setActiveScanning(bool activeScanning) {
_scanningParams.setActiveScanning(activeScanning);
@@ -1065,6 +1310,9 @@
* The application-specific callback to be invoked upon
* receiving every advertisement report. This can be passed in
* as NULL, in which case scanning may not be enabled at all.
+ *
+ * @return BLE_ERROR_NONE if the device successfully started the scan
+ * procedure.
*/
ble_error_t startScan(void (*callback)(const AdvertisementCallbackParams_t *params)) {
ble_error_t err = BLE_ERROR_NONE;
@@ -1079,7 +1327,19 @@
}
/**
- * Same as above, but this takes an (object, method) pair for a callback.
+ * Same Gap::startScan(), but allows the possibility to add an object
+ * reference and member function as handler for advertisement event
+ * callbacks.
+ *
+ * @param[in] object
+ * Pointer to the object of a class defining the member callback
+ * function (@p callbackMember).
+ * @param[in] callbackMember
+ * The member callback (within the context of an object) to be
+ * invoked.
+ *
+ * @return BLE_ERROR_NONE if the device successfully started the scan
+ * procedure.
*/
template<typename T>
ble_error_t startScan(T *object, void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)) {
@@ -1116,21 +1376,58 @@
}
private:
+ /**
+ * Helper function used to set the advertising data in the underlying BLE stack.
+ *
+ * @return BLE_ERROR_NONE if the advertising data was successfully set.
+ */
ble_error_t setAdvertisingData(void) {
return setAdvertisingData(_advPayload, _scanResponse);
}
private:
+ /**
+ * Functionality that is BLE stack-dependent and must be implemented by the
+ * ported. This is a helper function to set the advertising data in the
+ * BLE stack.
+ *
+ * @param[in] advData
+ * The new advertising data.
+ * @param[in] scanResponse
+ * The new scan response data.
+ *
+ * @return BLE_ERROR_NONE if the advertising data was set successfully.
+ */
virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0;
+
+ /**
+ * Functionality that is BLE stack-dependent and must be implemented by the
+ * ported. This is a helper function to start the advertising procedure in
+ * the underlying BLE stack.
+ *
+ * @param[in]
+ * The advertising parameters.
+ *
+ * @return BLE_ERROR_NONE if the advertising procedure was successfully
+ * started.
+ */
virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
public:
/**
- * Accessors to read back currently active advertising params.
+ * Accessor to read back currently active advertising parameters.
+ *
+ * @return A reference to the current advertising parameters.
*/
GapAdvertisingParams &getAdvertisingParams(void) {
return _advParams;
}
+
+ /**
+ * A const alternative to Gap::getAdvertisingParams().
+ *
+ * @return A const reference to the current advertising parameters.
+ */
const GapAdvertisingParams &getAdvertisingParams(void) const {
return _advParams;
}
@@ -1140,6 +1437,9 @@
* the underlying stack. It would be uncommon for this API to be used
* directly; there are other APIs to tweak advertisement parameters
* individually.
+ *
+ * @param[in] newParams
+ * The new advertising parameters.
*/
void setAdvertisingParams(const GapAdvertisingParams &newParams) {
_advParams = newParams;
@@ -1150,17 +1450,24 @@
/**
* Set up a callback for timeout events. Refer to TimeoutSource_t for
* possible event types.
- * @note It is possible to unregister callbacks using onTimeout().detach(callback)
+ *
+ * @param[in] callback
+ * Event handler being registered.
+ *
+ * @note It is possible to unregister callbacks using onTimeout().detach(callback).
*/
void onTimeout(TimeoutEventCallback_t callback) {
timeoutCallbackChain.add(callback);
}
/**
- * @brief provide access to the callchain of timeout event callbacks
- * It is possible to register callbacks using onTimeout().add(callback);
- * It is possible to unregister callbacks using onTimeout().detach(callback)
- * @return The timeout event callbacks chain
+ * @brief Provide access to the callchain of timeout event callbacks.
+ *
+ * @note It is possible to register callbacks using onTimeout().add(callback).
+ *
+ * @note It is possible to unregister callbacks using onTimeout().detach(callback).
+ *
+ * @return A reference to the timeout event callbacks chain.
*/
TimeoutEventCallbackChain_t& onTimeout() {
return timeoutCallbackChain;
@@ -1168,18 +1475,41 @@
/**
* Append to a chain of callbacks to be invoked upon GAP connection.
+ *
+ * @param[in] callback
+ * Event handler being registered.
+ *
* @note It is possible to unregister callbacks using onConnection().detach(callback)
*/
- void onConnection(ConnectionEventCallback_t callback) {connectionCallChain.add(callback);}
-
- template<typename T>
- void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
+ void onConnection(ConnectionEventCallback_t callback) {
+ connectionCallChain.add(callback);
+ }
/**
- * @brief provide access to the callchain of connection event callbacks
- * It is possible to register callbacks using onConnection().add(callback);
- * It is possible to unregister callbacks using onConnection().detach(callback)
- * @return The connection event callbacks chain
+ * Same Gap::onConnection(), but allows the possibility to add an object
+ * reference and member function as handler for connection event
+ * callbacks.
+ *
+ * @param[in] tptr
+ * Pointer to the object of a class defining the member callback
+ * function (@p mptr).
+ * @param[in] mptr
+ * The member callback (within the context of an object) to be
+ * invoked.
+ */
+ template<typename T>
+ void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {
+ connectionCallChain.add(tptr, mptr);
+ }
+
+ /**
+ * @brief Provide access to the callchain of connection event callbacks.
+ *
+ * @return A reference to the connection event callbacks chain.
+ *
+ * @note It is possible to register callbacks using onConnection().add(callback).
+ *
+ * @note It is possible to unregister callbacks using onConnection().detach(callback).
*/
ConnectionEventCallbackChain_t& onConnection() {
return connectionCallChain;
@@ -1187,18 +1517,41 @@
/**
* Append to a chain of callbacks to be invoked upon GAP disconnection.
- * @note It is possible to unregister callbacks using onDisconnection().detach(callback)
+ *
+ * @param[in] callback
+ Event handler being registered.
+ *
+ * @note It is possible to unregister callbacks using onDisconnection().detach(callback).
*/
- void onDisconnection(DisconnectionEventCallback_t callback) {disconnectionCallChain.add(callback);}
-
- template<typename T>
- void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
+ void onDisconnection(DisconnectionEventCallback_t callback) {
+ disconnectionCallChain.add(callback);
+ }
/**
- * @brief provide access to the callchain of disconnection event callbacks
- * It is possible to register callbacks using onDisconnection().add(callback);
- * It is possible to unregister callbacks using onDisconnection().detach(callback)
- * @return The disconnection event callbacks chain
+ * Same Gap::onDisconnection(), but allows the possibility to add an object
+ * reference and member function as handler for disconnection event
+ * callbacks.
+ *
+ * @param[in] tptr
+ * Pointer to the object of a class defining the member callback
+ * function (@p mptr).
+ * @param[in] mptr
+ * The member callback (within the context of an object) to be
+ * invoked.
+ */
+ template<typename T>
+ void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {
+ disconnectionCallChain.add(tptr, mptr);
+ }
+
+ /**
+ * @brief Provide access to the callchain of disconnection event callbacks.
+ *
+ * @return A reference to the disconnection event callback chain.
+ *
+ * @note It is possible to register callbacks using onDisconnection().add(callback).
+ *
+ * @note It is possible to unregister callbacks using onDisconnection().detach(callback).
*/
DisconnectionEventCallbackChain_t& onDisconnection() {
return disconnectionCallChain;
@@ -1218,22 +1571,26 @@
* devices, to manage peak current drawn during periods when the radio is on,
* or to trigger sensor data collection for transmission in the Radio Event.
*
- * @param callback
- * The application handler to be invoked in response to a radio
- * ACTIVE/INACTIVE event.
- *
- * Or in the other version:
- *
- * @param tptr
- * Pointer to the object of a class defining the member callback
- * function (mptr).
- * @param mptr
- * The member callback (within the context of an object) to be
- * invoked in response to a radio ACTIVE/INACTIVE event.
+ * @param[in] callback
+ * The application handler to be invoked in response to a radio
+ * ACTIVE/INACTIVE event.
*/
void onRadioNotification(void (*callback)(bool param)) {
radioNotificationCallback.attach(callback);
}
+
+ /**
+ * Same as Gap::onRadioNotification(), but allows the posibility to
+ * register an object reference and member function as handler for radio
+ * notification events.
+ *
+ * @param[in] tptr
+ * Pointer to the object of a class defining the member callback
+ * function (@p mptr).
+ * @param[in] mptr
+ * The member callback (within the context of an object) to be
+ * invoked in response to a radio ACTIVE/INACTIVE event.
+ */
template <typename T>
void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
radioNotificationCallback.attach(tptr, mptr);
@@ -1244,28 +1601,48 @@
* Gap instance is about to shutdown (possibly as a result of a call
* to BLE::shutdown()).
*
- * @Note: It is possible to chain together multiple onShutdown callbacks
+ * @param[in] callback
+ * The handler that is being registered to be notified of
+ * shutdown events.
+ *
+ * @note It is possible to chain together multiple onShutdown callbacks
* (potentially from different modules of an application) to be notified
* before the Gap instance is shutdown.
*
- * @Note: It is also possible to set up a callback into a member function of
+ * @note It is also possible to set up a callback into a member function of
* some object.
*
- * @Note It is possible to unregister a callback using onShutdown().detach(callback)
+ * @note It is possible to unregister a callback using onShutdown().detach(callback)
*/
void onShutdown(const GapShutdownCallback_t& callback) {
shutdownCallChain.add(callback);
}
+
+ /**
+ * Same as Gap::onShutdown(), but allows the posibility to
+ * register an object reference and member function as handler for shutdown
+ * events.
+ *
+ * @param[in] objPtr
+ * Pointer to the object of a class defining the member callback
+ * function (@p memberPtr).
+ * @param[in] memberPtr
+ * The member callback (within the context of an object) to be
+ * invoked in response to a shutdown event.
+ */
template <typename T>
void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
shutdownCallChain.add(objPtr, memberPtr);
}
/**
- * @brief provide access to the callchain of shutdown event callbacks
- * It is possible to register callbacks using onShutdown().add(callback);
- * It is possible to unregister callbacks using onShutdown().detach(callback)
- * @return The shutdown event callbacks chain
+ * @brief Provide access to the callchain of shutdown event callbacks.
+ *
+ * @return A reference to the shutdown event callback chain.
+ *
+ * @note It is possible to register callbacks using onShutdown().add(callback).
+ *
+ * @note It is possible to unregister callbacks using onShutdown().detach(callback).
*/
GapShutdownCallbackChain_t& onShutdown() {
return shutdownCallChain;
@@ -1284,7 +1661,7 @@
*
* @return BLE_ERROR_NONE on success.
*
- * @note: Currently a call to reset() does not reset the advertising and
+ * @note Currently a call to reset() does not reset the advertising and
* scan parameters to default values.
*/
virtual ble_error_t reset(void) {
@@ -1314,6 +1691,9 @@
}
protected:
+ /**
+ * Construct a Gap instance.
+ */
Gap() :
_advParams(),
_advPayload(),
@@ -1332,6 +1712,26 @@
/* Entry points for the underlying stack to report events back to the user. */
public:
+ /**
+ * Helper function that notifies all registered handlers of an occurrence
+ * of a connection event. This function is meant to be called from the
+ * BLE stack specific implementation when a connection event occurs.
+ *
+ * @param[in] handle
+ * The ID of the connection that generated the event.
+ * @param[in] role
+ * The role of this BLE device in the connection.
+ * @param[in] peerAddrType
+ * The peer's BLE address type.
+ * @param[in] peerAddr
+ * The peer's BLE address.
+ * @param[in] ownAddrType
+ * This device's BLE address type.
+ * @param[in] ownAddr
+ * This device's BLE address.
+ * @param[in] connectionParams
+ * The parameters configured for this connection.
+ */
void processConnectionEvent(Handle_t handle,
Role_t role,
BLEProtocol::AddressType_t peerAddrType,
@@ -1344,12 +1744,40 @@
connectionCallChain.call(&callbackParams);
}
+ /**
+ * Helper function that notifies all registered handlers of an occurrence
+ * of a disconnection event. This function is meant to be called from the
+ * BLE stack specific implementation when a disconnection event occurs.
+ *
+ * @param[in] handle
+ * The ID of the connection that generated the event.
+ * @param[in] reason
+ * The reason for disconnection.
+ */
void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
state.connected = 0;
DisconnectionCallbackParams_t callbackParams(handle, reason);
disconnectionCallChain.call(&callbackParams);
}
+ /**
+ * Helper function that notifies the registered handler of a scanned
+ * advertisement packet. This function is meant to be called from the
+ * BLE stack specific implementation when a such event occurs.
+ *
+ * @param[in] peerAddr
+ * The peer's BLE address.
+ * @param[in] rssi
+ * The advertisement packet RSSI value.
+ * @param[in] isScanReponse
+ * Whether this packet is the response to a scan request.
+ * @param[in] type
+ * The type of advertisement.
+ * @param[in] advertisingDataLen
+ * Length of the advertisement data.
+ * @param[in] advertisingData
+ * Pointer to the advertisement packet's data.
+ */
void processAdvertisementReport(const BLEProtocol::AddressBytes_t peerAddr,
int8_t rssi,
bool isScanResponse,
@@ -1366,6 +1794,14 @@
onAdvertisementReport.call(¶ms);
}
+ /**
+ * Helper function that notifies all registered handlers of an occurrence
+ * of a timeout event. This function is meant to be called from the
+ * BLE stack specific implementation when a timeout event occurs.
+ *
+ * @param[in] source
+ * The source of the timout event.
+ */
void processTimeoutEvent(TimeoutSource_t source) {
if (timeoutCallbackChain) {
timeoutCallbackChain(source);
@@ -1373,22 +1809,64 @@
}
protected:
+ /**
+ * Currently set advertising parameters.
+ */
GapAdvertisingParams _advParams;
+ /**
+ * Currently set advertising data.
+ */
GapAdvertisingData _advPayload;
+ /**
+ * Currently set scanning parameters.
+ */
GapScanningParams _scanningParams;
+ /**
+ * Currently set scan response data.
+ */
GapAdvertisingData _scanResponse;
+ /**
+ * The current GAP state.
+ */
GapState_t state;
+ /**
+ * Whether active scanning is set. This is used to fetch the scan response
+ * from a peer if possible.
+ */
bool scanningActive;
protected:
+ /**
+ * Callchain containing all registered callback handlers for timeout
+ * events.
+ */
TimeoutEventCallbackChain_t timeoutCallbackChain;
+ /**
+ * The registered callback handler for radio notification events.
+ */
RadioNotificationEventCallback_t radioNotificationCallback;
+ /**
+ * The registered callback handler for scanned advertisement packet
+ * notifications.
+ */
AdvertisementReportCallback_t onAdvertisementReport;
+ /**
+ * Callchain containing all registered callback handlers for connection
+ * events.
+ */
ConnectionEventCallbackChain_t connectionCallChain;
+ /**
+ * Callchain containing all registered callback handlers for disconnection
+ * events.
+ */
DisconnectionEventCallbackChain_t disconnectionCallChain;
private:
+ /**
+ * Callchain containing all registered callback handlers for shutdown
+ * events.
+ */
GapShutdownCallbackChain_t shutdownCallChain;
private:
--- a/ble/GattClient.h Wed Apr 06 19:14:34 2016 +0100
+++ b/ble/GattClient.h Wed Apr 06 19:14:38 2016 +0100
@@ -351,7 +351,7 @@
/**
* @brief Terminate an ongoing characteristic descriptor discovery.
- * @detail This should result in an invocation of the TerminationCallback if
+ * @details 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:34 2016 +0100
+++ b/ble/SafeBool.h Wed Apr 06 19:14:38 2016 +0100
@@ -17,26 +17,32 @@
#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 reduce instantiation of trueTag function
+ * @brief Base class for all intances of SafeBool.
+ * This base class reduces 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 {}
};
@@ -44,71 +50,75 @@
/**
* @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:34 2016 +0100
+++ b/ble/services/BatteryService.h Wed Apr 06 19:14:38 2016 +0100
@@ -28,7 +28,7 @@
class BatteryService {
public:
/**
- * @param[ref] _ble
+ * @param[in] _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,9 +57,20 @@
}
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:34 2016 +0100
+++ b/ble/services/DeviceInformationService.h Wed Apr 06 19:14:38 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[ref] _ble
- * BLE object for the underlying controller.
+ * @param[in] _ble
+ * A reference to a 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,12 +104,34 @@
}
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:34 2016 +0100
+++ b/module.json Wed Apr 06 19:14:38 2016 +0100
@@ -1,6 +1,6 @@
{
"name": "ble",
- "version": "2.5.0",
+ "version": "2.4.0",
"description": "The BLE module offers a high level abstraction for using Bluetooth Low Energy on multiple platforms.",
"keywords": [
"Bluetooth",