Cristi Stoican
jgh
Fork of
BLE_API
by 
Bluetooth Low Energy
Revision 1179:4ab722f8dca0, committed 2016-04-06
- Comitter:
- vcoubard
- Date:
- Wed Apr 06 19:15:30 2016 +0100
- Parent:
- 1178:a4418fcb462f
- Child:
- 1180:e11b058d005e
- Commit message:
- Synchronized with git rev ca632aaf
Author: Andres Amaya Garcia
Update Gap state after advertising times out
The BLE API was not updating the Gap internal state when the advertising stops
because of a user timeout. This commit fixes the issue by updating the internal
state structure in Gap just before the registered callbacks are notified of the
advertising timeout.
Changed in this revision
--- a/ble/BLE.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/BLE.h Wed Apr 06 19:15:30 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
@@ -89,6 +89,11 @@
* @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke
* the initialization completion callback at some point.
*
+ * @note In some cases, initialization is instantaneous (or blocking); if
+ * so, it is acceptable for the stack-specific implementation of init()
+ * to invoke the completion callback directly (within its own
+ * context).
+ *
* @note Nearly all BLE APIs would return
* BLE_ERROR_INITIALIZATION_INCOMPLETE if used on an instance before the
* corresponding transport is initialized.
@@ -133,70 +138,38 @@
* This call allows the application to get the BLE stack version information.
*
* @return A pointer to a const string representing the version.
- *
- * @note The string returned is owned by BLE API.
+ * Note: The string is owned by BLE_API.
*/
const char *getVersion(void);
- /**
- * Accessor to Gap. All Gap related functionality requires
+ /*
+ * Accessors to GAP. Please refer to Gap.h. All GAP related functionality requires
* going through this accessor.
- *
- * @return A reference to a Gap object associated to this BLE instance.
- */
- Gap &gap();
-
- /**
- * A const alternative to gap().
- *
- * @return A const reference to a Gap object associated to this BLE instance.
*/
const Gap &gap() const;
+ Gap &gap();
- /**
- * Accessor to GattServer. All GattServer related functionality requires
- * going through this accessor.
- *
- * @return A reference to a GattServer object associated to this BLE instance.
- */
- GattServer& gattServer();
-
- /**
- * A const alternative to gattServer().
- *
- * @return A const reference to a GattServer object associated to this BLE instance.
+ /*
+ * Accessors to GATT Server. Please refer to GattServer.h. All GATTServer related
+ * functionality requires going through this accessor.
*/
const GattServer& gattServer() const;
+ GattServer& gattServer();
- /**
- * Accessors to GattClient. All GattClient related functionality requires going
- * through this accessor.
- *
- * @return A reference to a GattClient object associated to this BLE instance.
- */
- GattClient& gattClient();
-
- /**
- * A const alternative to gattClient().
- *
- * @return A const reference to a GattClient object associated to this BLE instance.
+ /*
+ * Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related
+ * functionality requires going through this accessor.
*/
const GattClient& gattClient() const;
+ GattClient& gattClient();
- /**
- * Accessors to SecurityManager. All SecurityManager related functionality requires
- * going through this accessor.
- *
- * @return A reference to a SecurityManager object associated to this BLE instance.
- */
- SecurityManager& securityManager();
-
- /**
- * A const alternative to securityManager().
- *
- * @return A const reference to a SecurityManager object associated to this BLE instance.
+ /*
+ * Accessors to Security Manager. Please refer to SecurityManager.h. All
+ * SecurityManager related functionality requires going through this
+ * accessor.
*/
const SecurityManager& securityManager() const;
+ SecurityManager& securityManager();
/**
* Yield control to the BLE stack or to other tasks waiting for events. This
@@ -208,19 +181,10 @@
void waitForEvent(void);
public:
- /**
- * The value of the BLE::InstanceID_t for the default BLE instance.
- */
static const InstanceID_t DEFAULT_INSTANCE = 0;
#ifndef YOTTA_CFG_BLE_INSTANCES_COUNT
- /**
- * The number of permitted BLE instances for the application.
- */
static const InstanceID_t NUM_INSTANCES = 1;
#else
- /**
- * The number of permitted BLE instances for the application.
- */
static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT;
#endif
@@ -228,14 +192,14 @@
* Get a reference to the BLE singleton corresponding to a given interface.
* There is a static array of BLE singletons.
*
- * @note Calling Instance() is preferred over constructing a BLE object
+ * @Note: Calling Instance() is preferred over constructing a BLE object
* directly, as it returns references to singletons.
*
* @param[in] id
* Instance-ID. This should be less than NUM_INSTANCES
* for the returned BLE singleton to be useful.
*
- * @return A reference to a single object.
+ * @return a reference to a single object.
*/
static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE);
@@ -270,23 +234,23 @@
* Set the BTLE MAC address and type.
* @return BLE_ERROR_NONE on success.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setAddress(). A former call to
- * ble.setAddress(...) should be replaced with
- * ble.gap().setAddress(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setAddress(...) should be replaced with
+ * ble.gap().setAddress(...).
*/
ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
return gap().setAddress(type, address);
}
/**
- * Fetch the Bluetooth Low Energy MAC address and type.
+ * Fetch the BTLE MAC address and type.
* @return BLE_ERROR_NONE on success.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::getAddress(). A former call to
- * ble.getAddress(...) should be replaced with
- * ble.gap().getAddress(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getAddress(...) should be replaced with
+ * ble.gap().getAddress(...).
*/
ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
return gap().getAddress(typeP, address);
@@ -295,10 +259,10 @@
/**
* Set the GAP advertising mode to use for this device.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setAdvertisingType(). A former call to
- * ble.setAdvertisingType(...) should be replaced with
- * ble.gap().setAdvertisingType(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setAdvertisingType(...) should be replaced with
+ * ble.gap().setAdvertisingType(...).
*/
void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
gap().setAdvertisingType(advType);
@@ -315,16 +279,16 @@
* This field must be set to 0 if connectionMode is equal
* to ADV_CONNECTABLE_DIRECTED.
*
- * @note Decreasing this value allows central devices to detect a
+ * @note: Decreasing this value allows central devices to detect a
* peripheral faster, at the expense of more power being used by the radio
* due to the higher data transmit rate.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setAdvertisingInterval(). A former call to
- * ble.setAdvertisingInterval(...) should be replaced with
- * ble.gap().setAdvertisingInterval(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setAdvertisingInterval(...) should be replaced with
+ * ble.gap().setAdvertisingInterval(...).
*
- * @note WARNING: This API previously used 0.625ms as the unit for its
+ * @note: [WARNING] This API previously used 0.625ms as the unit for its
* 'interval' argument. That required an explicit conversion from
* milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
* no longer required as the new units are milliseconds. Any application
@@ -337,10 +301,10 @@
/**
* @return Minimum Advertising interval in milliseconds.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::getMinAdvertisingInterval(). A former call to
- * ble.getMinAdvertisingInterval(...) should be replaced with
- * ble.gap().getMinAdvertisingInterval(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getMinAdvertisingInterval(...) should be replaced with
+ * ble.gap().getMinAdvertisingInterval(...).
*/
uint16_t getMinAdvertisingInterval(void) const {
return gap().getMinAdvertisingInterval();
@@ -349,10 +313,10 @@
/**
* @return Minimum Advertising interval in milliseconds for non-connectible mode.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::MinNonConnectableAdvertisingInterval(). A former call to
- * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
- * ble.gap().getMinNonConnectableAdvertisingInterval(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
+ * ble.gap().getMinNonConnectableAdvertisingInterval(...).
*/
uint16_t getMinNonConnectableAdvertisingInterval(void) const {
return gap().getMinNonConnectableAdvertisingInterval();
@@ -361,10 +325,10 @@
/**
* @return Maximum Advertising interval in milliseconds.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::getMaxAdvertisingInterval(). A former call to
- * ble.getMaxAdvertisingInterval(...) should be replaced with
- * ble.gap().getMaxAdvertisingInterval(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getMaxAdvertisingInterval(...) should be replaced with
+ * ble.gap().getMaxAdvertisingInterval(...).
*/
uint16_t getMaxAdvertisingInterval(void) const {
return gap().getMaxAdvertisingInterval();
@@ -375,10 +339,10 @@
* Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
* and 16383). Use 0 to disable the advertising timeout.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setAdvertisingTimeout(). A former call to
- * ble.setAdvertisingTimeout(...) should be replaced with
- * ble.gap().setAdvertisingTimeout(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setAdvertisingTimeout(...) should be replaced with
+ * ble.gap().setAdvertisingTimeout(...).
*/
void setAdvertisingTimeout(uint16_t timeout) {
gap().setAdvertisingTimeout(timeout);
@@ -390,10 +354,10 @@
* directly; there are other APIs to tweak advertisement parameters
* individually (see above).
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setAdvertisingParams(). A former call to
- * ble.setAdvertisingParams(...) should be replaced with
- * ble.gap().setAdvertisingParams(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setAdvertisingParams(...) should be replaced with
+ * ble.gap().setAdvertisingParams(...).
*/
void setAdvertisingParams(const GapAdvertisingParams &advParams) {
gap().setAdvertisingParams(advParams);
@@ -403,10 +367,10 @@
* @return Read back advertising parameters. Useful for storing and
* restoring parameters rapidly.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::getAdvertisingParams(). A former call to
- * ble.getAdvertisingParams(...) should be replaced with
- * ble.gap().getAdvertisingParams(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getAdvertisingParams(...) should be replaced with
+ * ble.gap().getAdvertisingParams(...).
*/
const GapAdvertisingParams &getAdvertisingParams(void) const {
return gap().getAdvertisingParams();
@@ -423,10 +387,10 @@
* GapAdvertisingData::Flags for valid flags. Multiple
* flags may be specified in combination.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::accumulateAdvertisingPayload(uint8_t). A former call to
- * ble.accumulateAdvertisingPayload(flags) should be replaced with
- * ble.gap().accumulateAdvertisingPayload(flags).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.accumulateAdvertisingPayload(flags) should be replaced with
+ * ble.gap().accumulateAdvertisingPayload(flags).
*/
ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
return gap().accumulateAdvertisingPayload(flags);
@@ -441,11 +405,10 @@
* @param[in] app
* The appearance of the peripheral.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::accumulateAdvertisingPayload(GapAdvertisingData::Appearance).
- * A former call to ble.accumulateAdvertisingPayload(appearance)
- * should be replaced with
- * ble.gap().accumulateAdvertisingPayload(appearance).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.accumulateAdvertisingPayload(appearance) should be replaced with
+ * ble.gap().accumulateAdvertisingPayload(appearance).
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
return gap().accumulateAdvertisingPayload(app);
@@ -457,14 +420,14 @@
* as an additional 31 bytes if the advertising payload is too
* small.
*
- * @param[in] power
+ * @param[in] app
* The max transmit power to be used by the controller. This
* is only a hint.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::accumulateAdvertisingPayloadTxPower(). A former call to
- * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
- * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
+ * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
*/
ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
return gap().accumulateAdvertisingPayloadTxPower(power);
@@ -480,10 +443,10 @@
* @param data Data bytes.
* @param len Data length.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::accumulateAdvertisingPayload(GapAdvertisingData::DataType, const uint8_t, uint8_t).
- * A former call to ble.accumulateAdvertisingPayload(...) should
- * be replaced with ble.gap().accumulateAdvertisingPayload(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.accumulateAdvertisingPayload(...) should be replaced with
+ * ble.gap().accumulateAdvertisingPayload(...).
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
return gap().accumulateAdvertisingPayload(type, data, len);
@@ -494,10 +457,10 @@
* underlying stack. It would be uncommon for this API to be used directly;
* there are other APIs to build an advertisement payload (see above).
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setAdvertisingData(). A former call to
- * ble.setAdvertisingData(...) should be replaced with
- * ble.gap().setAdvertisingPayload(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setAdvertisingData(...) should be replaced with
+ * ble.gap().setAdvertisingPayload(...).
*/
ble_error_t setAdvertisingData(const GapAdvertisingData &advData) {
return gap().setAdvertisingPayload(advData);
@@ -507,10 +470,10 @@
* @return Read back advertising data. Useful for storing and
* restoring payload.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::getAdvertisingData(). A former call to
- * ble.getAdvertisingData(...) should be replaced with
- * ble.gap().getAdvertisingPayload()(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getAdvertisingData(...) should be replaced with
+ * ble.gap().getAdvertisingPayload()(...).
*/
const GapAdvertisingData &getAdvertisingData(void) const {
return gap().getAdvertisingPayload();
@@ -521,27 +484,24 @@
* accumulateAdvertisingPayload(). This automatically propagates the re-
* initialized advertising payload to the underlying stack.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::clearAdvertisingPayload(). A former call to
- * ble.clearAdvertisingPayload(...) should be replaced with
- * ble.gap().clearAdvertisingPayload(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.clearAdvertisingPayload(...) should be replaced with
+ * ble.gap().clearAdvertisingPayload(...).
*/
void clearAdvertisingPayload(void) {
gap().clearAdvertisingPayload();
}
/**
- * Dynamically reset the accumulated advertising
- * payload and scanResponse. The application must clear and re-
- * accumulates a new advertising payload (and scanResponse) before using this
- * API.
+ * This API is *deprecated* and resolves to a no-operation. It is left here
+ * to allow older code to compile. Please avoid using this API in new code.
+ * This API will be dropped in a future release.
*
- * @return BLE_ERROR_NONE when the advertising payload is set successfully.
- *
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setAdvertisingPayload().
- *
- * @note The new APIs in Gap update the underlying advertisement payload
+ * Formerly, it would be used to dynamically reset the accumulated advertising
+ * payload and scanResponse; to do this, the application would clear and re-
+ * accumulate a new advertising payload (and scanResponse) before using this
+ * API. Updates to the underlying advertisement payload now happen
* implicitly.
*/
ble_error_t setAdvertisingPayload(void) {
@@ -556,10 +516,10 @@
* @param[in] data Data bytes.
* @param[in] len Data length.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::accumulateScanResponse(). A former call to
- * ble.accumulateScanResponse(...) should be replaced with
- * ble.gap().accumulateScanResponse(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.accumulateScanResponse(...) should be replaced with
+ * ble.gap().accumulateScanResponse(...).
*/
ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
return gap().accumulateScanResponse(type, data, len);
@@ -569,10 +529,10 @@
* Reset any scan response prepared from prior calls to
* accumulateScanResponse().
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::clearScanResponse(). A former call to
- * ble.clearScanResponse(...) should be replaced with
- * ble.gap().clearScanResponse(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.clearScanResponse(...) should be replaced with
+ * ble.gap().clearScanResponse(...).
*/
void clearScanResponse(void) {
gap().clearScanResponse();
@@ -581,10 +541,10 @@
/**
* Start advertising.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::startAdvertising(). A former call to
- * ble.startAdvertising(...) should be replaced with
- * ble.gap().startAdvertising(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.startAdvertising(...) should be replaced with
+ * ble.gap().startAdvertising(...).
*/
ble_error_t startAdvertising(void) {
return gap().startAdvertising();
@@ -593,10 +553,10 @@
/**
* Stop advertising.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::stopAdvertising(). A former call to
- * ble.stopAdvertising(...) should be replaced with
- * ble.gap().stopAdvertising(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.stopAdvertising(...) should be replaced with
+ * ble.gap().stopAdvertising(...).
*/
ble_error_t stopAdvertising(void) {
return gap().stopAdvertising();
@@ -624,12 +584,12 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @note The scan interval and window are recommendations to the BLE stack.
+ * @Note: The scan interval and window are recommendations to the BLE stack.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setScanParams(). A former call to
- * ble.setScanParams(...) should be replaced with
- * ble.gap().setScanParams(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setScanParams(...) should be replaced with
+ * ble.gap().setScanParams(...).
*/
ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
@@ -653,10 +613,10 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setScanInterval(). A former call to
- * ble.setScanInterval(interval) should be replaced with
- * ble.gap().setScanInterval(interval).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setScanInterval(interval) should be replaced with
+ * ble.gap().setScanInterval(interval).
*/
ble_error_t setScanInterval(uint16_t interval) {
return gap().setScanInterval(interval);
@@ -677,10 +637,10 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setScanWindow(). A former call to
- * ble.setScanWindow(window) should be replaced with
- * ble.gap().setScanWindow(window).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setScanWindow(window) should be replaced with
+ * ble.gap().setScanWindow(window).
*/
ble_error_t setScanWindow(uint16_t window) {
return gap().setScanWindow(window);
@@ -701,12 +661,12 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @note The scan interval and window are recommendations to the BLE stack.
+ * @Note: The scan interval and window are recommendations to the BLE stack.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setScanTimeout(). A former call to
- * ble.setScanTimeout(...) should be replaced with
- * ble.gap().setScanTimeout(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setScanTimeout(...) should be replaced with
+ * ble.gap().setScanTimeout(...).
*/
ble_error_t setScanTimeout(uint16_t timeout) {
return gap().setScanTimeout(timeout);
@@ -721,10 +681,10 @@
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setActiveScan(). A former call to
- * ble.setActiveScan(...) should be replaced with
- * ble.gap().setActiveScanning(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setActiveScan(...) should be replaced with
+ * ble.gap().setActiveScanning(...).
*/
void setActiveScan(bool activeScanning) {
gap().setActiveScanning(activeScanning);
@@ -739,10 +699,10 @@
* receiving every advertisement report. This can be passed in
* as NULL, in which case scanning may not be enabled at all.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::startScan(). A former call to
- * ble.startScan(callback) should be replaced with
- * ble.gap().startScan(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.startScan(callback) should be replaced with
+ * ble.gap().startScan(callback).
*/
ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) {
return gap().startScan(callback);
@@ -751,10 +711,10 @@
/**
* Same as above, but this takes an (object, method) pair for a callback.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::startScan(). A former call to
- * ble.startScan(callback) should be replaced with
- * ble.gap().startScan(object, callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.startScan(callback) should be replaced with
+ * ble.gap().startScan(object, callback).
*/
template<typename T>
ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
@@ -764,10 +724,10 @@
*
* @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::stopScan(). A former call to
- * ble.stopScan() should be replaced with
- * ble.gap().stopScan().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.stopScan() should be replaced with
+ * ble.gap().stopScan().
*/
ble_error_t stopScan(void) {
return gap().stopScan();
@@ -787,10 +747,10 @@
* successfully. The onConnection callback (if set) is invoked upon
* a connection event.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::connect(). A former call to
- * ble.connect(...) should be replaced with
- * ble.gap().connect(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.connect(...) should be replaced with
+ * ble.gap().connect(...).
*/
ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
@@ -820,27 +780,28 @@
* @param reason
* The reason for disconnection; sent back to the peer.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::disconnect(). A former call to
- * ble.disconnect(reason) should be replaced with
- * ble.gap().disconnect(reason).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.disconnect(reason) should be replaced with
+ * ble.gap().disconnect(reason).
*
- * @note This version of disconnect() doesn't take a connection handle. It
+ * @note: This version of disconnect() doesn't take a connection handle. It
* works reliably only for stacks that are limited to a single
- * connection.
+ * connection. This API should be considered *deprecated* in favour of the
+ * alternative, which takes a connection handle. It will be dropped in the future.
*/
ble_error_t disconnect(Gap::DisconnectionReason_t reason) {
return gap().disconnect(reason);
}
/**
- * Returns the current Gap state of the device using a bitmask that
+ * Returns the current GAP state of the device using a bitmask that
* describes whether the device is advertising or connected.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::getState(). A former call to
- * ble.getGapState() should be replaced with
- * ble.gap().getState().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getGapState() should be replaced with
+ * ble.gap().getState().
*/
Gap::GapState_t getGapState(void) const {
return gap().getState();
@@ -858,10 +819,10 @@
* @return BLE_ERROR_NONE if the parameters were successfully filled into
* the given structure pointed to by params.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::getPreferredConnectionParams(). A former call to
- * ble.getPreferredConnectionParams() should be replaced with
- * ble.gap().getPreferredConnectionParams().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getPreferredConnectionParams() should be replaced with
+ * ble.gap().getPreferredConnectionParams().
*/
ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) {
return gap().getPreferredConnectionParams(params);
@@ -875,10 +836,10 @@
* @param[in] params
* The structure containing the desired parameters.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setPreferredConnectionParams(). A former call to
- * ble.setPreferredConnectionParams() should be replaced with
- * ble.gap().setPreferredConnectionParams().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setPreferredConnectionParams() should be replaced with
+ * ble.gap().setPreferredConnectionParams().
*/
ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) {
return gap().setPreferredConnectionParams(params);
@@ -894,38 +855,38 @@
* Pointer to desired connection parameters. If NULL is provided on a peripheral role,
* the parameters in the PPCP characteristic of the GAP service will be used instead.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::updateConnectionParams(). A former call to
- * ble.updateConnectionParams() should be replaced with
- * ble.gap().updateConnectionParams().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.updateConnectionParams() should be replaced with
+ * ble.gap().updateConnectionParams().
*/
ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
return gap().updateConnectionParams(handle, params);
}
/**
- * Set the device name characteristic in the Gap service.
+ * Set the device name characteristic in the GAP service.
* @param[in] deviceName
* The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setDeviceName(). A former call to
- * ble.setDeviceName() should be replaced with
- * ble.gap().setDeviceName().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setDeviceName() should be replaced with
+ * ble.gap().setDeviceName().
*/
ble_error_t setDeviceName(const uint8_t *deviceName) {
return gap().setDeviceName(deviceName);
}
/**
- * Get the value of the device name characteristic in the Gap service.
+ * Get the value of the device name characteristic in the GAP service.
* @param[out] deviceName
* Pointer to an empty buffer where the UTF-8 *non NULL-
* terminated* string will be placed. Set this
* value to NULL in order to obtain the deviceName-length
* from the 'length' parameter.
*
- * @param[in,out] lengthP
+ * @param[in/out] lengthP
* (on input) Length of the buffer pointed to by deviceName;
* (on output) the complete device name length (without the
* null terminator).
@@ -935,38 +896,38 @@
* number of bytes actually returned in deviceName. The application may
* use this information to retry with a suitable buffer size.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::getDeviceName(). A former call to
- * ble.getDeviceName() should be replaced with
- * ble.gap().getDeviceName().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getDeviceName() should be replaced with
+ * ble.gap().getDeviceName().
*/
ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
return gap().getDeviceName(deviceName, lengthP);
}
/**
- * Set the appearance characteristic in the Gap service.
+ * Set the appearance characteristic in the GAP service.
* @param[in] appearance
* The new value for the device-appearance.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setAppearance(). A former call to
- * ble.setAppearance() should be replaced with
- * ble.gap().setAppearance().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setAppearance() should be replaced with
+ * ble.gap().setAppearance().
*/
ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
return gap().setAppearance(appearance);
}
/**
- * Get the appearance characteristic in the Gap service.
- * @param[out] appearanceP
+ * Get the appearance characteristic in the GAP service.
+ * @param[out] appearance
* The new value for the device-appearance.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::getAppearance(). A former call to
- * ble.getAppearance() should be replaced with
- * ble.gap().getAppearance().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getAppearance() should be replaced with
+ * ble.gap().getAppearance().
*/
ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
return gap().getAppearance(appearanceP);
@@ -976,10 +937,10 @@
* Set the radio's transmit power.
* @param[in] txPower Radio transmit power in dBm.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::setTxPower(). A former call to
- * ble.setTxPower() should be replaced with
- * ble.gap().setTxPower().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.setTxPower() should be replaced with
+ * ble.gap().setTxPower().
*/
ble_error_t setTxPower(int8_t txPower) {
return gap().setTxPower(txPower);
@@ -993,10 +954,10 @@
* @param[out] countP
* Out parameter to receive the array's size.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::getPermittedTxPowerValues(). A former call to
- * ble.getPermittedTxPowerValues() should be replaced with
- * ble.gap().getPermittedTxPowerValues().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call to
+ * ble.getPermittedTxPowerValues() should be replaced with
+ * ble.gap().getPermittedTxPowerValues().
*/
void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
gap().getPermittedTxPowerValues(valueArrayPP, countP);
@@ -1006,10 +967,10 @@
* Add a service declaration to the local server ATT table. Also add the
* characteristics contained within.
*
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::addService(). A former call
- * to ble.addService() should be replaced with
- * ble.gattServer().addService().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.addService() should be replaced with
+ * ble.gattServer().addService().
*/
ble_error_t addService(GattService &service) {
return gattServer().addService(service);
@@ -1021,7 +982,7 @@
* Attribute handle for the value attribute of the characteristic.
* @param[out] buffer
* A buffer to hold the value being read.
- * @param[in,out] lengthP
+ * @param[in/out] lengthP
* Length of the buffer being supplied. If the attribute
* value is longer than the size of the supplied buffer,
* this variable will return the total attribute value length
@@ -1030,10 +991,10 @@
*
* @return BLE_ERROR_NONE if a value was read successfully into the buffer.
*
- * @deprecated You should use the parallel API from GattServer directly,
- * GattServer::read(GattAttribute::Handle_t,uint8_t,uint16_t). A former call
- * to ble.readCharacteristicValue() should be replaced with
- * ble.gattServer().read().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.readCharacteristicValue() should be replaced with
+ * ble.gattServer().read().
*/
ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
return gattServer().read(attributeHandle, buffer, lengthP);
@@ -1047,7 +1008,7 @@
* Attribute handle for the value attribute of the characteristic.
* @param[out] buffer
* A buffer to hold the value being read.
- * @param[in,out] lengthP
+ * @param[in/out] lengthP
* Length of the buffer being supplied. If the attribute
* value is longer than the size of the supplied buffer,
* this variable will return the total attribute value length
@@ -1060,10 +1021,10 @@
* parameter to allow fetches for connection-specific multivalued
* attributes (such as the CCCDs).
*
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::read(Gap::Handle_t,GattAttribute::Handle_t,uint8_t,uint16_t).
- * A former call to ble.readCharacteristicValue() should be replaced with
- * ble.gattServer().read().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.readCharacteristicValue() should be replaced with
+ * ble.gattServer().read().
*/
ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP);
@@ -1087,10 +1048,10 @@
*
* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
*
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::write(GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
- * A former call to ble.updateCharacteristicValue() should be replaced with
- * ble.gattServer().write().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.updateCharacteristicValue() should be replaced with
+ * ble.gattServer().write().
*/
ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle,
const uint8_t *value,
@@ -1121,10 +1082,10 @@
*
* @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
*
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::write(Gap::Handle_t,GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
- * A former call to ble.updateCharacteristicValue() should be replaced with
- * ble.gattServer().write().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.updateCharacteristicValue() should be replaced with
+ * ble.gattServer().write().
*/
ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle,
GattAttribute::Handle_t attributeHandle,
@@ -1149,10 +1110,10 @@
*
* @return BLE_ERROR_NONE on success.
*
- * @deprecated You should use the parallel API from SecurityManager directly, refer to
- * SecurityManager.init(). A former
- * call to ble.initializeSecurity(...) should be replaced with
- * ble.securityManager().init(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.initializeSecurity(...) should be replaced with
+ * ble.securityManager().init(...).
*/
ble_error_t initializeSecurity(bool enableBonding = true,
bool requireMITM = true,
@@ -1169,10 +1130,10 @@
*
* @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
*
- * @deprecated You should use the parallel API from SecurityManager directly, refer to
- * SecurityManager::getLinkSecurity(). A former
- * call to ble.getLinkSecurity(...) should be replaced with
- * ble.securityManager().getLinkSecurity(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.getLinkSecurity(...) should be replaced with
+ * ble.securityManager().getLinkSecurity(...).
*/
ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) {
return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
@@ -1186,10 +1147,10 @@
* @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
* application registration.
*
- * @deprecated You should use the parallel API from SecurityManager directly, refer to
- * SecurityManager::purgeAllBondingState(). A former
- * call to ble.purgeAllBondingState() should be replaced with
- * ble.securityManager().purgeAllBondingState().
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.purgeAllBondingState() should be replaced with
+ * ble.securityManager().purgeAllBondingState().
*/
ble_error_t purgeAllBondingState(void) {
return securityManager().purgeAllBondingState();
@@ -1199,10 +1160,10 @@
* Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
* possible event types.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::onTimeout(). A former call
- * to ble.onTimeout(callback) should be replaced with
- * ble.gap().onTimeout(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call
+ * to ble.onTimeout(callback) should be replaced with
+ * ble.gap().onTimeout(callback).
*/
void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) {
gap().onTimeout(timeoutCallback);
@@ -1211,10 +1172,10 @@
/**
* Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::onConnection(). A former call
- * to ble.onConnection(callback) should be replaced with
- * ble.gap().onConnection(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call
+ * to ble.onConnection(callback) should be replaced with
+ * ble.gap().onConnection(callback).
*/
void onConnection(Gap::ConnectionEventCallback_t connectionCallback) {
gap().onConnection(connectionCallback);
@@ -1223,24 +1184,15 @@
/**
* Append to a chain of callbacks to be invoked upon GAP disconnection.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::onDisconnection(). A former call
- * to ble.onDisconnection(callback) should be replaced with
- * ble.gap().onDisconnection(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call
+ * to ble.onDisconnection(callback) should be replaced with
+ * ble.gap().onDisconnection(callback).
*/
void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) {
gap().onDisconnection(disconnectionCallback);
}
- /**
- * The same as onDisconnection(), but allows an object reference and member function
- * to be added to the chain of callbacks.
- *
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::onDisconnection(). 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);
@@ -1262,10 +1214,10 @@
* The application handler to be invoked in response to a radio
* ACTIVE/INACTIVE event.
*
- * @deprecated You should use the parallel API from Gap directly, refer to
- * Gap::onRadioNotification(). A former call
- * to ble.onRadioNotification(...) should be replaced with
- * ble.gap().onRadioNotification(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from Gap directly. A former call
+ * to ble.onRadioNotification(...) should be replaced with
+ * ble.gap().onRadioNotification(...).
*/
void onRadioNotification(void (*callback)(bool)) {
gap().onRadioNotification(callback);
@@ -1275,31 +1227,21 @@
* Add a callback for the GATT event DATA_SENT (which is triggered when
* updates are sent out by GATT in the form of notifications).
*
- * @note It is possible to chain together multiple onDataSent callbacks
+ * @Note: It is possible to chain together multiple onDataSent callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics.
*
- * @note It is also possible to set up a callback into a member function of
+ * @Note: It is also possible to set up a callback into a member function of
* some object.
*
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::onDataSent(). A former call
- * to ble.onDataSent(...) should be replaced with
- * ble.gattServer().onDataSent(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.onDataSent(...) should be replaced with
+ * ble.gattServer().onDataSent(...).
*/
void onDataSent(void (*callback)(unsigned count)) {
gattServer().onDataSent(callback);
}
-
- /**
- * The same as onDataSent(), but allows an object reference and member function
- * to be added to the chain of callbacks.
- *
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::onDataSent(). 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);
}
@@ -1311,32 +1253,22 @@
* For a Central, this callback is triggered when a response is received for
* a write request.
*
- * @note It is possible to chain together multiple onDataWritten callbacks
+ * @Note: It is possible to chain together multiple onDataWritten callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics. Many services, such as DFU and UART, add their own
* onDataWritten callbacks behind the scenes to trap interesting events.
*
- * @note It is also possible to set up a callback into a member function of
+ * @Note: It is also possible to set up a callback into a member function of
* some object.
*
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::onDataWritten(). A former call
- * to ble.onDataWritten(...) should be replaced with
- * ble.gattServer().onDataWritten(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.onDataWritten(...) should be replaced with
+ * ble.gattServer().onDataWritten(...).
*/
void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {
gattServer().onDataWritten(callback);
}
-
- /**
- * The same as onDataWritten(), but allows an object reference and member function
- * to be added to the chain of callbacks.
- *
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::onDataWritten(). 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);
}
@@ -1345,39 +1277,29 @@
* Set up a callback to be invoked on the peripheral when an attribute is
* being read by a remote client.
*
- * @note This functionality may not be available on all underlying stacks.
+ * @Note: This functionality may not be available on all underlying stacks.
* You could use GattCharacteristic::setReadAuthorizationCallback() as an
* alternative.
*
- * @note It is possible to chain together multiple onDataRead callbacks
+ * @Note: It is possible to chain together multiple onDataRead callbacks
* (potentially from different modules of an application) to receive updates
* to characteristics. Services may add their own onDataRead callbacks
* behind the scenes to trap interesting events.
*
- * @note It is also possible to set up a callback into a member function of
+ * @Note: It is also possible to set up a callback into a member function of
* some object.
*
* @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
* else BLE_ERROR_NONE.
*
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::onDataRead(). A former call
- * to ble.onDataRead(...) should be replaced with
- * ble.gattServer().onDataRead(...).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.onDataRead(...) should be replaced with
+ * ble.gattServer().onDataRead(...).
*/
ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
return gattServer().onDataRead(callback);
}
-
- /**
- * The same as onDataRead(), but allows an object reference and member function
- * to be added to the chain of callbacks.
- *
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::onDataRead(). 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);
}
@@ -1386,10 +1308,10 @@
* Set up a callback for when notifications or indications are enabled for a
* characteristic on the local GattServer.
*
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::onUpdatesEnabled(). A former call
- * to ble.onUpdatesEnabled(callback) should be replaced with
- * ble.gattServer().onUpdatesEnabled(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.onUpdatesEnabled(callback) should be replaced with
+ * ble.gattServer().onUpdatesEnabled(callback).
*/
void onUpdatesEnabled(GattServer::EventCallback_t callback) {
gattServer().onUpdatesEnabled(callback);
@@ -1399,10 +1321,10 @@
* Set up a callback for when notifications or indications are disabled for a
* characteristic on the local GattServer.
*
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::onUpdatesDisabled(). A former call
- * to ble.onUpdatesEnabled(callback) should be replaced with
- * ble.gattServer().onUpdatesEnabled(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.onUpdatesEnabled(callback) should be replaced with
+ * ble.gattServer().onUpdatesEnabled(callback).
*/
void onUpdatesDisabled(GattServer::EventCallback_t callback) {
gattServer().onUpdatesDisabled(callback);
@@ -1412,10 +1334,10 @@
* Set up a callback for when the GATT server receives a response for an
* indication event sent previously.
*
- * @deprecated You should use the parallel API from GattServer directly, refer to
- * GattServer::onConfirmationReceived(). A former call
- * to ble.onConfirmationReceived(callback) should be replaced with
- * ble.gattServer().onConfirmationReceived(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from GattServer directly. A former call
+ * to ble.onConfirmationReceived(callback) should be replaced with
+ * ble.gattServer().onConfirmationReceived(callback).
*/
void onConfirmationReceived(GattServer::EventCallback_t callback) {
gattServer().onConfirmationReceived(callback);
@@ -1428,10 +1350,10 @@
* security request: bool allowBonding, bool requireMITM, and
* SecurityIOCapabilities_t.
*
- * @deprecated You should use the parallel API from SecurityManager directly, refer to
- * SecurityManager::onSecuritySetupInitiated(). A former
- * call to ble.onSecuritySetupInitiated(callback) should be replaced with
- * ble.securityManager().onSecuritySetupInitiated(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onSecuritySetupInitiated(callback) should be replaced with
+ * ble.securityManager().onSecuritySetupInitiated(callback).
*/
void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
securityManager().onSecuritySetupInitiated(callback);
@@ -1443,10 +1365,10 @@
* devices. The callback is passed in the success/failure status of the
* security setup procedure.
*
- * @deprecated You should use the parallel API from SecurityManager directly, refer to
- * SecurityManager::onSecuritySetupCompleted(). A former
- * call to ble.onSecuritySetupCompleted(callback) should be replaced with
- * ble.securityManager().onSecuritySetupCompleted(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onSecuritySetupCompleted(callback) should be replaced with
+ * ble.securityManager().onSecuritySetupCompleted(callback).
*/
void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
securityManager().onSecuritySetupCompleted(callback);
@@ -1460,10 +1382,10 @@
* or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
* to the level of security in effect for the secured link.
*
- * @deprecated You should use the parallel API from SecurityManager directly, refer to
- * SecurityManager::onLinkSecured(). A former
- * call to ble.onLinkSecured(callback) should be replaced with
- * ble.securityManager().onLinkSecured(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onLinkSecured(callback) should be replaced with
+ * ble.securityManager().onLinkSecured(callback).
*/
void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
securityManager().onLinkSecured(callback);
@@ -1473,10 +1395,10 @@
* Set up a callback for successful bonding, meaning that link-specific security
* context is stored persistently for a peer device.
*
- * @deprecated You should use the parallel API from SecurityManager directly, refer to
- * SecurityManager::onSecurityContextStored(). A former
- * call to ble.onSecurityContextStored(callback) should be replaced with
- * ble.securityManager().onSecurityContextStored(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onSecurityContextStored(callback) should be replaced with
+ * ble.securityManager().onSecurityContextStored(callback).
*/
void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
securityManager().onSecurityContextStored(callback);
@@ -1489,10 +1411,10 @@
* a passkey (or PIN) to authenticate the connection
* attempt.
*
- * @deprecated You should use the parallel API from SecurityManager directly, refer to
- * SecurityManager::onPasskeyDisplay(). A former
- * call to ble.onPasskeyDisplay(callback) should be replaced with
- * ble.securityManager().onPasskeyDisplay(callback).
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * You should use the parallel API from SecurityManager directly. A former
+ * call to ble.onPasskeyDisplay(callback) should be replaced with
+ * ble.securityManager().onPasskeyDisplay(callback).
*/
void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
return securityManager().onPasskeyDisplay(callback);
@@ -1516,8 +1438,7 @@
BLEInstanceBase *transport; /* The device-specific backend */
};
-typedef BLE BLEDevice; /**< @deprecated This type alias is retained for the
- * sake of compatibility with older
+typedef BLE BLEDevice; /* DEPRECATED. This type alias is retained for the sake of compatibility with older
* code. Will be dropped at some point soon.*/
-#endif /* ifndef __BLE_H__ */
\ No newline at end of file
+#endif // ifndef __BLE_H__
\ No newline at end of file
--- a/ble/BLEInstanceBase.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/BLEInstanceBase.h Wed Apr 06 19:15:30 2016 +0100
@@ -28,112 +28,22 @@
/**
* The interface for the transport object to be created by the target library's
* createBLEInstance().
- *
- * @note This class is part of the interface of BLE API with the implementation;
- * therefore, it is meant to be used only by porters rather than normal
- * BLE API users.
*/
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/BLEProtocol.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/BLEProtocol.h Wed Apr 06 19:15:30 2016 +0100
@@ -51,27 +51,16 @@
typedef uint8_t AddressBytes_t[ADDR_LEN]; /**< 48-bit address, in LSB format. */
/**
- * BLE address. It contains an address-type (AddressType_t) and bytes (AddressBytes_t).
+ * BLE address. It contains an address-type (@ref AddressType_t) and bytes (@ref AddressBytes_t).
*/
struct Address_t {
- AddressType_t type; /**< The type of the BLE address. */
- AddressBytes_t address; /**< The BLE address. */
+ AddressType_t type; /**< @ref AddressType_t */
+ AddressBytes_t address; /**< @ref AddressBytes_t */
- /**
- * Construct an Address_t object with the supplied type and address.
- *
- * @param[in] typeIn
- * The BLE address type.
- * @param[in] addressIn
- * The BLE address.
- */
Address_t(AddressType_t typeIn, const AddressBytes_t& addressIn) : type(typeIn) {
std::copy(addressIn, addressIn + ADDR_LEN, address);
}
- /**
- * Empty constructor.
- */
Address_t() : type(), address() {
}
};
--- a/ble/CallChainOfFunctionPointersWithContext.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/CallChainOfFunctionPointersWithContext.h Wed Apr 06 19:15:30 2016 +0100
@@ -55,17 +55,16 @@
* }
* @endcode
*/
+
template <typename ContextType>
class CallChainOfFunctionPointersWithContext : public SafeBool<CallChainOfFunctionPointersWithContext<ContextType> > {
public:
- /**
- * The type of each callback in the callchain.
- */
typedef FunctionPointerWithContext<ContextType> *pFunctionPointerWithContext_t;
public:
- /**
- * Create an empty chain.
+ /** Create an empty chain.
+ *
+ * @param size (optional) Initial size of the chain.
*/
CallChainOfFunctionPointersWithContext() : chainHead(NULL) {
/* empty */
@@ -75,69 +74,58 @@
clear();
}
- /**
- * Add a function at the front of the chain.
+ /** Add a function at the front of the chain.
*
- * @param[in] function
- * A pointer to a void function.
+ * @param function A pointer to a void function.
*
- * @return The function object created for @p function.
+ * @returns
+ * The function object created for 'function'.
*/
pFunctionPointerWithContext_t add(void (*function)(ContextType context)) {
return common_add(new FunctionPointerWithContext<ContextType>(function));
}
- /**
- * Add a function at the front of the chain.
+ /** Add a function at the front of the chain.
*
- * @param[in] tptr
- * Pointer to the object to call the member function on.
- * @param[in] mptr
- * Pointer to the member function to be called.
+ * @param tptr Pointer to the object to call the member function on.
+ * @param mptr Pointer to the member function to be called.
*
- * @return The function object created for @p tptr and @p mptr.
+ * @returns
+ * The function object created for 'tptr' and 'mptr'.
*/
template<typename T>
pFunctionPointerWithContext_t add(T *tptr, void (T::*mptr)(ContextType context)) {
return common_add(new FunctionPointerWithContext<ContextType>(tptr, mptr));
}
- /**
- * Add a function at the front of the chain.
+ /** Add a function at the front of the chain.
*
- * @param[in] func
- * The FunctionPointerWithContext to add.
- *
- * @return The function object created for @p func.
+ * @param func The FunctionPointerWithContext to add.
*/
pFunctionPointerWithContext_t add(const FunctionPointerWithContext<ContextType>& func) {
return common_add(new FunctionPointerWithContext<ContextType>(func));
}
- /**
- * Detach a function pointer from a callchain.
- *
- * @param[in] toDetach
- * FunctionPointerWithContext to detach from this callchain.
- *
- * @return true if a function pointer has been detached and false otherwise.
- *
- * @note It is safe to remove a function pointer while the chain is
- * traversed by call(ContextType).
- */
- bool detach(const FunctionPointerWithContext<ContextType>& toDetach) {
+ /**
+ * Detach a function pointer from a callchain
+ *
+ * @oaram toDetach FunctionPointerWithContext to detach from this callchain
+ *
+ * @return true if a function pointer has been detached and false otherwise
+ */
+ bool detach(const FunctionPointerWithContext<ContextType>& toDetach) {
pFunctionPointerWithContext_t current = chainHead;
pFunctionPointerWithContext_t previous = NULL;
while (current) {
- if(*current == toDetach) {
+ if(*current == toDetach) {
if(previous == NULL) {
- if(currentCalled == current) {
+ if(currentCalled == current) {
currentCalled = NULL;
}
chainHead = current->getNext();
} else {
- if(currentCalled == current) {
+ if(currentCalled == current) {
currentCalled = previous;
}
previous->chainAsNext(current->getNext());
@@ -153,8 +141,7 @@
return false;
}
- /**
- * Clear the call chain (remove all functions in the chain).
+ /** Clear the call chain (remove all functions in the chain).
*/
void clear(void) {
pFunctionPointerWithContext_t fptr = chainHead;
@@ -167,32 +154,26 @@
chainHead = NULL;
}
- /**
- * Check whether the callchain contains any callbacks.
- *
- * @return true if the callchain is not empty and false otherwise.
- */
bool hasCallbacksAttached(void) const {
return (chainHead != NULL);
}
- /**
- * Call all the functions in the chain in sequence.
+ /** Call all the functions in the chain in sequence
*/
void call(ContextType context) {
((const CallChainOfFunctionPointersWithContext*) this)->call(context);
}
/**
- * Same as call() above, but const.
+ * @brief same as above but const
*/
void call(ContextType context) const {
currentCalled = chainHead;
- while(currentCalled) {
+ while(currentCalled) {
currentCalled->call(context);
// if this was the head and the call removed the head
- if(currentCalled == NULL) {
+ if(currentCalled == NULL) {
currentCalled = chainHead;
} else {
currentCalled = currentCalled->getNext();
@@ -201,41 +182,34 @@
}
/**
- * Same as call(), but with function call operator.
- * @code
- *
+ * @brief same as above but with function call operator
+ * \code
+ *
* void first(bool);
* void second(bool);
- *
+ *
* CallChainOfFunctionPointerWithContext<bool> foo;
- *
+ *
* foo.attach(first);
* foo.attach(second);
- *
+ *
* // call the callchain like a function
* foo(true);
- *
- * @endcode
+ *
+ * \endcode
*/
void operator()(ContextType context) const {
call(context);
}
/**
- * Bool conversion operation.
- *
- * @return true if the callchain is not empty and false otherwise.
+ * @brief bool conversion operation
*/
bool toBool() const {
return chainHead != NULL;
}
private:
- /**
- * Add a callback to the head of the callchain.
- *
- * @return A pointer to the head of the callchain.
- */
pFunctionPointerWithContext_t common_add(pFunctionPointerWithContext_t pf) {
if (chainHead == NULL) {
chainHead = pf;
@@ -248,17 +222,10 @@
}
private:
- /**
- * A pointer to the first callback in the callchain or NULL if the callchain is empty.
- */
pFunctionPointerWithContext_t chainHead;
-
- /**
- * Iterator during a function call, this has to be mutable because the call function is const.
- *
- * @note Mutable is the correct behaviour here, the iterator never leaks outside the object.
- * so the object can still be seen as logically const even if it is modified.
- */
+ // iterator during a function call, this has to be mutable because the call function is const.
+ // Note: mutable is the correct behaviour here, the iterator never leak outside the object.
+ // So the object can still be seen as logically const even if it change its internal state
mutable pFunctionPointerWithContext_t currentCalled;
--- a/ble/CharacteristicDescriptorDiscovery.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/CharacteristicDescriptorDiscovery.h Wed Apr 06 19:15:30 2016 +0100
@@ -36,7 +36,7 @@
public:
/**
* @brief Parameter type of CharacteristicDescriptorDiscovery::DiscoveryCallback_t.
- * @details Every time a characteristic descriptor has been discovered, the callback
+ * @detail Every time a characteristic descriptor has been discovered, the callback
* registered for the discovery operation through GattClient::discoverCharacteristicDescriptors
* or DiscoveredCharacteristic::discoverDescriptors will be called with this parameter.
*
--- a/ble/DiscoveredCharacteristic.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/DiscoveredCharacteristic.h Wed Apr 06 19:15:30 2016 +0100
@@ -28,24 +28,20 @@
* @brief Representation of a characteristic discovered during a GattClient
* discovery procedure (see GattClient::launchServiceDiscovery ).
*
- * @details Provide detailed informations about a discovered characteristic like:
- * - Its UUID (see getUUID()).
+ * @detail Provide detailed informations about a discovered characteristic like:
+ * - Its UUID (see #getUUID).
* - The most important handles of the characteristic definition
- * (see getDeclHandle(), getValueHandle(), getLastHandle())
- * - Its properties (see getProperties()).
+ * (see #getDeclHandle, #getValueHandle, #getLastHandle )
+ * - Its properties (see #getProperties).
* This class also provide functions to operate on the characteristic:
- * - Read the characteristic value (see read())
- * - Writing a characteristic value (see write() or writeWoResponse())
+ * - Read the characteristic value (see #read)
+ * - Writing a characteristic value (see #write or #writeWoResponse)
* - Discover descriptors inside the characteristic definition. These descriptors
* extends the characteristic. More information about descriptor usage is
* available in DiscoveredCharacteristicDescriptor class.
*/
class DiscoveredCharacteristic {
public:
- /**
- * Structure that encapsulates the properties of a discovered
- * characteristic.
- */
struct Properties_t {
uint8_t _broadcast :1; /**< Broadcasting the value permitted. */
uint8_t _read :1; /**< Reading the value permitted. */
@@ -56,81 +52,19 @@
uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
public:
- /**
- * @brief Check if broadcasting is permitted.
- *
- * @return true if broadcasting the value is permitted, and false
- * otherwise.
- */
- bool broadcast(void) const {
- return _broadcast;
- }
-
- /**
- * @brief Check reading is permitted.
- *
- * @return true if reading the value is permitted, and false
- * otherwise.
- */
- bool read(void) const {
- return _read;
- }
-
- /**
- * @brief Check if writing with Write Command is permitted.
- *
- * @return true if writing the value with Write Command is permitted,
- * false otherwise.
- */
- bool writeWoResp(void) const {
- return _writeWoResp;
- }
-
- /**
- * @brief Check if writing with Write Request is permitted.
- *
- * @return true if writing the value with Write Request is permitted,
- * false otherwise.
- */
- bool write(void) const {
- return _write;
- }
-
- /**
- * @brief Check notifications are permitted.
- *
- * @return true if notifications of the value are permitted, false
- * otherwise.
- */
- bool notify(void) const {
- return _notify;
- }
-
- /**
- * @brief Check if indications are permitted.
- *
- * @return true if indications of the value are permitted, false
- * otherwise.
- */
- bool indicate(void) const {
- return _indicate;
- }
-
- /**
- * @brief Check if writing with Signed Write Command is permitted.
- *
- * @return true if writing the value with Signed Write Command is
- * permitted, false otherwise.
- */
- bool authSignedWrite(void) const {
- return _authSignedWrite;
- }
+ bool broadcast(void) const {return _broadcast; }
+ bool read(void) const {return _read; }
+ bool writeWoResp(void) const {return _writeWoResp; }
+ bool write(void) const {return _write; }
+ bool notify(void) const {return _notify; }
+ bool indicate(void) const {return _indicate; }
+ bool authSignedWrite(void) const {return _authSignedWrite;}
/**
* @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t
*
- * @param[in] lhs The left hand side of the equality expression
- * @param[in] rhs The right hand side of the equality expression
+ * @param lhs[in] The left hand side of the equality expression
+ * @param rhs[in] The right hand side of the equality expression
*
* @return true if operands are equals, false otherwise.
*/
@@ -167,9 +101,8 @@
* than ATT_MTU - 1, this function must be called multiple times with
* appropriate offset to read the complete value.
*
- * @param[in] offset
- * The position - in the characteristic value bytes stream - where
- * the read operation begin.
+ * @param offset[in] The position - in the characteristic value bytes stream - where
+ * the read operation begin.
*
* @return BLE_ERROR_NONE if a read has been initiated, or
* BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
@@ -182,11 +115,9 @@
* @brief Same as #read(uint16_t) const but allow the user to register a callback
* which will be fired once the read is done.
*
- * @param[in] offset
- * The position - in the characteristic value bytes stream - where
- * the read operation begin.
- * @param[in] onRead
- * Continuation of the read operation
+ * @param offset[in] The position - in the characteristic value bytes stream - where
+ * the read operation begin.
+ * @param onRead[in] Continuation of the read operation
*/
ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const;
@@ -243,21 +174,12 @@
ble_error_t write(uint16_t length, const uint8_t *value) const;
/**
- * Same as write(uint16_t, const uint8_t *) const but register a callback
+ * Same as #write(uint16_t, const uint8_t *) const but register a callback
* which will be called once the data has been written.
*
- * @param[in] length
- * The amount of bytes to write.
- * @param[in] value
- * The bytes to write.
- * @param[in] onWrite
- * Continuation callback for the write operation
- *
- * @retval BLE_ERROR_NONE Successfully started the Write procedure, or
- * BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
- * BLE_STACK_BUSY if some client procedure is already in progress, or
- * BLE_ERROR_NO_MEM if there are no available buffers left to process the request, or
- * BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's properties.
+ * @param[in] length The amount of bytes to write.
+ * @param[in] value The bytes to write.
+ * @param[in] onRead Continuation callback for the write operation
*/
ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onWrite) const;
@@ -284,7 +206,7 @@
/**
* @brief Get the declaration handle of this characteristic.
- * @details The declaration handle is the first handle of a characteristic
+ * @detail The declaration handle is the first handle of a characteristic
* definition. The value accessible at this handle contains the following
* informations:
* - The characteristics properties (see Properties_t). This value can
@@ -353,10 +275,8 @@
/**
* @brief "Equal to" operator for DiscoveredCharacteristic
*
- * @param[in] lhs
- * The left hand side of the equality expression
- * @param[in] rhs
- * The right hand side of the equality expression
+ * @param lhs[in] The left hand side of the equality expression
+ * @param rhs[in] The right hand side of the equality expression
*
* @return true if operands are equals, false otherwise.
*/
@@ -373,12 +293,10 @@
/**
* @brief "Not equal to" operator for DiscoveredCharacteristic
*
- * @param[in] lhs
- * The right hand side of the expression
- * @param[in] rhs
- * The left hand side of the expression
+ * @param lhs[in] The right hand side of the expression
+ * @param rhs[in] The left hand side of the expression
*
- * @return true if operands are not equal, false otherwise.
+ * @return true if operands are not equals, false otherwise.
*/
friend bool operator !=(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) {
return !(lhs == rhs);
@@ -396,37 +314,15 @@
}
protected:
- /**
- * Pointer to the underlying GattClient for this DiscoveredCharacteristic object.
- */
GattClient *gattc;
protected:
- /**
- * Discovered characteristic's UUID.
- */
UUID uuid;
- /**
- * Hold the configured properties of the discovered characteristic.
- * For more information refer to Properties_t.
- */
Properties_t props;
- /**
- * Value handle of the discovered characteristic's declaration attribute.
- */
GattAttribute::Handle_t declHandle;
- /**
- * Value handle of the discovered characteristic's value attribute.
- */
GattAttribute::Handle_t valueHandle;
- /**
- * Value handle of the discovered characteristic's last attribute.
- */
GattAttribute::Handle_t lastHandle;
- /**
- * Handle for the connection where the characteristic was discovered.
- */
Gap::Handle_t connHandle;
};
--- a/ble/DiscoveredCharacteristicDescriptor.h Wed Apr 06 19:15:28 2016 +0100 +++ b/ble/DiscoveredCharacteristicDescriptor.h Wed Apr 06 19:15:30 2016 +0100 @@ -28,7 +28,7 @@ * discovery procedure (see GattClient::discoverCharacteristicDescriptors or * DiscoveredCharacteristic::discoverDescriptors ). * - * @details Provide detailed informations about a discovered characteristic descriptor + * @detail Provide detailed informations about a discovered characteristic descriptor * like: * - Its UUID (see #getUUID). * - Its handle (see #getAttributeHandle)
--- a/ble/DiscoveredService.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/DiscoveredService.h Wed Apr 06 19:15:30 2016 +0100
@@ -25,82 +25,34 @@
*/
class DiscoveredService {
public:
- /**
- * Set information about the discovered service.
- *
- * @param[in] uuidIn
- * The UUID of the discovered service.
- * @param[in] startHandleIn
- * The start handle of the discovered service in the peer's
- * ATT table.
- * @param[in] endHandleIn
- * The end handle of the discovered service in the peer's
- * ATT table.
- */
- void setup(UUID uuidIn, GattAttribute::Handle_t startHandleIn, GattAttribute::Handle_t endHandleIn) {
- uuid = uuidIn;
- startHandle = startHandleIn;
- endHandle = endHandleIn;
- }
+ void setup(UUID uuidIn, GattAttribute::Handle_t startHandleIn, GattAttribute::Handle_t endHandleIn) {
+ uuid = uuidIn;
+ startHandle = startHandleIn;
+ endHandle = endHandleIn;
+ }
- /**
- * Set the start and end handle of the discovered service.
- * @param[in] startHandleIn
- * The start handle of the discovered service in the peer's
- * ATT table.
- * @param[in] endHandleIn
- * The end handle of the discovered service in the peer's
- * ATT table.
- */
- void setup(GattAttribute::Handle_t startHandleIn, GattAttribute::Handle_t endHandleIn) {
- startHandle = startHandleIn;
- endHandle = endHandleIn;
- }
+ void setup(GattAttribute::Handle_t startHandleIn, GattAttribute::Handle_t endHandleIn) {
+ startHandle = startHandleIn;
+ endHandle = endHandleIn;
+ }
- /**
- * Set the long UUID of the discovered service.
- *
- * @param[in] longUUID
- * The long UUID of the discovered service.
- * @param[in] order
- * The byte ordering of @p longUUID.
- */
void setupLongUUID(UUID::LongUUIDBytes_t longUUID, UUID::ByteOrder_t order = UUID::MSB) {
uuid.setupLong(longUUID, order);
}
public:
- /**
- * Get the UUID of the discovered service.
- *
- * @return A reference to the UUID of the discovered service.
- */
const UUID &getUUID(void) const {
return uuid;
}
- /**
- * Get the start handle of the discovered service in the peer's ATT table.
- *
- * @return A reference to the start handle.
- */
const GattAttribute::Handle_t& getStartHandle(void) const {
return startHandle;
}
-
- /**
- * Get the end handle of the discovered service in the peer's ATT table.
- *
- * @return A reference to the end handle.
- */
const GattAttribute::Handle_t& getEndHandle(void) const {
return endHandle;
}
public:
- /**
- * Construct a DiscoveredService instance.
- */
DiscoveredService() : uuid(UUID::ShortUUIDBytes_t(0)),
startHandle(GattAttribute::INVALID_HANDLE),
endHandle(GattAttribute::INVALID_HANDLE) {
--- a/ble/Gap.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/Gap.h Wed Apr 06 19:15:30 2016 +0100
@@ -40,24 +40,23 @@
/**
* Address-type for BLEProtocol addresses.
*
- * @deprecated Use BLEProtocol::AddressType_t instead.
+ * @note: deprecated. Use BLEProtocol::AddressType_t instead.
*/
typedef BLEProtocol::AddressType_t AddressType_t;
/**
* Address-type for BLEProtocol addresses.
- *
- * @deprecated Use BLEProtocol::AddressType_t instead.
+ * @note: deprecated. Use BLEProtocol::AddressType_t instead.
*/
typedef BLEProtocol::AddressType_t addr_type_t;
/**
* Address-type for BLEProtocol addresses.
+ * \deprecated: Use BLEProtocol::AddressType_t instead.
*
- * @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_*.
+ * DEPRECATION ALERT: 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,
@@ -66,27 +65,11 @@
ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE
};
- /**
- * 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;
+ 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. */
public:
- /**
- * Enumeration for timeout sources.
- */
enum TimeoutSource_t {
TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */
TIMEOUT_SRC_SECURITY_REQUEST = 0x01, /**< Security request timeout. */
@@ -154,94 +137,51 @@
* @experimental
*/
struct Whitelist_t {
- 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. */
+ BLEProtocol::Address_t *addresses;
+ uint8_t size;
+ uint8_t capacity;
};
- /**
- * 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. */
};
- /**
- * Type for connection handle.
- */
- typedef uint16_t Handle_t;
+ typedef uint16_t Handle_t; /* Type for connection handle. */
- /**
- * 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 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.*/
+ 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.*/
} 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; /**< 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. */
+ BLEProtocol::AddressBytes_t peerAddr;
+ int8_t rssi;
+ bool isScanResponse;
+ GapAdvertisingParams::AdvertisingType_t type;
+ uint8_t advertisingDataLen;
+ const uint8_t *advertisingData;
};
-
- /**
- * 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; /**< 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 */
+ 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;
- /**
- * 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,
@@ -261,22 +201,10 @@
}
};
- /**
- * Structure that encapsulates information about a disconnection event.
- * Refer to Gap::onDisconnection().
- */
struct DisconnectionCallbackParams_t {
- Handle_t handle; /**< The ID of the connection that caused the disconnection event */
- DisconnectionReason_t reason; /**< The reason of the disconnection event */
+ Handle_t handle;
+ DisconnectionReason_t reason;
- /**
- * 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),
@@ -285,63 +213,22 @@
};
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;
/*
@@ -352,11 +239,6 @@
* 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) {
@@ -370,11 +252,6 @@
/**
* 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) {
@@ -386,44 +263,28 @@
}
/**
- * 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. */
}
@@ -440,18 +301,17 @@
/**
* Create a connection (GAP Link Establishment).
*
- * @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.
- *
+ * @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.
* @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,
@@ -469,12 +329,11 @@
/**
* 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,
@@ -489,12 +348,8 @@
* be communicated to the application with an invocation of the
* disconnectionCallback.
*
- * @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.
+ * @param reason
+ * The reason for disconnection; to be sent back to the peer.
*/
virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
/* avoid compiler warnings about unused variables */
@@ -509,15 +364,13 @@
* be communicated to the application with an invocation of the
* disconnectionCallback.
*
- * @param[in] reason
- * The reason for disconnection; to be sent back to the peer.
- *
- * @return BLE_ERROR_NONE if disconnection was successful.
+ * @param reason
+ * The reason for disconnection; to be sent back to the peer.
*
- * @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.
+ * @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.
*/
virtual ble_error_t disconnect(DisconnectionReason_t reason) {
/* Avoid compiler warnings about unused variables. */
@@ -536,7 +389,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. */
@@ -552,9 +405,6 @@
*
* @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. */
@@ -564,18 +414,16 @@
}
/**
- * 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 */
@@ -587,11 +435,8 @@
/**
* 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. */
@@ -602,25 +447,21 @@
/**
* 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 */
@@ -632,11 +473,8 @@
/**
* 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. */
@@ -647,12 +485,8 @@
/**
* Get the appearance characteristic in the GAP service.
- *
* @param[out] appearance
- * The current device-appearance value.
- *
- * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
- * from the underlying BLE stack.
+ * The new value for the device-appearance.
*/
virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
/* Avoid compiler warnings about unused variables. */
@@ -663,12 +497,7 @@
/**
* Set the radio's transmit power.
- *
- * @param[in] txPower
- * Radio's transmit power in dBm.
- *
- * @return BLE_ERROR_NONE if the new radio's transmit power was set
- * correctly.
+ * @param[in] txPower Radio transmit power in dBm.
*/
virtual ble_error_t setTxPower(int8_t txPower) {
/* Avoid compiler warnings about unused variables. */
@@ -694,14 +523,8 @@
}
/**
- * 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
@@ -713,7 +536,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
@@ -851,15 +674,6 @@
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. */
@@ -870,10 +684,8 @@
*/
public:
/**
- * Get 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.
- *
- * @return The current GAP state of the device.
*/
GapState_t getState(void) const {
return state;
@@ -881,17 +693,12 @@
/**
* 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
@@ -902,15 +709,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
- * @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.
+ * @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.
*/
void setAdvertisingInterval(uint16_t interval) {
if (interval == 0) {
@@ -922,9 +729,6 @@
}
/**
- * 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.
@@ -935,8 +739,6 @@
/**
* Start advertising.
- *
- * @return BLE_ERROR_NONE if the device started advertising successfully.
*/
ble_error_t startAdvertising(void) {
setAdvertisingData(); /* Update the underlying stack. */
@@ -963,9 +765,6 @@
* 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;
@@ -982,11 +781,8 @@
* as an additional 31 bytes if the advertising payload is too
* small.
*
- * @param[in] app
- * The appearance of the peripheral.
- *
- * @return BLE_ERROR_NONE if the data was successfully added to the
- * advertising payload.
+ * @param app
+ * The appearance of the peripheral.
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
setAppearance(app);
@@ -1005,11 +801,8 @@
* as an additional 31 bytes if the advertising payload is too
* small.
*
- * @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.
+ * @param power
+ * The max transmit power to be used by the controller (in dBm).
*/
ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
ble_error_t rc;
@@ -1026,12 +819,9 @@
* The SCAN_RESPONSE message may be used as an additional 31 bytes if the
* advertising payload is too small.
*
- * @param[in] type
- * The type describing the variable length data.
- * @param[in] data
- * Data bytes.
- * @param[in] len
- * Length of data.
+ * @param type The type describing the variable length data.
+ * @param data Data bytes.
+ * @param len Length of data.
*
* @return BLE_ERROR_NONE if the advertisement payload was updated based on
* matching AD type; otherwise, an appropriate error.
@@ -1060,14 +850,11 @@
* 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.
@@ -1088,15 +875,7 @@
/**
* 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 (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.
+ * there are other APIs to build an advertisement payload (see above).
*/
ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) {
_advPayload = payload;
@@ -1104,11 +883,8 @@
}
/**
- * Get a reference to the advertising payload.
- *
- * @return Read back advertising data.
- *
- * @note Useful for storing and restoring payload.
+ * @return Read back advertising data. Useful for storing and
+ * restoring payload.
*/
const GapAdvertisingData &getAdvertisingPayload(void) const {
return _advPayload;
@@ -1118,15 +894,9 @@
* 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.
- *
- * @return BLE_ERROR_NONE if the data was successfully added to the scan
- * response payload.
+ * @param[in] type The type describing the variable length data.
+ * @param[in] data Data bytes.
+ * @param[in] len Length of data.
*/
ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
ble_error_t rc;
@@ -1139,10 +909,10 @@
/**
* Reset any scan response prepared from prior calls to
- * Gap::accumulateScanResponse().
+ * accumulateScanResponse().
*
- * @note This should be followed by a call to Gap::setAdvertisingPayload() or
- * Gap::startAdvertising() before the update takes effect.
+ * Note: This should be followed by a call to setAdvertisingPayload() or
+ * startAdvertising() before the update takes effect.
*/
void clearScanResponse(void) {
_scanResponse.clear();
@@ -1151,7 +921,6 @@
/**
* 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
@@ -1162,19 +931,17 @@
* Set to True if active-scanning is required. This is used to fetch the
* scan response from a peer if possible.
*
- * @return BLE_ERROR_NONE if the scan parameters were correctly set.
+ * 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 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.
+ * Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
*
- * @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.
+ * @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,
@@ -1193,21 +960,18 @@
/**
* 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].
*
- * @return BLE_ERROR_NONE if the scan interval was correctly set.
+ * 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 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().
+ * 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);
@@ -1215,24 +979,21 @@
/**
* 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].
*
- * @return BLE_ERROR_NONE if the scan window was correctly set.
+ * 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 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.
+ * Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
*
- * @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.
+ * 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;
@@ -1250,17 +1011,14 @@
/**
* Set up parameters for GAP scanning (observer mode).
- *
* @param[in] timeout
* Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
*
- * @return BLE_ERROR_NONE if the scan timeout was correctly set.
+ * Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
*
- * @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.
+ * 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;
@@ -1277,19 +1035,16 @@
}
/**
- * Modify the active scanning parameter for GAP scanning (observer mode).
- * This is used to fetch the scan response from a peer if possible.
- *
+ * Set up parameters for GAP scanning (observer mode).
* @param[in] activeScanning
- * Set to True if active-scanning is required.
+ * Set to True if active-scanning is required. This is used to fetch the
+ * scan response from a peer if possible.
*
- * @return BLE_ERROR_NONE if active scanning was successfully set.
+ * Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
*
- * @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.
+ * 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);
@@ -1310,9 +1065,6 @@
* 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;
@@ -1327,19 +1079,7 @@
}
/**
- * Same as 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.
+ * Same as above, but this takes an (object, method) pair for a callback.
*/
template<typename T>
ble_error_t startScan(T *object, void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)) {
@@ -1376,58 +1116,21 @@
}
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:
/**
- * Accessor to read back currently active advertising parameters.
- *
- * @return A reference to the current advertising parameters.
+ * Accessors to read back currently active advertising params.
*/
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;
}
@@ -1437,9 +1140,6 @@
* 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;
@@ -1450,24 +1150,17 @@
/**
* Set up a callback for timeout events. Refer to TimeoutSource_t for
* possible event types.
- *
- * @param[in] callback
- * Event handler being registered.
- *
- * @note It is possible to unregister callbacks using onTimeout().detach(callback).
+ * @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.
- *
- * @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.
+ * @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
*/
TimeoutEventCallbackChain_t& onTimeout() {
return timeoutCallbackChain;
@@ -1475,41 +1168,18 @@
/**
* 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);
- }
+ 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);}
/**
- * Same as 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).
+ * @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
*/
ConnectionEventCallbackChain_t& onConnection() {
return connectionCallChain;
@@ -1517,41 +1187,18 @@
/**
* Append to a chain of callbacks to be invoked upon GAP disconnection.
- *
- * @param[in] callback
- Event handler being registered.
- *
- * @note It is possible to unregister callbacks using onDisconnection().detach(callback).
+ * @note It is possible to unregister callbacks using onDisconnection().detach(callback)
*/
- void onDisconnection(DisconnectionEventCallback_t callback) {
- disconnectionCallChain.add(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);}
/**
- * Same as 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).
+ * @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
*/
DisconnectionEventCallbackChain_t& onDisconnection() {
return disconnectionCallChain;
@@ -1571,26 +1218,22 @@
* 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[in] callback
- * The application handler to be invoked in response to a radio
- * ACTIVE/INACTIVE 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.
*/
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);
@@ -1601,48 +1244,28 @@
* Gap instance is about to shutdown (possibly as a result of a call
* to BLE::shutdown()).
*
- * @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
+ * @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.
- *
- * @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).
+ * @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
*/
GapShutdownCallbackChain_t& onShutdown() {
return shutdownCallChain;
@@ -1661,7 +1284,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) {
@@ -1691,9 +1314,6 @@
}
protected:
- /**
- * Construct a Gap instance.
- */
Gap() :
_advParams(),
_advPayload(),
@@ -1712,26 +1332,6 @@
/* 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,
@@ -1744,40 +1344,12 @@
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,
@@ -1794,79 +1366,33 @@
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 (source == TIMEOUT_SRC_ADVERTISING) {
+ /* Update gap state if the source is an advertising timeout */
+ state.advertising = 0;
+ }
if (timeoutCallbackChain) {
timeoutCallbackChain(source);
}
}
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/GapAdvertisingData.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GapAdvertisingData.h Wed Apr 06 19:15:30 2016 +0100
@@ -24,125 +24,125 @@
#define GAP_ADVERTISING_DATA_MAX_PAYLOAD (31)
-/**
- * @brief This class provides several helper functions to generate properly
- * formatted GAP Advertising and Scan Response data payloads.
- *
- * @note See Bluetooth Specification 4.0 (Vol. 3), Part C, Sections 11 and 18
- * for further information on Advertising and Scan Response data.
- *
- * @par Advertising and Scan Response Payloads
- * Advertising data and Scan Response data are organized around a set of
- * data types called 'AD types' in Bluetooth 4.0 (see the Bluetooth Core
- * Specification v4.0, Vol. 3, Part C, Sections 11 and 18).
- *
- * @par
- * Each AD type has its own standardized assigned number, as defined
- * by the Bluetooth SIG:
- * https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile.
- *
- * @par
- * For convenience, all appropriate AD types are encapsulated
- * in GapAdvertisingData::DataType.
- *
- * @par
- * Before the AD Types and their payload (if any) can be inserted into
- * the Advertising or Scan Response frames, they need to be formatted as
- * follows:
- *
- * @li @c Record length (1 byte).
- * @li @c AD Type (1 byte).
- * @li @c AD payload (optional; only present if record length > 1).
- *
- * @par
- * This class takes care of properly formatting the payload, performs
- * some basic checks on the payload length, and tries to avoid common
- * errors like adding an exclusive AD field twice in the Advertising
- * or Scan Response payload.
- *
- * @par EXAMPLE
- *
- * @code
- *
- * // ToDo
- *
- * @endcode
- */
+/**************************************************************************/
+/*!
+ \brief
+ This class provides several helper functions to generate properly
+ formatted GAP Advertising and Scan Response data payloads.
+
+ \note
+ See Bluetooth Specification 4.0 (Vol. 3), Part C, Sections 11 and 18
+ for further information on Advertising and Scan Response data.
+
+ \par Advertising and Scan Response Payloads
+ Advertising data and Scan Response data are organized around a set of
+ data types called 'AD types' in Bluetooth 4.0 (see the Bluetooth Core
+ Specification v4.0, Vol. 3, Part C, Sections 11 and 18).
+
+ \par
+ Each AD type has its own standardized assigned number, as defined
+ by the Bluetooth SIG:
+ https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
+
+ \par
+ For convenience, all appropriate AD types are encapsulated
+ in GapAdvertisingData::DataType.
+
+ \par
+ Before the AD Types and their payload (if any) can be inserted into
+ the Advertising or Scan Response frames, they need to be formatted as
+ follows:
+
+ \li \c Record length (1 byte).
+ \li \c AD Type (1 byte).
+ \li \c AD payload (optional; only present if record length > 1).
+
+ \par
+ This class takes care of properly formatting the payload, performs
+ some basic checks on the payload length, and tries to avoid common
+ errors like adding an exclusive AD field twice in the Advertising
+ or Scan Response payload.
+
+ \par EXAMPLE
+
+ \code
+
+ // ToDo
+
+ \endcode
+*/
+/**************************************************************************/
class GapAdvertisingData
{
public:
+ /**********************************************************************/
/*!
- * @brief A list of Advertising Data types commonly used by peripherals.
- * These AD types are used to describe the capabilities of the
- * peripheral, and are inserted inside the advertising or scan
- * response payloads.
- *
- * @par Source
- *
- * @li @c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 11, 18.
- * @li @c https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile.
- */
+ \brief
+ A list of Advertising Data types commonly used by peripherals.
+ These AD types are used to describe the capabilities of the
+ peripheral, and are inserted inside the advertising or scan
+ response payloads.
+
+ \par Source
+ \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 11, 18
+ \li \c https://www.bluetooth.org/en-us/specification/assigned-numbers/generic-access-profile
+ */
+ /**********************************************************************/
enum DataType_t {
- FLAGS = 0x01, /**< Flags, refer to GapAdvertisingData::Flags_t. */
- INCOMPLETE_LIST_16BIT_SERVICE_IDS = 0x02, /**< Incomplete list of 16-bit Service IDs. */
- COMPLETE_LIST_16BIT_SERVICE_IDS = 0x03, /**< Complete list of 16-bit Service IDs. */
- INCOMPLETE_LIST_32BIT_SERVICE_IDS = 0x04, /**< Incomplete list of 32-bit Service IDs (not relevant for Bluetooth 4.0). */
- COMPLETE_LIST_32BIT_SERVICE_IDS = 0x05, /**< Complete list of 32-bit Service IDs (not relevant for Bluetooth 4.0). */
- INCOMPLETE_LIST_128BIT_SERVICE_IDS = 0x06, /**< Incomplete list of 128-bit Service IDs. */
- COMPLETE_LIST_128BIT_SERVICE_IDS = 0x07, /**< Complete list of 128-bit Service IDs. */
- SHORTENED_LOCAL_NAME = 0x08, /**< Shortened Local Name. */
- COMPLETE_LOCAL_NAME = 0x09, /**< Complete Local Name. */
- TX_POWER_LEVEL = 0x0A, /**< TX Power Level (in dBm). */
- DEVICE_ID = 0x10, /**< Device ID. */
- SLAVE_CONNECTION_INTERVAL_RANGE = 0x12, /**< Slave Connection Interval Range. */
- LIST_128BIT_SOLICITATION_IDS = 0x15, /**< List of 128 bit service UUIDs the device is looking for. */
- SERVICE_DATA = 0x16, /**< Service Data. */
- APPEARANCE = 0x19, /**< Appearance, refer to GapAdvertisingData::Appearance_t. */
- ADVERTISING_INTERVAL = 0x1A, /**< Advertising Interval. */
- MANUFACTURER_SPECIFIC_DATA = 0xFF /**< Manufacturer Specific Data. */
+ FLAGS = 0x01, /**< \ref *Flags */
+ INCOMPLETE_LIST_16BIT_SERVICE_IDS = 0x02, /**< Incomplete list of 16-bit Service IDs */
+ COMPLETE_LIST_16BIT_SERVICE_IDS = 0x03, /**< Complete list of 16-bit Service IDs */
+ INCOMPLETE_LIST_32BIT_SERVICE_IDS = 0x04, /**< Incomplete list of 32-bit Service IDs (not relevant for Bluetooth 4.0) */
+ COMPLETE_LIST_32BIT_SERVICE_IDS = 0x05, /**< Complete list of 32-bit Service IDs (not relevant for Bluetooth 4.0) */
+ INCOMPLETE_LIST_128BIT_SERVICE_IDS = 0x06, /**< Incomplete list of 128-bit Service IDs */
+ COMPLETE_LIST_128BIT_SERVICE_IDS = 0x07, /**< Complete list of 128-bit Service IDs */
+ SHORTENED_LOCAL_NAME = 0x08, /**< Shortened Local Name */
+ COMPLETE_LOCAL_NAME = 0x09, /**< Complete Local Name */
+ TX_POWER_LEVEL = 0x0A, /**< TX Power Level (in dBm) */
+ DEVICE_ID = 0x10, /**< Device ID */
+ SLAVE_CONNECTION_INTERVAL_RANGE = 0x12, /**< Slave Connection Interval Range */
+ LIST_128BIT_SOLICITATION_IDS = 0x15, /**< List of 128 bit service UUIDs the device is looking for */
+ SERVICE_DATA = 0x16, /**< Service Data */
+ APPEARANCE = 0x19, /**< \ref Appearance */
+ ADVERTISING_INTERVAL = 0x1A, /**< Advertising Interval */
+ MANUFACTURER_SPECIFIC_DATA = 0xFF /**< Manufacturer Specific Data */
};
- /**
- * Type alias for GapAdvertisingData::DataType_t.
- *
- * @deprecated This type alias will be dropped in future releases.
- */
- typedef enum DataType_t DataType;
+ typedef enum DataType_t DataType; /* Deprecated type alias. This may be dropped in a future release. */
+
+ /**********************************************************************/
+ /*!
+ \brief
+ A list of values for the FLAGS AD Type.
- /**
- * @brief A list of values for the FLAGS AD Type.
- *
- * @note You can use more than one value in the FLAGS AD Type (ex.
- * LE_GENERAL_DISCOVERABLE and BREDR_NOT_SUPPORTED).
- *
- * @par Source
- *
- * @li @c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 18.1.
- */
+ \note
+ You can use more than one value in the FLAGS AD Type (ex.
+ LE_GENERAL_DISCOVERABLE and BREDR_NOT_SUPPORTED).
+
+ \par Source
+ \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 18.1
+ */
+ /**********************************************************************/
enum Flags_t {
- LE_LIMITED_DISCOVERABLE = 0x01, /**< Peripheral device is discoverable for a limited period of time. */
+ LE_LIMITED_DISCOVERABLE = 0x01, /**< *Peripheral device is discoverable for a limited period of time. */
LE_GENERAL_DISCOVERABLE = 0x02, /**< Peripheral device is discoverable at any moment. */
BREDR_NOT_SUPPORTED = 0x04, /**< Peripheral device is LE only. */
SIMULTANEOUS_LE_BREDR_C = 0x08, /**< Not relevant - central mode only. */
SIMULTANEOUS_LE_BREDR_H = 0x10 /**< Not relevant - central mode only. */
};
- /**
- * Type alias for GapAdvertisingData::Flags_t.
- *
- * @deprecated This type alias will be dropped in future releases.
- */
- typedef enum Flags_t Flags;
+ typedef enum Flags_t Flags; /* Deprecated type alias. This may be dropped in a future release. */
- /**
- * @brief
- * A list of values for the APPEARANCE AD Type, which describes the
- * physical shape or appearance of the device.
- *
- * @par Source
- *
- * @li @c Bluetooth Core Specification Supplement, Part A, Section 1.12.
- * @li @c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 12.2.
- * @li @c https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml.
- */
+ /**********************************************************************/
+ /*!
+ \brief
+ A list of values for the APPEARANCE AD Type, which describes the
+ physical shape or appearance of the device.
+
+ \par Source
+ \li \c Bluetooth Core Specification Supplement, Part A, Section 1.12
+ \li \c Bluetooth Core Specification 4.0 (Vol. 3), Part C, Section 12.2
+ \li \c https://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml
+ */
+ /**********************************************************************/
enum Appearance_t {
UNKNOWN = 0, /**< Unknown or unspecified appearance type. */
GENERIC_PHONE = 64, /**< Generic Phone. */
@@ -194,22 +194,14 @@
OUTDOOR_LOCATION_POD = 5187, /**< Outdoor Location Pod. */
OUTDOOR_LOCATION_AND_NAVIGATION_POD = 5188 /**< Outdoor Location and Navigation Pod. */
};
- /**
- * Type alias for GapAdvertisingData::Appearance_t.
- *
- * @deprecated This type alias will be dropped in future releases.
- */
- typedef enum Appearance_t Appearance;
+ typedef enum Appearance_t Appearance; /* Deprecated type alias. This may be dropped in a future release. */
- /**
- * Empty constructor.
- */
GapAdvertisingData(void) : _payload(), _payloadLen(0), _appearance(GENERIC_TAG) {
/* empty */
}
/**
- * Adds advertising data based on the specified AD type (see GapAdvertisingData::DataType_t).
+ * Adds advertising data based on the specified AD type (see DataType).
* If the supplied AD type is already present in the advertising
* payload, then the value is updated.
*
@@ -230,14 +222,14 @@
*/
ble_error_t addData(DataType_t advDataType, const uint8_t *payload, uint8_t len)
{
- /* Find field */
+ // find field
uint8_t* field = findField(advDataType);
if (field) {
- /* Field type already exist, either add to field or replace */
+ // Field type already exist, either add to field or replace
return addField(advDataType, payload, len, field);
} else {
- /* Field doesn't exists, insert new */
+ // field doesn't exists, insert new
return appendField(advDataType, payload, len);
}
}
@@ -257,14 +249,14 @@
*/
ble_error_t updateData(DataType_t advDataType, const uint8_t *payload, uint8_t len)
{
- /* Find field */
+ // find field
uint8_t* field = findField(advDataType);
if (field) {
- /* Field type already exist, replace field contents */
+ // Field type already exist, replace field contents
return updateField(advDataType, payload, len, field);
} else {
- /* field doesn't exists, return an error */
+ // field doesn't exists, return an error
return BLE_ERROR_UNSPECIFIED;
}
}
@@ -276,7 +268,7 @@
* The APPEARANCE value to add.
*
* @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
- * advertising buffer to overflow, else BLE_ERROR_NONE.
+ * advertising buffer to overflow, else BLE_ERROR_NONE.
*/
ble_error_t addAppearance(Appearance appearance = GENERIC_TAG) {
_appearance = appearance;
@@ -285,17 +277,16 @@
/**
* Helper function to add FLAGS data to the advertising payload.
- *
- * @param[in] flags
- * LE_LIMITED_DISCOVERABLE
- * The peripheral is discoverable for a limited period of time.
- * LE_GENERAL_DISCOVERABLE
- * The peripheral is permanently discoverable.
- * BREDR_NOT_SUPPORTED
- * This peripheral is a Bluetooth Low Energy only device (no EDR support).
+ * @param flags
+ * LE_LIMITED_DISCOVERABLE
+ * The peripheral is discoverable for a limited period of time.
+ * LE_GENERAL_DISCOVERABLE
+ * The peripheral is permanently discoverable.
+ * BREDR_NOT_SUPPORTED
+ * This peripheral is a Bluetooth Low Energy only device (no EDR support).
*
* @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
- * advertising buffer to overflow, else BLE_ERROR_NONE.
+ * advertising buffer to overflow, else BLE_ERROR_NONE.
*/
ble_error_t addFlags(uint8_t flags = LE_GENERAL_DISCOVERABLE) {
return addData(GapAdvertisingData::FLAGS, &flags, 1);
@@ -305,7 +296,7 @@
* Helper function to add TX_POWER_LEVEL data to the advertising payload.
*
* @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
- * advertising buffer to overflow, else BLE_ERROR_NONE.
+ * advertising buffer to overflow, else BLE_ERROR_NONE.
*/
ble_error_t addTxPower(int8_t txPower) {
/* To Do: Basic error checking to make sure txPower is in range. */
@@ -321,40 +312,30 @@
}
/**
- * Access the current payload.
- *
- * @return A pointer to the current payload.
+ * Returns a pointer to the current payload.
*/
const uint8_t *getPayload(void) const {
return _payload;
}
/**
- * Get the current payload length.
- *
- * @return The current payload length (0..31 bytes).
+ * Returns the current payload length (0..31 bytes).
*/
uint8_t getPayloadLen(void) const {
return _payloadLen;
}
/**
- * Get the current appearance value.
- *
- * @return The 16-bit appearance value for this device.
+ * Returns the 16-bit appearance value for this device.
*/
uint16_t getAppearance(void) const {
return (uint16_t)_appearance;
}
/**
- * Search advertisement data for a specific field.
- *
- * @param[in] type
- * The type of the field to find.
- *
- * @return A pointer to the first element in the field if found, NULL otherwise.
- * Where the first element is the length of the field.
+ * Search advertisement data for field.
+ * Returns pointer to the first element in the field if found, NULL otherwise.
+ * Where the first element is the length of the field.
*/
const uint8_t* findField(DataType_t type) const {
return findField(type);
@@ -362,19 +343,7 @@
private:
/**
- * Append advertising data based on the specified AD type (see
- * GapAdvertisingData::DataType_t).
- *
- * @param[in] advDataType
- * The type of the new data.
- * @param[in] payload
- * A pointer to the data to be appended to the advertising
- * payload.
- * @param[in] len
- * The length of th data pointed to by @p payload.
- *
- * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
- * advertising buffer to overflow, else BLE_ERROR_NONE.
+ * Append advertising data based on the specified AD type (see DataType)
*/
ble_error_t appendField(DataType advDataType, const uint8_t *payload, uint8_t len)
{
@@ -400,15 +369,11 @@
/**
* Search advertisement data for field.
- *
- * @param[in] type
- * The type of the data to find.
- *
- * @return A pointer to the first element in the field if found, NULL
- * otherwise. Where the first element is the length of the field.
+ * Returns pointer to the first element in the field if found, NULL otherwise.
+ * Where the first element is the length of the field.
*/
uint8_t* findField(DataType_t type) {
- /* Scan through advertisement data */
+ // scan through advertisement data
for (uint8_t idx = 0; idx < _payloadLen; ) {
uint8_t fieldType = _payload[idx + 1];
@@ -416,11 +381,11 @@
return &_payload[idx];
}
- /* Advance to next field */
+ // advance to next field
idx += _payload[idx] + 1;
}
- /* Field not found */
+ // field not found
return NULL;
}
@@ -428,17 +393,6 @@
* Given the a pointer to a field in the advertising payload it replaces
* the existing data in the field with the supplied data.
*
- * @param[in] advDataType
- * The type of the new data.
- * @param[in] payload
- * A pointer to the data to be added to the advertising
- * payload.
- * @param[in] len
- * The length of th data pointed to by @p payload.
- * @param[in] field
- * A pointer to the field of type @p advDataType in the
- * advertising buffer.
- *
* When the specified AD type is INCOMPLETE_LIST_16BIT_SERVICE_IDS,
* COMPLETE_LIST_16BIT_SERVICE_IDS, INCOMPLETE_LIST_32BIT_SERVICE_IDS,
* COMPLETE_LIST_32BIT_SERVICE_IDS, INCOMPLETE_LIST_128BIT_SERVICE_IDS,
@@ -446,14 +400,14 @@
* supplied value is appended to the values previously added to the
* payload.
*
- * @return BLE_ERROR_NONE on success.
+ * Returns BLE_ERROR_NONE on success.
*/
ble_error_t addField(DataType_t advDataType, const uint8_t *payload, uint8_t len, uint8_t* field)
{
ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW;
switch(advDataType) {
- /* These fields will have the new data appended if there is sufficient space */
+ // These fields will have the new data appended if there is sufficient space
case INCOMPLETE_LIST_16BIT_SERVICE_IDS:
case COMPLETE_LIST_16BIT_SERVICE_IDS:
case INCOMPLETE_LIST_32BIT_SERVICE_IDS:
@@ -461,13 +415,11 @@
case INCOMPLETE_LIST_128BIT_SERVICE_IDS:
case COMPLETE_LIST_128BIT_SERVICE_IDS:
case LIST_128BIT_SOLICITATION_IDS: {
- /* Check if data fits */
+ // check if data fits
if ((_payloadLen + len) <= GAP_ADVERTISING_DATA_MAX_PAYLOAD) {
- /*
- * Make room for new field by moving the remainder of the
- * advertisement payload "to the right" starting after the
- * TYPE field.
- */
+ // make room for new field by moving the remainder of the
+ // advertisement payload "to the right" starting after the
+ // TYPE field.
uint8_t* end = &_payload[_payloadLen];
while (&field[1] < end) {
@@ -475,12 +427,12 @@
end--;
}
- /* Insert new data */
+ // insert new data
for (uint8_t idx = 0; idx < len; idx++) {
field[2 + idx] = payload[idx];
}
- /* Increment lengths */
+ // increment lengths
field[0] += len;
_payloadLen += len;
@@ -489,7 +441,7 @@
break;
}
- /* These fields will be overwritten with the new value */
+ // These fields will be overwritten with the new value
default: {
result = updateField(advDataType, payload, len, field);
@@ -503,26 +455,14 @@
/**
* Given the a pointer to a field in the advertising payload it replaces
* the existing data in the field with the supplied data.
- *
- * @param[in] advDataType
- * The type of the data to be updated.
- * @param[in] payload
- * A pointer to the data to be updated to the advertising
- * payload.
- * @param[in] len
- * The length of th data pointed to by @p payload.
- * @param[in] field
- * A pointer to the field of type @p advDataType in the
- * advertising buffer.
- *
- * @return BLE_ERROR_NONE on success.
+ * Returns BLE_ERROR_NONE on success.
*/
ble_error_t updateField(DataType_t advDataType, const uint8_t *payload, uint8_t len, uint8_t* field)
{
ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW;
uint8_t dataLength = field[0] - 1;
- /* New data has same length, do in-order replacement */
+ // new data has same length, do in-order replacement
if (len == dataLength) {
for (uint8_t idx = 0; idx < dataLength; idx++) {
field[2 + idx] = payload[idx];
@@ -530,19 +470,19 @@
result = BLE_ERROR_NONE;
} else {
- /* Check if data fits */
+ // check if data fits
if ((_payloadLen - dataLength + len) <= GAP_ADVERTISING_DATA_MAX_PAYLOAD) {
- /* Remove old field */
+ // remove old field
while ((field + dataLength + 2) < &_payload[_payloadLen]) {
*field = field[dataLength + 2];
field++;
}
- /* Reduce length */
+ // reduce length
_payloadLen -= dataLength + 2;
- /* Add new field */
+ // add new field
result = appendField(advDataType, payload, len);
}
}
@@ -550,18 +490,9 @@
return result;
}
- /**
- * The advertising data buffer
- */
uint8_t _payload[GAP_ADVERTISING_DATA_MAX_PAYLOAD];
- /**
- * The length of the data added to the advertising buffer.
- */
uint8_t _payloadLen;
- /**
- * Appearance value.
- */
uint16_t _appearance;
};
-#endif /* ifndef __GAP_ADVERTISING_DATA_H__ */
\ No newline at end of file
+#endif // ifndef __GAP_ADVERTISING_DATA_H__
\ No newline at end of file
--- a/ble/GapAdvertisingParams.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GapAdvertisingParams.h Wed Apr 06 19:15:30 2016 +0100
@@ -25,55 +25,24 @@
*/
class GapAdvertisingParams {
public:
- /**
- * Minimum Advertising interval for connectable undirected and connectable
- * directed events in 625us units - 20ms.
- */
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN = 0x0020;
- /**
- * Minimum Advertising interval for scannable and non-connectable
- * undirected events in 625us units - 100ms.
- */
static const unsigned GAP_ADV_PARAMS_INTERVAL_MIN_NONCON = 0x00A0;
- /**
- * Maximum Advertising interval in 625us units - 10.24s.
- */
static const unsigned GAP_ADV_PARAMS_INTERVAL_MAX = 0x4000;
- /**
- * Maximum advertising timeout seconds.
- */
static const unsigned GAP_ADV_PARAMS_TIMEOUT_MAX = 0x3FFF;
- /**
+ /*!
* Encapsulates the peripheral advertising modes, which determine how
* the device appears to other central devices in hearing range.
*/
enum AdvertisingType_t {
- ADV_CONNECTABLE_UNDIRECTED, /**< Vol 3, Part C, Section 9.3.4 and Vol 6, Part B, Section 2.3.1.1. */
- ADV_CONNECTABLE_DIRECTED, /**< Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2. */
- ADV_SCANNABLE_UNDIRECTED, /**< Include support for Scan Response payloads, see Vol 6, Part B, Section 2.3.1.4. */
- ADV_NON_CONNECTABLE_UNDIRECTED /**< Vol 3, Part C, Section 9.3.2 and Vol 6, Part B, Section 2.3.1.3. */
+ ADV_CONNECTABLE_UNDIRECTED, /**< Vol 3, Part C, Section 9.3.4 and Vol 6, Part B, Section 2.3.1.1 */
+ ADV_CONNECTABLE_DIRECTED, /**< Vol 3, Part C, Section 9.3.3 and Vol 6, Part B, Section 2.3.1.2 */
+ ADV_SCANNABLE_UNDIRECTED, /**< Include support for Scan Response payloads, see Vol 6, Part B, Section 2.3.1.4 */
+ ADV_NON_CONNECTABLE_UNDIRECTED /**< Vol 3, Part C, Section 9.3.2 and Vol 6, Part B, Section 2.3.1.3 */
};
- /**
- * Type alias for GapAdvertisingParams::AdvertisingType_t.
- *
- * @deprecated This type alias will be dropped in future releases.
- */
- typedef enum AdvertisingType_t AdvertisingType;
+ typedef enum AdvertisingType_t AdvertisingType; /* Deprecated type alias. */
public:
- /**
- * Construct an instance of GapAdvertisingParams.
- *
- * @param[in] advType
- * Type of advertising. Default is
- * GapAdvertisingParams::ADV_CONNECTABLE_UNDIRECTED.
- * @param[in] interval
- * Advertising interval in units of 0.625ms. Default is
- * GapAdvertisingParams::GAP_ADV_PARAMS_INTERVAL_MIN_NONCON.
- * @param[in] timeout
- * Advertising timeout. Default is 0.
- */
GapAdvertisingParams(AdvertisingType_t advType = ADV_CONNECTABLE_UNDIRECTED,
uint16_t interval = GAP_ADV_PARAMS_INTERVAL_MIN_NONCON,
uint16_t timeout = 0) : _advType(advType), _interval(interval), _timeout(timeout) {
@@ -109,99 +78,43 @@
}
static const uint16_t UNIT_0_625_MS = 625; /**< Number of microseconds in 0.625 milliseconds. */
- /**
- * Convert milliseconds to units of 0.625ms.
- *
- * @param[in] durationInMillis
- * The number of milliseconds to convert.
- *
- * @return The value of @p durationInMillis in units of 0.625ms.
- */
static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis) {
return (durationInMillis * 1000) / UNIT_0_625_MS;
}
- /**
- * Convert units of 0.625ms to milliseconds.
- *
- * @param[in] gapUnits
- * The number of units of 0.625ms to convert.
- *
- * @return The value of @p gapUnits in milliseconds.
- */
static uint16_t ADVERTISEMENT_DURATION_UNITS_TO_MS(uint16_t gapUnits) {
return (gapUnits * UNIT_0_625_MS) / 1000;
}
- /**
- * Get the advertising type.
- *
- * @return The advertising type.
- */
AdvertisingType_t getAdvertisingType(void) const {
return _advType;
}
/**
- * Get the advertising interval in milliseconds.
- *
- * @return The advertisement interval (in milliseconds).
+ * @return the advertisement interval (in milliseconds).
*/
uint16_t getInterval(void) const {
return ADVERTISEMENT_DURATION_UNITS_TO_MS(_interval);
}
/**
- * Get the advertisement interval in units of 0.625ms.
- *
- * @return The advertisement interval in advertisement duration units (0.625ms units).
+ * @return the advertisement interval in advertisement duration units (0.625ms units).
*/
uint16_t getIntervalInADVUnits(void) const {
return _interval;
}
- /**
- * Get The advertising timeout.
- *
- * @return The advertising timeout (in seconds).
- */
uint16_t getTimeout(void) const {
return _timeout;
}
- /**
- * Set the advertising type.
- *
- * @param[in] newAdvType
- * The new advertising type.
- */
- void setAdvertisingType(AdvertisingType_t newAdvType) {
- _advType = newAdvType;
- }
-
- /**
- * Set the advertising interval in milliseconds.
- *
- * @param[in] newInterval
- * The new advertising interval in milliseconds.
- */
- void setInterval(uint16_t newInterval) {
- _interval = MSEC_TO_ADVERTISEMENT_DURATION_UNITS(newInterval);
- }
-
- /**
- * Set the advertising timeout.
- *
- * @param[in] newTimeout
- * The new advertising timeout (in seconds).
- */
- void setTimeout(uint16_t newTimeout) {
- _timeout = newTimeout;
- }
+ void setAdvertisingType(AdvertisingType_t newAdvType) {_advType = newAdvType; }
+ void setInterval(uint16_t newInterval) {_interval = MSEC_TO_ADVERTISEMENT_DURATION_UNITS(newInterval);}
+ void setTimeout(uint16_t newTimeout) {_timeout = newTimeout; }
private:
- AdvertisingType_t _advType; /**< The advertising type. */
- uint16_t _interval; /**< The advertising interval in ADV duration units (i.e. 0.625ms). */
- uint16_t _timeout; /**< The advertising timeout in seconds. */
+ AdvertisingType_t _advType;
+ uint16_t _interval; /* In ADV duration units (i.e. 0.625ms). */
+ uint16_t _timeout; /* In seconds. */
};
-#endif /* ifndef __GAP_ADVERTISING_PARAMS_H__ */
\ No newline at end of file
+#endif // ifndef __GAP_ADVERTISING_PARAMS_H__
\ No newline at end of file
--- a/ble/GapScanningParams.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GapScanningParams.h Wed Apr 06 19:15:30 2016 +0100
@@ -27,115 +27,31 @@
static const unsigned SCAN_TIMEOUT_MAX = 0xFFFF; /**< Maximum Scan timeout in seconds. */
public:
- /**
- * Construct an instance of GapScanningParams.
- *
- * @param[in] interval
- * The scan interval in milliseconds. Default is
- * GapScanningParams::SCAN_INTERVAL_MIN.
- * @param[in] window
- * The scan window in milliseconds. Default is
- * GapScanningParams::SCAN_WINDOW_MAX.
- * @param[in] timeout
- * The scan timeout in seconds. Default is 0.
- * @param[in] activeScanning
- * Set to True if active-scanning is required. This is used to
- * fetch the scan response from a peer if possible. Default is
- * false.
- */
GapScanningParams(uint16_t interval = SCAN_INTERVAL_MAX,
uint16_t window = SCAN_WINDOW_MAX,
uint16_t timeout = 0,
bool activeScanning = false);
static const uint16_t UNIT_0_625_MS = 625; /**< Number of microseconds in 0.625 milliseconds. */
- /**
- * Convert milliseconds to units of 0.625ms.
- *
- * @param[in] durationInMillis
- * The number of milliseconds to convert.
- *
- * @return The value of @p durationInMillis in units of 0.625ms.
- */
static uint16_t MSEC_TO_SCAN_DURATION_UNITS(uint32_t durationInMillis) {
return (durationInMillis * 1000) / UNIT_0_625_MS;
}
- /**
- * Set the scan interval.
- *
- * @param[in] newIntervalInMS
- * New scan interval in milliseconds.
- *
- * @return BLE_ERROR_NONE if the new scan interval was set successfully.
- */
ble_error_t setInterval(uint16_t newIntervalInMS);
- /**
- * Set the scan window.
- *
- * @param[in] newWindowInMS
- * New scan window in milliseconds.
- *
- * @return BLE_ERROR_NONE if the new scan window was set successfully.
- */
ble_error_t setWindow(uint16_t newWindowInMS);
- /**
- * Set the scan timeout.
- *
- * @param[in] newTimeout
- * New scan timeout in seconds.
- *
- * @return BLE_ERROR_NONE if the new scan window was set successfully.
- */
ble_error_t setTimeout(uint16_t newTimeout);
- /**
- * Set active scanning. This is used to fetch the scan response from a peer
- * if possible.
- *
- * @param[in] activeScanning
- * The new boolean value of active scanning.
- */
- void setActiveScanning(bool activeScanning);
+ void setActiveScanning(bool activeScanning);
public:
- /**
- * Get the scan interval.
- *
- * @return the scan interval in units of 0.625ms.
- */
- uint16_t getInterval(void) const {
- return _interval;
- }
-
- /**
- * Get the scan window.
- *
- * @return the scan window in units of 0.625ms.
- */
- uint16_t getWindow(void) const {
- return _window;
- }
+ /* @Note: The following return durations in units of 0.625ms */
+ uint16_t getInterval(void) const {return _interval;}
+ uint16_t getWindow(void) const {return _window; }
- /**
- * Get the scan timeout.
- *
- * @return The scan timeout in seconds.
- */
- uint16_t getTimeout(void) const {
- return _timeout;
- }
-
- /**
- * Check whether active scanning is set.
- *
- * @return True if active scanning is set, false otherwise.
- */
- bool getActiveScanning(void) const {
- return _activeScanning;
- }
+ uint16_t getTimeout(void) const {return _timeout; }
+ bool getActiveScanning(void) const {return _activeScanning;}
private:
uint16_t _interval; /**< Scan interval in units of 625us (between 2.5ms and 10.24s). */
@@ -149,4 +65,4 @@
GapScanningParams& operator =(const GapScanningParams &in);
};
-#endif /* ifndef __GAP_SCANNING_PARAMS_H__ */
\ No newline at end of file
+#endif // ifndef __GAP_SCANNING_PARAMS_H__
\ No newline at end of file
--- a/ble/GattAttribute.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GattAttribute.h Wed Apr 06 19:15:30 2016 +0100
@@ -19,20 +19,9 @@
#include "UUID.h"
-/**
- * Instances of this class encapsulate the data that belongs to a Bluetooth Low
- * Energy attribute.
- */
class GattAttribute {
public:
- /**
- * Type for the handle or ID of the attribute in the ATT table. These are
- * unique and are usually generated by the underlying BLE stack.
- */
typedef uint16_t Handle_t;
- /**
- * Define the value of an invalid attribute handle.
- */
static const Handle_t INVALID_HANDLE = 0x0000;
public:
@@ -66,103 +55,21 @@
}
public:
- /**
- * Get the attribute's handle in the ATT table.
- *
- * @return The attribute's handle.
- */
- Handle_t getHandle(void) const {
- return _handle;
- }
-
- /**
- * The UUID of the characteristic that this attribute belongs to.
- *
- * @return The characteristic's UUID.
- */
- const UUID &getUUID(void) const {
- return _uuid;
- }
-
- /**
- * Get the current length of the attribute value.
- *
- * @return The current length of the attribute value.
- */
- uint16_t getLength(void) const {
- return _len;
- }
-
- /**
- * Get the maximum length of the attribute value.
- *
- * The maximum length of the attribute value.
- */
- uint16_t getMaxLength(void) const {
- return _lenMax;
- }
-
- /**
- * Get a pointer to the current length of the attribute value.
- *
- * @return A pointer to the current length of the attribute value.
- */
- uint16_t *getLengthPtr(void) {
- return &_len;
- }
-
- /**
- * Set the attribute handle.
- *
- * @param[in] id
- * The new attribute handle.
- */
- void setHandle(Handle_t id) {
- _handle = id;
- }
-
- /**
- * Get a pointer to the attribute value.
- *
- * @return A pointer to the attribute value.
- */
- uint8_t *getValuePtr(void) {
- return _valuePtr;
- }
-
- /**
- * Check whether the length of the attribute's value can change over time.
- *
- * @return true if the attribute has variable length, false otherwise.
- */
- bool hasVariableLength(void) const {
- return _hasVariableLen;
- }
+ Handle_t getHandle(void) const {return _handle; }
+ const UUID &getUUID(void) const {return _uuid; }
+ uint16_t getLength(void) const {return _len; }
+ uint16_t getMaxLength(void) const {return _lenMax; }
+ uint16_t *getLengthPtr(void) {return &_len; }
+ void setHandle(Handle_t id) {_handle = id; }
+ uint8_t *getValuePtr(void) {return _valuePtr; }
+ bool hasVariableLength(void) const {return _hasVariableLen;}
private:
- /**
- * Characteristic's UUID.
- */
- UUID _uuid;
- /**
- * Pointer to the attribute's value.
- */
+ UUID _uuid; /* Characteristic UUID. */
uint8_t *_valuePtr;
- /**
- * Maximum length of the value pointed to by GattAttribute::_valuePtr.
- */
- uint16_t _lenMax;
- /**
- * Current length of the value pointed to by GattAttribute::_valuePtr.
- */
- uint16_t _len;
- /**
- * Whether the length of the value can change over time.
- */
+ uint16_t _lenMax; /* Maximum length of the value. */
+ uint16_t _len; /* Current length of the value. */
bool _hasVariableLen;
- /**
- * The attribute's handle in the ATT table.
- */
Handle_t _handle;
private:
@@ -171,4 +78,4 @@
GattAttribute& operator=(const GattAttribute &);
};
-#endif /* ifndef __GATT_ATTRIBUTE_H__ */
\ No newline at end of file
+#endif // ifndef __GATT_ATTRIBUTE_H__
\ No newline at end of file
--- a/ble/GattCallbackParamTypes.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GattCallbackParamTypes.h Wed Apr 06 19:15:30 2016 +0100
@@ -18,9 +18,6 @@
#define __GATT_CALLBACK_PARAM_TYPES_H__
struct GattWriteCallbackParams {
- /**
- * Enumeration for write operations.
- */
enum WriteOp_t {
OP_INVALID = 0x00, /**< Invalid operation. */
OP_WRITE_REQ = 0x01, /**< Write request. */
@@ -31,32 +28,20 @@
OP_EXEC_WRITE_REQ_NOW = 0x06, /**< Execute write request: immediately execute all prepared writes. */
};
- Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event */
- GattAttribute::Handle_t handle; /**< Attribute Handle to which the write operation applies. */
- WriteOp_t writeOp; /**< Type of write operation. */
- uint16_t offset; /**< Offset for the write operation. */
- uint16_t len; /**< Length (in bytes) of the data to write. */
- /**
- * Pointer to the data to write.
- *
- * @note Data might not persist beyond the callback; make a local copy if
- * needed.
- */
- const uint8_t *data;
+ Gap::Handle_t connHandle;
+ GattAttribute::Handle_t handle;
+ WriteOp_t writeOp; /**< Type of write operation. */
+ uint16_t offset; /**< Offset for the write operation. */
+ uint16_t len;
+ const uint8_t *data; /* @note: Data might not persist beyond the callback; make a local copy if needed. */
};
struct GattReadCallbackParams {
- Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event */
- GattAttribute::Handle_t handle; /**< Attribute Handle to which the read operation applies. */
- uint16_t offset; /**< Offset for the read operation. */
- uint16_t len; /**< Length (in bytes) of the data to read. */
- /**
- * Pointer to the data read.
- *
- * @note Data might not persist beyond the callback; make a local copy if
- * needed.
- */
- const uint8_t *data;
+ Gap::Handle_t connHandle;
+ GattAttribute::Handle_t handle;
+ uint16_t offset; /**< Offset for the read operation. */
+ uint16_t len;
+ const uint8_t *data; /* @note: Data might not persist beyond the callback; make a local copy if needed. */
};
enum GattAuthCallbackReply_t {
@@ -75,41 +60,34 @@
};
struct GattWriteAuthCallbackParams {
- Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event */
- GattAttribute::Handle_t handle; /**< Attribute Handle to which the write operation applies. */
- uint16_t offset; /**< Offset for the write operation. */
- uint16_t len; /**< Length of the incoming data. */
- const uint8_t *data; /**< Incoming data, variable length. */
- /**
- * This is the out parameter that the callback needs to set to
- * AUTH_CALLBACK_REPLY_SUCCESS for the request to proceed.
- */
- GattAuthCallbackReply_t authorizationReply;
+ Gap::Handle_t connHandle;
+ GattAttribute::Handle_t handle;
+ uint16_t offset; /**< Offset for the write operation. */
+ uint16_t len; /**< Length of the incoming data. */
+ const uint8_t *data; /**< Incoming data, variable length. */
+ GattAuthCallbackReply_t authorizationReply; /* This is the out parameter that the callback
+ * needs to set to AUTH_CALLBACK_REPLY_SUCCESS
+ * for the request to proceed. */
};
struct GattReadAuthCallbackParams {
- Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event */
- GattAttribute::Handle_t handle; /**< Attribute Handle to which the read operation applies. */
- uint16_t offset; /**< Offset for the read operation. */
- uint16_t len; /**< Optional: new length of the outgoing data. */
- uint8_t *data; /**< Optional: new outgoing data. Leave at NULL if data is unchanged. */
- /**
- * This is the out parameter that the callback needs to set to
- * AUTH_CALLBACK_REPLY_SUCCESS for the request to proceed.
- */
- GattAuthCallbackReply_t authorizationReply;
+ Gap::Handle_t connHandle;
+ GattAttribute::Handle_t handle;
+ uint16_t offset; /**< Offset for the read operation. */
+ uint16_t len; /**< Optional: new length of the outgoing data. */
+ uint8_t *data; /**< Optional: new outgoing data. Leave at NULL if data is unchanged. */
+ GattAuthCallbackReply_t authorizationReply; /* This is the out parameter that the callback
+ * needs to set to AUTH_CALLBACK_REPLY_SUCCESS
+ * for the request to proceed. */
};
-/**
- * For encapsulating handle-value update events (notifications or indications)
- * generated at the remote server.
- */
+/* For encapsulating handle-value update events (notifications or indications) generated at the remote server. */
struct GattHVXCallbackParams {
- Gap::Handle_t connHandle; /**< The handle of the connection that triggered the event */
- GattAttribute::Handle_t handle; /**< Attribute Handle to which the HVx operation applies. */
- HVXType_t type; /**< Indication or Notification, see HVXType_t. */
- uint16_t len; /**< Attribute data length. */
- const uint8_t *data; /**< Attribute data, variable length. */
+ Gap::Handle_t connHandle;
+ GattAttribute::Handle_t handle; /**< Attribute Handle to which the HVx operation applies. */
+ HVXType_t type; /**< Indication or Notification, see @ref HVXType_t. */
+ uint16_t len; /**< Attribute data length. */
+ const uint8_t *data; /**< Attribute data, variable length. */
};
#endif /*__GATT_CALLBACK_PARAM_TYPES_H__*/
\ No newline at end of file
--- a/ble/GattCharacteristic.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GattCharacteristic.h Wed Apr 06 19:15:30 2016 +0100
@@ -99,13 +99,15 @@
UUID_RSC_MEASUREMENT_CHAR = 0x2A53
};
- /**
- * @brief Standard GATT characteristic presentation format unit types.
- * These unit types are used to describe what the raw numeric
- * data in a characteristic actually represents.
- *
- * @note See https://developer.bluetooth.org/gatt/units/Pages/default.aspx
- */
+ /**************************************************************************/
+ /*!
+ \brief Standard GATT characteristic presentation format unit types.
+ These unit types are used to describe what the raw numeric
+ data in a characteristic actually represents.
+
+ \note See https://developer.bluetooth.org/gatt/units/Pages/default.aspx
+ */
+ /**************************************************************************/
enum {
BLE_GATT_UNIT_NONE = 0x2700, /**< No specified unit type. */
BLE_GATT_UNIT_LENGTH_METRE = 0x2701, /**< Length, metre. */
@@ -218,13 +220,14 @@
BLE_GATT_UNIT_IRRADIANCE_WATT_PER_SQUARE_METRE = 0x27B6 /**< */
};
- /**
- * @brief Standard GATT number types.
- *
- * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.2.
- *
- * @note See http://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml
- */
+ /**************************************************************************/
+ /*!
+ \brief Standard GATT number types.
+
+ \note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.2
+ \note See http://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml
+ */
+ /**************************************************************************/
enum {
BLE_GATT_FORMAT_RFU = 0x00, /**< Reserved for future use. */
BLE_GATT_FORMAT_BOOLEAN = 0x01, /**< Boolean. */
@@ -256,12 +259,14 @@
BLE_GATT_FORMAT_STRUCT = 0x1B /**< Opaque Structure. */
};
+ /**************************************************************************/
/*!
- * @brief Standard GATT characteristic properties.
- *
- * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.1.1
- * and Section 3.3.3.1 for Extended Properties.
- */
+ \brief Standard GATT characteristic properties.
+
+ \note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.1.1
+ and Section 3.3.3.1 for Extended Properties
+ */
+ /**************************************************************************/
enum Properties_t {
BLE_GATT_CHAR_PROPERTIES_NONE = 0x00,
BLE_GATT_CHAR_PROPERTIES_BROADCAST = 0x01, /**< Permits broadcasts of the characteristic value using the Server Characteristic Configuration descriptor. */
@@ -274,50 +279,51 @@
BLE_GATT_CHAR_PROPERTIES_EXTENDED_PROPERTIES = 0x80 /**< Additional characteristic properties are defined in the Characteristic Extended Properties descriptor */
};
- /**
- * @brief GATT presentation format wrapper.
- *
- * @note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5.
- *
- * @note See https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml
- */
+ /**************************************************************************/
+ /*!
+ \brief GATT presentation format wrapper
+
+ \note See Bluetooth Specification 4.0 (Vol. 3), Part G, Section 3.3.3.5
+ \note See https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml
+ */
+ /**************************************************************************/
struct PresentationFormat_t {
- uint8_t gatt_format; /**< Format of the value. */
+ uint8_t gatt_format; /**< Format of the value; see @ref ble_gatt_format_t. */
int8_t exponent; /**< Exponent for integer data types. Example: if Exponent = -3 and the char value is 3892, the actual value is 3.892 */
- uint16_t gatt_unit; /**< UUID from Bluetooth Assigned Numbers. */
- uint8_t gatt_namespace; /**< Namespace from Bluetooth Assigned Numbers, normally '1'. */
- uint16_t gatt_nsdesc; /**< Namespace description from Bluetooth Assigned Numbers, normally '0'. */
+ uint16_t gatt_unit; /**< UUID from Bluetooth Assigned Numbers; see @ref ble_gatt_unit_t. */
+ uint8_t gatt_namespace; /**< Namespace from Bluetooth Assigned Numbers, normally '1'; see @ref BLE_GATT_CPF_NAMESPACES. */
+ uint16_t gatt_nsdesc; /**< Namespace description from Bluetooth Assigned Numbers, normally '0'; see @ref BLE_GATT_CPF_NAMESPACES. */
};
/**
- * @brief Creates a new GattCharacteristic using the specified 16-bit
- * UUID, value length, and properties.
+ * @brief Creates a new GattCharacteristic using the specified 16-bit
+ * UUID, value length, and properties.
+ *
+ * @note The UUID value must be unique in the service and is normally >1.
*
- * @param[in] uuid
- * The UUID to use for this characteristic.
- * @param[in] valuePtr
- * The memory holding the initial value. The value is copied
- * into the stack when the enclosing service is added, and
- * is thereafter maintained internally by the stack.
- * @param[in] len
- * The length in bytes of this characteristic's value.
- * @param[in] maxLen
- * The max length in bytes of this characteristic's value.
- * @param[in] props
- * The 8-bit field containing the characteristic's properties.
- * @param[in] descriptors
- * A pointer to an array of descriptors to be included within
- * this characteristic. The memory for the descriptor array is
- * owned by the caller, and should remain valid at least until
- * the enclosing service is added to the GATT table.
- * @param[in] numDescriptors
- * The number of descriptors in the previous array.
- * @param[in] hasVariableLen
- * Whether the attribute's value length changes over time.
+ * @param[in] uuid
+ * The UUID to use for this characteristic.
+ * @param[in] valuePtr
+ * The memory holding the initial value. The value is copied
+ * into the stack when the enclosing service is added, and
+ * is thereafter maintained internally by the stack.
+ * @param[in] len
+ * The length in bytes of this characteristic's value.
+ * @param[in] maxLen
+ * The max length in bytes of this characteristic's value.
+ * @param[in] hasVariableLen
+ * Whether the attribute's value length changes over time.
+ * @param[in] props
+ * The 8-bit field containing the characteristic's properties.
+ * @param[in] descriptors
+ * A pointer to an array of descriptors to be included within
+ * this characteristic. The memory for the descriptor array is
+ * owned by the caller, and should remain valid at least until
+ * the enclosing service is added to the GATT table.
+ * @param[in] numDescriptors
+ * The number of descriptors in the previous array.
*
- * @note The UUID value must be unique in the service and is normally >1.
- *
- * @note If valuePtr == NULL, length == 0, and properties == READ
+ * @NOTE: If valuePtr == NULL, length == 0, and properties == READ
* for the value attribute of a characteristic, then that particular
* characteristic may be considered optional and dropped while
* instantiating the service with the underlying BLE stack.
@@ -344,12 +350,9 @@
public:
/**
- * Set up the minimum security (mode and level) requirements for access to
- * the characteristic's value attribute.
+ * Set up the minimum security (mode and level) requirements for access to the characteristic's value attribute.
*
- * @param[in] securityMode
- * Can be one of encryption or signing, with or without
- * protection for man in the middle attacks (MITM).
+ * @param securityMode Can be one of encryption or signing, with or without protection for man in the middle attacks (MITM).
*/
void requireSecurity(SecurityManager::SecurityMode_t securityMode) {
_requiredSecurity = securityMode;
@@ -357,61 +360,21 @@
public:
/**
- * Set up callback that will be triggered before the GATT Client is allowed
- * to write this characteristic. The handler will determine the
- * authorization reply for the write.
- *
- * @param[in] callback
- * Event handler being registered.
+ * Authorization.
*/
void setWriteAuthorizationCallback(void (*callback)(GattWriteAuthCallbackParams *)) {
writeAuthorizationCallback.attach(callback);
enabledWriteAuthorization = true;
}
-
- /**
- * Same as GattCharacrteristic::setWriteAuthorizationCallback(), but allows
- * the possibility to add an object reference and member function as
- * handler for connection event callbacks.
- *
- * @param[in] object
- * Pointer to the object of a class defining the member callback
- * function (@p member).
- * @param[in] member
- * The member callback (within the context of an object) to be
- * invoked.
- */
template <typename T>
void setWriteAuthorizationCallback(T *object, void (T::*member)(GattWriteAuthCallbackParams *)) {
writeAuthorizationCallback.attach(object, member);
enabledWriteAuthorization = true;
}
-
- /**
- * Set up callback that will be triggered before the GATT Client is allowed
- * to read this characteristic. The handler will determine the
- * authorizaion reply for the read.
- *
- * @param[in] callback
- * Event handler being registered.
- */
void setReadAuthorizationCallback(void (*callback)(GattReadAuthCallbackParams *)) {
readAuthorizationCallback.attach(callback);
enabledReadAuthorization = true;
}
-
- /**
- * Same as GattCharacrteristic::setReadAuthorizationCallback(), but allows
- * the possibility to add an object reference and member function as
- * handler for connection event callbacks.
- *
- * @param[in] object
- * Pointer to the object of a class defining the member callback
- * function (@p member).
- * @param[in] member
- * The member callback (within the context of an object) to be
- * invoked.
- */
template <typename T>
void setReadAuthorizationCallback(T *object, void (T::*member)(GattReadAuthCallbackParams *)) {
readAuthorizationCallback.attach(object, member);
@@ -419,16 +382,10 @@
}
/**
- * Helper that calls the registered handler to determine the authorization
- * reply for a write request. This function is meant to be called from the
- * BLE stack specific implementation.
- *
- * @param[in] params
- * To capture the context of the write-auth request. Also
- * contains an out-parameter for reply.
- *
- * @return A GattAuthCallbackReply_t value indicating whether authorization
- * is granted.
+ * Helper function meant to be called from the guts of the BLE stack to
+ * determine the authorization reply for a write request.
+ * @param params To capture the context of the write-auth request. Also contains an out-parameter for reply.
+ * @return true if the write is authorized to proceed.
*/
GattAuthCallbackReply_t authorizeWrite(GattWriteAuthCallbackParams *params) {
if (!isWriteAuthorizationEnabled()) {
@@ -441,24 +398,20 @@
}
/**
- * Helper that calls the registered handler to determine the authorization
- * reply for a read request. This function is meant to be called from the
- * BLE stack specific implementation.
+ * Helper function meant to be called from the guts of the BLE stack to
+ * determine the authorization reply for a read request.
+ * @param params To capture the context of the read-auth request.
*
- * @param[in] params
- * To capture the context of the read-auth request.
- *
- * @return A GattAuthCallbackReply_t value indicating whether authorization
- * is granted.
- *
- * @note To authorize or deny the read the params->authorizationReply field
+ * @NOTE: To authorize or deny the read the params->authorizationReply field
* should be set to true (authorize) or false (deny).
*
- * @note If the read is approved and params->data is unchanged (NULL),
+ * If the read is approved and params->data is unchanged (NULL),
* the current characteristic value will be used.
*
- * @note If the read is approved, a new value can be provided by setting
+ * If the read is approved, a new value can be provided by setting
* the params->data pointer and params->len fields.
+ *
+ * @return true if the read is authorized to proceed.
*/
GattAuthCallbackReply_t authorizeRead(GattReadAuthCallbackParams *params) {
if (!isReadAuthorizationEnabled()) {
@@ -470,96 +423,17 @@
return params->authorizationReply;
}
+ /* accessors */
public:
- /**
- * Get the characteristic's value attribute.
- *
- * @return A reference to the characteristic's value attribute.
- */
- GattAttribute& getValueAttribute() {
- return _valueAttribute;
- }
-
- /**
- * A const alternative to GattCharacteristic::getValueAttribute().
- *
- * @return A const reference to the characteristic's value attribute.
- */
- const GattAttribute& getValueAttribute() const {
- return _valueAttribute;
- }
-
- /**
- * Get the characteristic's value attribute handle in the ATT table.
- *
- * @return The value attribute handle.
- *
- * @note The attribute handle is typically assigned by the underlying BLE
- * stack.
- */
- GattAttribute::Handle_t getValueHandle(void) const {
- return getValueAttribute().getHandle();
- }
-
- /**
- * Get the characteristic's propertied. Refer to
- * GattCharacteristic::Properties_t.
- *
- * @return The characteristic's properties.
- */
- uint8_t getProperties(void) const {
- return _properties;
- }
+ GattAttribute& getValueAttribute() {return _valueAttribute; }
+ const GattAttribute& getValueAttribute() const {return _valueAttribute; }
+ GattAttribute::Handle_t getValueHandle(void) const {return getValueAttribute().getHandle();}
+ uint8_t getProperties(void) const {return _properties; }
+ SecurityManager::SecurityMode_t getRequiredSecurity() const {return _requiredSecurity; }
+ uint8_t getDescriptorCount(void) const {return _descriptorCount; }
+ bool isReadAuthorizationEnabled() const {return enabledReadAuthorization; }
+ bool isWriteAuthorizationEnabled() const {return enabledWriteAuthorization; }
- /**
- * Get the characteristic's required security.
- *
- * @return The characteristic's required security.
- */
- SecurityManager::SecurityMode_t getRequiredSecurity() const {
- return _requiredSecurity;
- }
-
- /**
- * Get the total number of descriptors within this characteristic.
- *
- * @return The total number of descriptors.
- */
- uint8_t getDescriptorCount(void) const {
- return _descriptorCount;
- }
-
- /**
- * Check whether read authorization is enabled i.e. check whether a
- * read authorization callback was previously registered. Refer to
- * GattCharacteristic::setReadAuthorizationCallback().
- *
- * @return true if read authorization is enabled, false otherwise.
- */
- bool isReadAuthorizationEnabled() const {
- return enabledReadAuthorization;
- }
-
- /**
- * Check whether write authorization is enabled i.e. check whether a
- * write authorization callback was previously registered. Refer to
- * GattCharacteristic::setReadAuthorizationCallback().
- *
- * @return true if write authorization is enabled, false otherwise.
- */
- bool isWriteAuthorizationEnabled() const {
- return enabledWriteAuthorization;
- }
-
- /**
- * Get this characteristic's descriptor at a specific index.
- *
- * @param[in] index
- * The descriptor's index.
- *
- * @return A pointer the requested descriptor if @p index contains a valid
- * descriptor, or NULL otherwise.
- */
GattAttribute *getDescriptor(uint8_t index) {
if (index >= _descriptorCount) {
return NULL;
@@ -569,45 +443,15 @@
}
private:
- /**
- * Attribute that contains the actual value of this characteristic.
- */
GattAttribute _valueAttribute;
- /**
- * The characteristic's properties. Refer to
- * GattCharacteristic::Properties_t.
- */
uint8_t _properties;
- /**
- * The characteristic's required security.
- */
SecurityManager::SecurityMode_t _requiredSecurity;
- /**
- * The characteristic's descriptor attributes.
- */
GattAttribute **_descriptors;
- /**
- * The number of descriptors in this characteristic.
- */
uint8_t _descriptorCount;
- /**
- * Whether read authorization is enabled i.e. whether there is a registered
- * callback to determine read authorization reply.
- */
bool enabledReadAuthorization;
- /**
- * Whether write authorization is enabled i.e. whether there is a registered
- * callback to determine write authorization reply.
- */
bool enabledWriteAuthorization;
- /**
- * The registered callback handler for read authorization reply.
- */
FunctionPointerWithContext<GattReadAuthCallbackParams *> readAuthorizationCallback;
- /**
- * The registered callback handler for write authorization reply.
- */
FunctionPointerWithContext<GattWriteAuthCallbackParams *> writeAuthorizationCallback;
private:
@@ -616,33 +460,9 @@
GattCharacteristic& operator=(const GattCharacteristic &);
};
-/**
- * Helper class to construct a read-only GattCharacteristic.
- */
template <typename T>
class ReadOnlyGattCharacteristic : public GattCharacteristic {
public:
- /**
- * Construct a ReadOnlyGattCharacteristic.
- *
- * @param[in] uuid
- * The characteristic's UUID.
- * @param[in] valuePtr
- * Pointer to the characterisitic's initial value.
- * @param[in] additionalProperties
- * Additional characterisitic properties. By default, the
- * properties are set to
- * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
- * @param[in] descriptors
- * An array of pointers to descriptors to be added to the new
- * characteristic.
- * @param[in] numDescriptors
- * The total number of descriptors in @p descriptors.
- *
- * @note Instances of ReadOnlyGattCharacteristic have a fixed length
- * attribute value that equals sizeof(T). For a variable length
- * alternative use GattCharacteristic directly.
- */
ReadOnlyGattCharacteristic<T>(const UUID &uuid,
T *valuePtr,
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
@@ -654,33 +474,9 @@
}
};
-/**
- * Helper class to construct a write-only GattCharacteristic.
- */
template <typename T>
class WriteOnlyGattCharacteristic : public GattCharacteristic {
public:
- /**
- * Construct a WriteOnlyGattCharacteristic.
- *
- * @param[in] uuid
- * The characteristic's UUID.
- * @param[in] valuePtr
- * Pointer to the characterisitic's initial value.
- * @param[in] additionalProperties
- * Additional characterisitic properties. By default, the
- * properties are set to
- * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
- * @param[in] descriptors
- * An array of pointers to descriptors to be added to the new
- * characteristic.
- * @param[in] numDescriptors
- * The total number of descriptors in @p descriptors.
- *
- * @note Instances of WriteOnlyGattCharacteristic have variable length
- * attribute value with maximum size equal to sizeof(T). For a fixed length
- * alternative use GattCharacteristic directly.
- */
WriteOnlyGattCharacteristic<T>(const UUID &uuid,
T *valuePtr,
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
@@ -692,34 +488,9 @@
}
};
-/**
- * Helper class to construct a readable and writable GattCharacteristic.
- */
template <typename T>
class ReadWriteGattCharacteristic : public GattCharacteristic {
public:
- /**
- * Construct a ReadWriteGattCharacteristic.
- *
- * @param[in] uuid
- * The characteristic's UUID.
- * @param[in] valuePtr
- * Pointer to the characterisitic's initial value.
- * @param[in] additionalProperties
- * Additional characterisitic properties. By default, the
- * properties are set to
- * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE |
- * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
- * @param[in] descriptors
- * An array of pointers to descriptors to be added to the new
- * characteristic.
- * @param[in] numDescriptors
- * The total number of descriptors in @p descriptors.
- *
- * @note Instances of ReadWriteGattCharacteristic have variable length
- * attribute value with maximum size equal to sizeof(T). For a fixed length
- * alternative use GattCharacteristic directly.
- */
ReadWriteGattCharacteristic<T>(const UUID &uuid,
T *valuePtr,
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
@@ -731,35 +502,9 @@
}
};
-/**
- * Helper class to construct a write-only GattCharacteristic with an array
- * value.
- */
template <typename T, unsigned NUM_ELEMENTS>
class WriteOnlyArrayGattCharacteristic : public GattCharacteristic {
public:
- /**
- * Construct a WriteOnlyGattCharacteristic.
- *
- * @param[in] uuid
- * The characteristic's UUID.
- * @param[in] valuePtr
- * Pointer to an array of length NUM_ELEMENTS containing the
- * characteristic's intitial value.
- * @param[in] additionalProperties
- * Additional characterisitic properties. By default, the
- * properties are set to
- * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
- * @param[in] descriptors
- * An array of pointers to descriptors to be added to the new
- * characteristic.
- * @param[in] numDescriptors
- * The total number of descriptors in @p descriptors.
- *
- * @note Instances of WriteOnlyGattCharacteristic have variable length
- * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS.
- * For a fixed length alternative use GattCharacteristic directly.
- */
WriteOnlyArrayGattCharacteristic<T, NUM_ELEMENTS>(const UUID &uuid,
T valuePtr[NUM_ELEMENTS],
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
@@ -771,35 +516,9 @@
}
};
-/**
- * Helper class to construct a read-only GattCharacteristic with an array
- * value.
- */
template <typename T, unsigned NUM_ELEMENTS>
class ReadOnlyArrayGattCharacteristic : public GattCharacteristic {
public:
- /**
- * Construct a ReadOnlyGattCharacteristic.
- *
- * @param[in] uuid
- * The characteristic's UUID.
- * @param[in] valuePtr
- * Pointer to an array of length NUM_ELEMENTS containing the
- * characteristic's intitial value.
- * @param[in] additionalProperties
- * Additional characterisitic properties. By default, the
- * properties are set to
- * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
- * @param[in] descriptors
- * An array of pointers to descriptors to be added to the new
- * characteristic.
- * @param[in] numDescriptors
- * The total number of descriptors in @p descriptors.
- *
- * @note Instances of ReadOnlyGattCharacteristic have fixed length
- * attribute value that equals sizeof(T) * NUM_ELEMENTS.
- * For a variable length alternative use GattCharacteristic directly.
- */
ReadOnlyArrayGattCharacteristic<T, NUM_ELEMENTS>(const UUID &uuid,
T valuePtr[NUM_ELEMENTS],
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
@@ -811,36 +530,9 @@
}
};
-/**
- * Helper class to construct a readable and writable GattCharacteristic with an array
- * value.
- */
template <typename T, unsigned NUM_ELEMENTS>
class ReadWriteArrayGattCharacteristic : public GattCharacteristic {
public:
- /**
- * Construct a ReadWriteGattCharacteristic.
- *
- * @param[in] uuid
- * The characteristic's UUID.
- * @param[in] valuePtr
- * Pointer to an array of length NUM_ELEMENTS containing the
- * characteristic's intitial value.
- * @param[in] additionalProperties
- * Additional characterisitic properties. By default, the
- * properties are set to
- * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE |
- * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
- * @param[in] descriptors
- * An array of pointers to descriptors to be added to the new
- * characteristic.
- * @param[in] numDescriptors
- * The total number of descriptors in @p descriptors.
- *
- * @note Instances of ReadWriteGattCharacteristic have variable length
- * attribute value with maximum size equal to sizeof(T) * NUM_ELEMENTS.
- * For a fixed length alternative use GattCharacteristic directly.
- */
ReadWriteArrayGattCharacteristic<T, NUM_ELEMENTS>(const UUID &uuid,
T valuePtr[NUM_ELEMENTS],
uint8_t additionalProperties = BLE_GATT_CHAR_PROPERTIES_NONE,
@@ -852,4 +544,4 @@
}
};
-#endif /* ifndef __GATT_CHARACTERISTIC_H__ */
\ No newline at end of file
+#endif // ifndef __GATT_CHARACTERISTIC_H__
\ No newline at end of file
--- a/ble/GattClient.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GattClient.h Wed Apr 06 19:15:30 2016 +0100
@@ -28,52 +28,21 @@
class GattClient {
public:
- /**
- * Type for the registered callbacks added to the data read callchain.
- * Refer to GattClient::onDataRead().
- */
typedef FunctionPointerWithContext<const GattReadCallbackParams*> ReadCallback_t;
- /**
- * Type for the data read event callchain. Refer to GattClient::onDataRead().
- */
typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams*> ReadCallbackChain_t;
- /**
- * Enumerator for write operations.
- */
enum WriteOp_t {
GATT_OP_WRITE_REQ = 0x01, /**< Write request. */
GATT_OP_WRITE_CMD = 0x02, /**< Write command. */
};
- /**
- * Type for the registered callbacks added to the data write callchain.
- * Refer to GattClient::onDataWrite().
- */
typedef FunctionPointerWithContext<const GattWriteCallbackParams*> WriteCallback_t;
- /**
- * Type for the data write event callchain. Refer to GattClient::onDataWrite().
- */
typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> WriteCallbackChain_t;
- /**
- * Type for the registered callbacks added to the update event callchain.
- * Refer to GattClient::onHVX().
- */
typedef FunctionPointerWithContext<const GattHVXCallbackParams*> HVXCallback_t;
- /**
- * Type for the update event callchain. Refer to GattClient::onHVX().
- */
typedef CallChainOfFunctionPointersWithContext<const GattHVXCallbackParams*> HVXCallbackChain_t;
- /**
- * Type for the registered callbacks added to the shutdown callchain.
- * Refer to GattClient::onShutdown().
- */
typedef FunctionPointerWithContext<const GattClient *> GattClientShutdownCallback_t;
- /**
- * Type for the shutdown event callchain. Refer to GattClient::onShutown().
- */
typedef CallChainOfFunctionPointersWithContext<const GattClient *> GattClientShutdownCallbackChain_t;
/*
@@ -87,40 +56,40 @@
* will be invoked at the end. Service discovery can be terminated prematurely,
* if needed, using terminateServiceDiscovery().
*
- * @param[in] connectionHandle
- * Handle for the connection with the peer.
- * @param[in] sc
- * This is the application callback for a matching service. Taken as
- * NULL by default. Note: service discovery may still be active
- * when this callback is issued; calling asynchronous BLE-stack
- * APIs from within this application callback might cause the
- * stack to abort service discovery. If this becomes an issue, it
- * may be better to make a local copy of the discoveredService and
- * wait for service discovery to terminate before operating on the
- * service.
- * @param[in] cc
- * This is the application callback for a matching characteristic.
- * Taken as NULL by default. Note: service discovery may still be
- * active when this callback is issued; calling asynchronous
- * BLE-stack APIs from within this application callback might cause
- * the stack to abort service discovery. If this becomes an issue,
- * it may be better to make a local copy of the discoveredCharacteristic
- * and wait for service discovery to terminate before operating on the
- * characteristic.
- * @param[in] matchingServiceUUID
- * UUID-based filter for specifying a service in which the application is
- * interested. By default it is set as the wildcard UUID_UNKNOWN,
- * in which case it matches all services. If characteristic-UUID
- * filter (below) is set to the wildcard value, then a service
- * callback will be invoked for the matching service (or for every
- * service if the service filter is a wildcard).
- * @param[in] matchingCharacteristicUUIDIn
- * UUID-based filter for specifying characteristic in which the application
- * is interested. By default it is set as the wildcard UUID_UKNOWN
- * to match against any characteristic. If both service-UUID
- * filter and characteristic-UUID filter are used with non-wildcard
- * values, then only a single characteristic callback is
- * invoked for the matching characteristic.
+ * @param connectionHandle
+ * Handle for the connection with the peer.
+ * @param sc
+ * This is the application callback for a matching service. Taken as
+ * NULL by default. Note: service discovery may still be active
+ * when this callback is issued; calling asynchronous BLE-stack
+ * APIs from within this application callback might cause the
+ * stack to abort service discovery. If this becomes an issue, it
+ * may be better to make a local copy of the discoveredService and
+ * wait for service discovery to terminate before operating on the
+ * service.
+ * @param cc
+ * This is the application callback for a matching characteristic.
+ * Taken as NULL by default. Note: service discovery may still be
+ * active when this callback is issued; calling asynchronous
+ * BLE-stack APIs from within this application callback might cause
+ * the stack to abort service discovery. If this becomes an issue,
+ * it may be better to make a local copy of the discoveredCharacteristic
+ * and wait for service discovery to terminate before operating on the
+ * characteristic.
+ * @param matchingServiceUUID
+ * UUID-based filter for specifying a service in which the application is
+ * interested. By default it is set as the wildcard UUID_UNKNOWN,
+ * in which case it matches all services. If characteristic-UUID
+ * filter (below) is set to the wildcard value, then a service
+ * callback will be invoked for the matching service (or for every
+ * service if the service filter is a wildcard).
+ * @param matchingCharacteristicUUIDIn
+ * UUID-based filter for specifying characteristic in which the application
+ * is interested. By default it is set as the wildcard UUID_UKNOWN
+ * to match against any characteristic. If both service-UUID
+ * filter and characteristic-UUID filter are used with non-wildcard
+ * values, then only a single characteristic callback is
+ * invoked for the matching characteristic.
*
* @note Using wildcard values for both service-UUID and characteristic-
* UUID will result in complete service discovery: callbacks being
@@ -157,21 +126,20 @@
* at the end. Service discovery can be terminated prematurely, if needed,
* using terminateServiceDiscovery().
*
- * @param[in] connectionHandle
- * Handle for the connection with the peer.
- * @param[in] callback
- * This is the application callback for a matching service.
- * Note: service discovery may still be active
- * when this callback is issued; calling asynchronous BLE-stack
- * APIs from within this application callback might cause the
- * stack to abort service discovery. If this becomes an issue, it
- * may be better to make a local copy of the discoveredService and
- * wait for service discovery to terminate before operating on the
- * service.
- * @param[in] matchingServiceUUID
- * UUID-based filter for specifying a service in which the application is
- * interested. By default it is set as the wildcard UUID_UNKNOWN,
- * in which case it matches all services.
+ * @param connectionHandle
+ * Handle for the connection with the peer.
+ * @param sc
+ * This is the application callback for a matching service. Note: service discovery may still be active
+ * when this callback is issued; calling asynchronous BLE-stack
+ * APIs from within this application callback might cause the
+ * stack to abort service discovery. If this becomes an issue, it
+ * may be better to make a local copy of the discoveredService and
+ * wait for service discovery to terminate before operating on the
+ * service.
+ * @param matchingServiceUUID
+ * UUID-based filter for specifying a service in which the application is
+ * interested. By default it is set as the wildcard UUID_UNKNOWN,
+ * in which case it matches all services.
*
* @return
* BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
@@ -194,19 +162,18 @@
* at the end. Service discovery can be terminated prematurely, if needed,
* using terminateServiceDiscovery().
*
- * @param[in] connectionHandle
- * Handle for the connection with the peer.
- * @param[in] callback
- * This is the application callback for a matching service.
- * Note: service discovery may still be active
- * when this callback is issued; calling asynchronous BLE-stack
- * APIs from within this application callback might cause the
- * stack to abort service discovery. If this becomes an issue, it
- * may be better to make a local copy of the discoveredService and
- * wait for service discovery to terminate before operating on the
- * service.
- * @param[in] startHandle, endHandle
- * Handle range within which to limit the search.
+ * @param connectionHandle
+ * Handle for the connection with the peer.
+ * @param sc
+ * This is the application callback for a matching service. Note: service discovery may still be active
+ * when this callback is issued; calling asynchronous BLE-stack
+ * APIs from within this application callback might cause the
+ * stack to abort service discovery. If this becomes an issue, it
+ * may be better to make a local copy of the discoveredService and
+ * wait for service discovery to terminate before operating on the
+ * service.
+ * @param startHandle, endHandle
+ * Handle range within which to limit the search.
*
* @return
* BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
@@ -225,9 +192,7 @@
}
/**
- * Check if service-discovery is currently active.
- *
- * @return true if service-discovery is active, false otherwise.
+ * Is service-discovery currently active?
*/
virtual bool isServiceDiscoveryActive(void) const {
return false; /* Requesting action from porters: override this API if this capability is supported. */
@@ -241,19 +206,7 @@
/* Requesting action from porters: override this API if this capability is supported. */
}
- /**
- * Initiate a GATT Client read procedure by attribute-handle.
- *
- * @param[in] connHandle
- * Handle for the connection with the peer.
- * @param[in] attributeHandle
- * Handle of the attribute to read data from.
- * @param[in] offset
- * The offset from the start of the attribute value to be read.
- *
- * @return
- * BLE_ERROR_NONE if read procedure was successfully started.
- */
+ /* Initiate a GATT Client read procedure by attribute-handle. */
virtual ble_error_t read(Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const {
/* Avoid compiler warnings about unused variables. */
(void)connHandle;
@@ -278,9 +231,6 @@
* Length of the new value.
* @param[in] value
* New value being written.
- *
- * @return
- * BLE_ERROR_NONE if write procedure was successfully started.
*/
virtual ble_error_t write(GattClient::WriteOp_t cmd,
Gap::Handle_t connHandle,
@@ -301,28 +251,18 @@
public:
/**
* Set up a callback for read response events.
- *
- * @param[in] callback
- * Event handler being registered.
- *
- * @note It is possible to chain together multiple onDataRead callbacks
- * (potentially from different modules of an application).
- *
- * @note It is possible to unregister a callback using
- * onDataRead().detach(callbackToRemove).
+ * It is possible to remove registered callbacks using
+ * onDataRead().detach(callbackToRemove)
*/
void onDataRead(ReadCallback_t callback) {
onDataReadCallbackChain.add(callback);
}
/**
- * @brief Provide access to the callchain of read event callbacks.
- *
- * @return A reference to the read event callback chain.
- *
- * @note It is possible to register callbacks using onDataRead().add(callback).
- *
- * @note It is possible to unregister callbacks using onDataRead().detach(callback).
+ * @brief provide access to the callchain of read callbacks
+ * It is possible to register callbacks using onDataRead().add(callback);
+ * It is possible to unregister callbacks using onDataRead().detach(callback)
+ * @return The read callbacks chain
*/
ReadCallbackChain_t& onDataRead() {
return onDataReadCallbackChain;
@@ -330,27 +270,19 @@
/**
* Set up a callback for write response events.
- *
- * @param[in] callback
- * Event handler being registered.
- *
- * @note It is possible to remove registered callbacks using
+ * It is possible to remove registered callbacks using
* onDataWritten().detach(callbackToRemove).
- *
- * @note Write commands (issued using writeWoResponse) don't generate a response.
+ * @Note: Write commands (issued using writeWoResponse) don't generate a response.
*/
void onDataWritten(WriteCallback_t callback) {
onDataWriteCallbackChain.add(callback);
}
/**
- * @brief Provide access to the callchain of data written callbacks.
- *
- * @return A reference to the data written callbacks chain.
- *
- * @note It is possible to register callbacks using onDataWritten().add(callback).
- *
- * @note It is possible to unregister callbacks using onDataWritten().detach(callback).
+ * @brief provide access to the callchain of data written callbacks
+ * It is possible to register callbacks using onDataWritten().add(callback);
+ * It is possible to unregister callbacks using onDataWritten().detach(callback)
+ * @return The data written callbacks chain
*/
WriteCallbackChain_t& onDataWritten() {
return onDataWriteCallbackChain;
@@ -358,13 +290,10 @@
/**
* Set up a callback for write response events.
- *
- * @param[in] callback
- * Event handler being registered.
+ * @Note: Write commands (issued using writeWoResponse) don't generate a response.
*
- * @note Write commands (issued using writeWoResponse) don't generate a response.
- *
- * @deprecated Please use GattServer::onDataWritten() instead.
+ * @note: This API is now *deprecated* and will be dropped in the future.
+ * Please use onDataWritten() instead.
*/
void onDataWrite(WriteCallback_t callback) {
onDataWritten(callback);
@@ -372,9 +301,6 @@
/**
* Set up a callback for when serviceDiscovery terminates.
- *
- * @param[in] callback
- * Event handler being registered.
*/
virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) {
(void)callback; /* Avoid compiler warnings about ununsed variables. */
@@ -383,21 +309,18 @@
}
/**
- * @brief Launch discovery of descriptors for a given characteristic.
- *
+ * @brief launch discovery of descriptors for a given characteristic
* @details This function will discover all descriptors available for a
- * specific characteristic.
+ * specific characteristic.
*
- * @param[in] characteristic
- * The characteristic targeted by this discovery procedure.
- * @param[in] discoveryCallback
- * User function called each time a descriptor is found during
- * the procedure.
- * @param[in] terminationCallback
- * User provided function which will be called once the
- * discovery procedure is terminating. This will get called
- * when all the descriptors have been discovered or if an
- * error occur during the discovery procedure.
+ * @param characteristic[in] The characteristic targeted by this discovery
+ * procedure
+ * @param discoveryCallback[in] User function called each time a descriptor
+ * is found during the procedure.
+ * @param terminationCallback[in] User provided function which will be called
+ * once the discovery procedure is terminating. This will get called when all
+ * the descriptors have been discovered or if an error occur during the discovery
+ * procedure.
*
* @return
* BLE_ERROR_NONE if characteristic descriptor discovery is launched
@@ -415,14 +338,10 @@
}
/**
- * @brief Indicate if the discovery of characteristic descriptors is active
- * for a given characteristic or not.
- *
- * @param[in] characteristic
- * The characteristic concerned by the descriptors discovery.
- *
- * @return true if a descriptors discovery is active for the characteristic
- * in input; otherwise false.
+ * @brief Indicate if the discovery of characteristic descriptors is active for a given characteristic
+ * or not.
+ * @param characteristic[in] The characteristic concerned by the descriptors discovery.
+ * @return true if a descriptors discovery is active for the characteristic in input; otherwise false.
*/
virtual bool isCharacteristicDescriptorDiscoveryActive(const DiscoveredCharacteristic& characteristic) const
{
@@ -432,13 +351,10 @@
/**
* @brief Terminate an ongoing characteristic descriptor discovery.
- *
- * @details This should result in an invocation of the TerminationCallback if
- * the characteristic descriptor discovery is active.
- *
- * @param[in] characteristic
- * The characteristic on which the running descriptors
- * discovery should be stopped.
+ * @detail This should result in an invocation of the TerminationCallback if
+ * the characteristic descriptor discovery is active.
+ * @param characteristic[in] The characteristic on which the running descriptors
+ * discovery should be stopped.
*/
virtual void terminateCharacteristicDescriptorDiscovery(const DiscoveredCharacteristic& characteristic) {
/* Requesting action from porter(s): override this API if this capability is supported. */
@@ -446,12 +362,10 @@
}
/**
- * Set up a callback for when the GATT Client receives an update event
+ * Set up a callback for when the GATT client receives an update event
* corresponding to a change in the value of a characteristic on the remote
- * GATT Server.
- *
- * @note It is possible to unregister callbacks using
- * onHVX().detach(callbackToRemove).
+ * GATT server.
+ * It is possible to remove registered callbacks using onHVX().detach(callbackToRemove).
*/
void onHVX(HVXCallback_t callback) {
onHVXCallbackChain.add(callback);
@@ -462,60 +376,38 @@
* GattClient instance is about to shutdown (possibly as a result of a call
* to BLE::shutdown()).
*
- * @param[in] callback
- * Event handler being registered.
+ * @Note: It is possible to chain together multiple onShutdown callbacks
+ * (potentially from different modules of an application) to be notified
+ * before the GattClient is shutdown.
*
- * @note It is possible to chain together multiple onShutdown callbacks
- * (potentially from different modules of an application) to be notified
- * before the GattClient is shutdown.
+ * @Note: It is also possible to set up a callback into a member function of
+ * some object.
*
- * @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 GattClientShutdownCallback_t& callback) {
shutdownCallChain.add(callback);
}
-
- /**
- * Same as GattClient::onShutdown(), but allows the possibility to add an object
- * reference and member function as handler for shutdown event
- * callbacks.
- *
- * @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.
- */
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.
- *
- * @return A reference to the shutdown event callbacks chain.
- *
- * @note It is possible to register callbacks using onShutdown().add(callback).
- *
- * @note It is possible to unregister callbacks using onShutdown().detach(callback).
+ * @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
*/
GattClientShutdownCallbackChain_t& onShutdown() {
return shutdownCallChain;
}
/**
- * @brief provide access to the callchain of HVX callbacks.
- *
- * @return A reference to the HVX callbacks chain.
- *
- * @note It is possible to register callbacks using onHVX().add(callback).
- *
- * @note It is possible to unregister callbacks using onHVX().detach(callback).
+ * @brief provide access to the callchain of HVX callbacks
+ * It is possible to register callbacks using onHVX().add(callback);
+ * It is possible to unregister callbacks using onHVX().detach(callback)
+ * @return The HVX callbacks chain
*/
HVXCallbackChain_t& onHVX() {
return onHVXCallbackChain;
@@ -554,41 +446,14 @@
/* 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 data read event. This function is meant to be called from the
- * BLE stack specific implementation when a data read event occurs.
- *
- * @param[in] params
- * The data read parameters passed to the registered
- * handlers.
- */
void processReadResponse(const GattReadCallbackParams *params) {
onDataReadCallbackChain(params);
}
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of a data written event. This function is meant to be called from the
- * BLE stack specific implementation when a data written event occurs.
- *
- * @param[in] params
- * The data written parameters passed to the registered
- * handlers.
- */
void processWriteResponse(const GattWriteCallbackParams *params) {
onDataWriteCallbackChain(params);
}
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of an update event. This function is meant to be called from the
- * BLE stack specific implementation when an update event occurs.
- *
- * @param[in] params
- * The update event parameters passed to the registered
- * handlers.
- */
void processHVXEvent(const GattHVXCallbackParams *params) {
if (onHVXCallbackChain) {
onHVXCallbackChain(params);
@@ -596,25 +461,9 @@
}
protected:
- /**
- * Callchain containing all registered callback handlers for data read
- * events.
- */
ReadCallbackChain_t onDataReadCallbackChain;
- /**
- * Callchain containing all registered callback handlers for data write
- * events.
- */
WriteCallbackChain_t onDataWriteCallbackChain;
- /**
- * Callchain containing all registered callback handlers for update
- * events.
- */
HVXCallbackChain_t onHVXCallbackChain;
- /**
- * Callchain containing all registered callback handlers for shutdown
- * events.
- */
GattClientShutdownCallbackChain_t shutdownCallChain;
private:
@@ -623,4 +472,4 @@
GattClient& operator=(const GattClient &);
};
-#endif /* ifndef __GATT_CLIENT_H__ */
\ No newline at end of file
+#endif // ifndef __GATT_CLIENT_H__
\ No newline at end of file
--- a/ble/GattServer.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GattServer.h Wed Apr 06 19:15:30 2016 +0100
@@ -26,57 +26,22 @@
class GattServer {
public:
- /**
- * Type for the registered callbacks added to the data sent callchain.
- * Refer to GattServer::onDataSent().
- */
+ /* Event callback handlers. */
typedef FunctionPointerWithContext<unsigned> DataSentCallback_t;
- /**
- * Type for the data sent event callchain. Refer to GattServer::onDataSent().
- */
typedef CallChainOfFunctionPointersWithContext<unsigned> DataSentCallbackChain_t;
- /**
- * Type for the registered callbacks added to the data written callchain.
- * Refer to GattServer::onDataWritten().
- */
typedef FunctionPointerWithContext<const GattWriteCallbackParams*> DataWrittenCallback_t;
- /**
- * Type for the data written event callchain. Refer to GattServer::onDataWritten().
- */
typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> DataWrittenCallbackChain_t;
- /**
- * Type for the registered callbacks added to the data read callchain.
- * Refer to GattServer::onDataRead().
- */
typedef FunctionPointerWithContext<const GattReadCallbackParams*> DataReadCallback_t;
- /**
- * Type for the data read event callchain. Refer to GattServer::onDataRead().
- */
typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *> DataReadCallbackChain_t;
- /**
- * Type for the registered callbacks added to the shutdown callchain.
- * Refer to GattServer::onShutdown().
- */
typedef FunctionPointerWithContext<const GattServer *> GattServerShutdownCallback_t;
- /**
- * Type for the shutdown event callchain. Refer to GattServer::onShutdown().
- */
typedef CallChainOfFunctionPointersWithContext<const GattServer *> GattServerShutdownCallbackChain_t;
- /**
- * Type for the registered callback for various events. Refer to
- * GattServer::onUpdatesEnabled(), GattServer::onUpdateDisabled() and
- * GattServer::onConfirmationReceived().
- */
typedef FunctionPointerWithContext<GattAttribute::Handle_t> EventCallback_t;
protected:
- /**
- * Construct a GattServer instance.
- */
GattServer() :
serviceCount(0),
characteristicCount(0),
@@ -97,11 +62,6 @@
/**
* Add a service declaration to the local server ATT table. Also add the
* characteristics contained within.
- *
- * @param[in] service
- * The service to be added.
- *
- * @return BLE_ERROR_NONE if the service was successfully added.
*/
virtual ble_error_t addService(GattService &service) {
/* Avoid compiler warnings about unused variables. */
@@ -112,12 +72,11 @@
/**
* Read the value of a characteristic from the local GATT server.
- *
* @param[in] attributeHandle
* 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 hold upon return the total attribute value length
@@ -137,14 +96,13 @@
/**
* Read the value of a characteristic from the local GATT server.
- *
* @param[in] connectionHandle
* Connection handle.
* @param[in] attributeHandle
* 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 hold upon return the total attribute value length
@@ -231,7 +189,7 @@
/**
* Determine the updates-enabled status (notification or indication) for the current connection from a characteristic's CCCD.
*
- * @param[in] characteristic
+ * @param characteristic
* The characteristic.
* @param[out] enabledP
* Upon return, *enabledP is true if updates are enabled, else false.
@@ -249,13 +207,14 @@
/**
* Determine the connection-specific updates-enabled status (notification or indication) from a characteristic's CCCD.
*
- * @param[in] connectionHandle
+ * @param connectionHandle
* The connection handle.
- * @param[in] characteristic
- * The characteristic.
* @param[out] enabledP
* Upon return, *enabledP is true if updates are enabled, else false.
*
+ * @param characteristic
+ * The characteristic.
+ *
* @return BLE_ERROR_NONE if the connection and handle are found. False otherwise.
*/
virtual ble_error_t areUpdatesEnabled(Gap::Handle_t connectionHandle, const GattCharacteristic &characteristic, bool *enabledP) {
@@ -270,8 +229,6 @@
/**
* A virtual function to allow underlying stacks to indicate if they support
* onDataRead(). It should be overridden to return true as applicable.
- *
- * @return true if onDataRead is supported, false otherwise.
*/
virtual bool isOnDataReadAvailable() const {
return false; /* Requesting action from porters: override this API if this capability is supported. */
@@ -285,41 +242,21 @@
* Add a callback for the GATT event DATA_SENT (which is triggered when
* updates are sent out by GATT in the form of notifications).
*
- * @param[in] callback
- * Event handler being registered.
+ * @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 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
- * some object.
+ * @Note: It is also possible to set up a callback into a member function of
+ * some object.
*/
- void onDataSent(const DataSentCallback_t& callback) {
- dataSentCallChain.add(callback);
- }
-
- /**
- * Same as GattServer::onDataSent(), but allows the possibility to add an object
- * reference and member function as handler for DATA_SENT event
- * callbacks.
- *
- * @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.
- */
+ void onDataSent(const DataSentCallback_t& callback) {dataSentCallChain.add(callback);}
template <typename T>
void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count)) {
dataSentCallChain.add(objPtr, memberPtr);
}
/**
- * @brief Provide access to the callchain of DATA_SENT event callbacks.
- *
- * @return A reference to the DATA_SENT event callback chain.
+ * @brief get the callback chain called when the event DATA_EVENT is triggered.
*/
DataSentCallbackChain_t& onDataSent() {
return dataSentCallChain;
@@ -332,48 +269,27 @@
* For a central, this callback is triggered when a response is received for
* a write request.
*
- * @param[in] callback
- * Event handler being registered.
- *
- * @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 It is possible to unregister a callback using onDataWritten().detach(callback)
+ * @Note It is possible to unregister a callback using onDataWritten().detach(callback)
*/
- void onDataWritten(const DataWrittenCallback_t& callback) {
- dataWrittenCallChain.add(callback);
- }
-
- /**
- * Same as GattServer::onDataWritten(), but allows the possibility to add an object
- * reference and member function as handler for data written event
- * callbacks.
- *
- * @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.
- */
+ void onDataWritten(const DataWrittenCallback_t& callback) {dataWrittenCallChain.add(callback);}
template <typename T>
void onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
dataWrittenCallChain.add(objPtr, memberPtr);
}
/**
- * @brief Provide access to the callchain of data written event callbacks.
- *
- * @return A reference to the data written event callbacks chain.
- *
- * @note It is possible to register callbacks using onDataWritten().add(callback).
- *
- * @note It is possible to unregister callbacks using onDataWritten().detach(callback).
+ * @brief provide access to the callchain of data written event callbacks
+ * It is possible to register callbacks using onDataWritten().add(callback);
+ * It is possible to unregister callbacks using onDataWritten().detach(callback)
+ * @return The data written event callbacks chain
*/
DataWrittenCallbackChain_t& onDataWritten() {
return dataWrittenCallChain;
@@ -383,25 +299,22 @@
* Setup a callback to be invoked on the peripheral when an attribute is
* being read by a remote client.
*
- * @param[in] callback
- * Event handler being registered.
- *
- * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
- * else BLE_ERROR_NONE.
- *
- * @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. Refer to isOnDataReadAvailable().
*
- * @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.
*
- * @note It is possible to unregister a callback using onDataRead().detach(callback).
+ * @Note It is possible to unregister a callback using onDataRead().detach(callback)
+ *
+ * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
+ * else BLE_ERROR_NONE.
*/
ble_error_t onDataRead(const DataReadCallback_t& callback) {
if (!isOnDataReadAvailable()) {
@@ -411,19 +324,6 @@
dataReadCallChain.add(callback);
return BLE_ERROR_NONE;
}
-
- /**
- * Same as GattServer::onDataRead(), but allows the possibility to add an object
- * reference and member function as handler for data read event
- * callbacks.
- *
- * @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.
- */
template <typename T>
ble_error_t onDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
if (!isOnDataReadAvailable()) {
@@ -435,13 +335,10 @@
}
/**
- * @brief Provide access to the callchain of data read event callbacks.
- *
- * @return A reference to the data read event callbacks chain.
- *
- * @note It is possible to register callbacks using onDataRead().add(callback).
- *
- * @note It is possible to unregister callbacks using onDataRead().detach(callback).
+ * @brief provide access to the callchain of data read event callbacks
+ * It is possible to register callbacks using onDataRead().add(callback);
+ * It is possible to unregister callbacks using onDataRead().detach(callback)
+ * @return The data read event callbacks chain
*/
DataReadCallbackChain_t& onDataRead() {
return dataReadCallChain;
@@ -452,47 +349,28 @@
* GattServer instance is about to shutdown (possibly as a result of a call
* to BLE::shutdown()).
*
- * @param[in] callback
- * Event handler being registered.
- *
- * @note It is possible to chain together multiple onShutdown callbacks
+ * @Note: It is possible to chain together multiple onShutdown callbacks
* (potentially from different modules of an application) to be notified
* before the GattServer 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 GattServerShutdownCallback_t& callback) {
shutdownCallChain.add(callback);
}
-
- /**
- * Same as GattServer::onShutdown(), but allows the possibility to add an object
- * reference and member function as handler for shutdown event
- * callbacks.
- *
- * @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.
- */
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.
- *
- * @return A reference to the shutdown event callbacks chain.
- *
- * @note It is possible to register callbacks using onShutdown().add(callback).
- *
- * @note It is possible to unregister callbacks using onShutdown().detach(callback).
+ * @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
*/
GattServerShutdownCallbackChain_t& onShutdown() {
return shutdownCallChain;
@@ -501,75 +379,31 @@
/**
* Set up a callback for when notifications or indications are enabled for a
* characteristic on the local GATT server.
- *
- * @param[in] callback
- * Event handler being registered.
*/
- void onUpdatesEnabled(EventCallback_t callback) {
- updatesEnabledCallback = callback;
- }
+ void onUpdatesEnabled(EventCallback_t callback) {updatesEnabledCallback = callback;}
/**
* Set up a callback for when notifications or indications are disabled for a
* characteristic on the local GATT server.
- *
- * @param[in] callback
- * Event handler being registered.
*/
- void onUpdatesDisabled(EventCallback_t callback) {
- updatesDisabledCallback = callback;
- }
+ void onUpdatesDisabled(EventCallback_t callback) {updatesDisabledCallback = callback;}
/**
* Set up a callback for when the GATT server receives a response for an
* indication event sent previously.
- *
- * @param[in] callback
- * Event handler being registered.
*/
- void onConfirmationReceived(EventCallback_t callback) {
- confirmationReceivedCallback = callback;
- }
+ void onConfirmationReceived(EventCallback_t callback) {confirmationReceivedCallback = callback;}
/* Entry points for the underlying stack to report events back to the user. */
protected:
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of a data written event. This function is meant to be called from the
- * BLE stack specific implementation when a data written event occurs.
- *
- * @param[in] params
- * The data written parameters passed to the registered
- * handlers.
- */
void handleDataWrittenEvent(const GattWriteCallbackParams *params) {
dataWrittenCallChain.call(params);
}
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of a data read event. This function is meant to be called from the
- * BLE stack specific implementation when a data read event occurs.
- *
- * @param[in] params
- * The data read parameters passed to the registered
- * handlers.
- */
void handleDataReadEvent(const GattReadCallbackParams *params) {
dataReadCallChain.call(params);
}
- /**
- * Helper function that notifies the registered handler of an occurrence
- * of updates enabled, updates disabled and confirmation received events.
- * This function is meant to be called from the BLE stack specific
- * implementation when any of these events occurs.
- *
- * @param[in] type
- * The type of event that occurred.
- * @param[in] attributeHandle
- * The handle of the attribute that was modified.
- */
void handleEvent(GattServerEvents::gattEvent_e type, GattAttribute::Handle_t attributeHandle) {
switch (type) {
case GattServerEvents::GATT_EVENT_UPDATES_ENABLED:
@@ -592,14 +426,6 @@
}
}
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of a data sent event. This function is meant to be called from the
- * BLE stack specific implementation when a data sent event occurs.
- *
- * @param[in] count
- * Number of packets sent.
- */
void handleDataSentEvent(unsigned count) {
dataSentCallChain.call(count);
}
@@ -637,47 +463,16 @@
}
protected:
- /**
- * The total number of services added to the ATT table.
- */
uint8_t serviceCount;
- /**
- * The total number of characteristics added to the ATT table.
- */
uint8_t characteristicCount;
private:
- /**
- * Callchain containing all registered callback handlers for data sent
- * events.
- */
DataSentCallbackChain_t dataSentCallChain;
- /**
- * Callchain containing all registered callback handlers for data written
- * events.
- */
DataWrittenCallbackChain_t dataWrittenCallChain;
- /**
- * Callchain containing all registered callback handlers for data read
- * events.
- */
DataReadCallbackChain_t dataReadCallChain;
- /**
- * Callchain containing all registered callback handlers for shutdown
- * events.
- */
GattServerShutdownCallbackChain_t shutdownCallChain;
- /**
- * The registered callback handler for updates enabled events.
- */
EventCallback_t updatesEnabledCallback;
- /**
- * The registered callback handler for updates disabled events.
- */
EventCallback_t updatesDisabledCallback;
- /**
- * The registered callback handler for confirmation received events.
- */
EventCallback_t confirmationReceivedCallback;
private:
@@ -686,4 +481,4 @@
GattServer& operator=(const GattServer &);
};
-#endif /* ifndef __GATT_SERVER_H__ */
\ No newline at end of file
+#endif // ifndef __GATT_SERVER_H__
\ No newline at end of file
--- a/ble/GattServerEvents.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GattServerEvents.h Wed Apr 06 19:15:30 2016 +0100
@@ -17,16 +17,14 @@
#ifndef __GATT_SERVER_EVENTS_H__
#define __GATT_SERVER_EVENTS_H__
-/**
- * @brief The base class used to abstract away the callback events that can be
- * triggered with the GATT Server.
- */
+/*!
+ \brief
+ The base class used to abstract away the callback events that can be
+ triggered with the GATT Server.
+*/
class GattServerEvents
{
public:
- /**
- * Enumeration for GattServer events.
- */
typedef enum gattEvent_e {
GATT_EVENT_DATA_SENT = 1, /**< Fired when a message was successfully sent out (notify only?) */
GATT_EVENT_DATA_WRITTEN = 2, /**< Client wrote data to the server (separate into char and descriptor writes?) */
@@ -38,4 +36,4 @@
} gattEvent_t;
};
-#endif /* ifndef __GATT_SERVER_EVENTS_H__ */
\ No newline at end of file
+#endif // ifndef __GATT_SERVER_EVENTS_H__
\ No newline at end of file
--- a/ble/GattService.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/GattService.h Wed Apr 06 19:15:30 2016 +0100
@@ -59,58 +59,15 @@
* The number of characteristics.
*/
GattService(const UUID &uuid, GattCharacteristic *characteristics[], unsigned numCharacteristics) :
- _primaryServiceID(uuid),
- _characteristicCount(numCharacteristics),
- _characteristics(characteristics),
- _handle(0) {
+ _primaryServiceID(uuid), _characteristicCount(numCharacteristics), _characteristics(characteristics), _handle(0) {
/* empty */
}
- /**
- * Get this service's UUID.
- *
- * @return A reference to the service's UUID.
- */
- const UUID &getUUID(void) const {
- return _primaryServiceID;
- }
-
- /**
- * Get handle of the service declaration attribute in the ATT table.
- *
- * @return The service's handle.
- */
- uint16_t getHandle(void) const {
- return _handle;
- }
+ const UUID &getUUID(void) const {return _primaryServiceID; }
+ uint16_t getHandle(void) const {return _handle; }
+ uint8_t getCharacteristicCount(void) const {return _characteristicCount;}
+ void setHandle(uint16_t handle) {_handle = handle;}
- /**
- * Get the total number of characteristics within this service.
- *
- * @return The total number of characteristics within this service.
- */
- uint8_t getCharacteristicCount(void) const {
- return _characteristicCount;
- }
-
- /**
- * Set the handle of the service declaration attribute in the ATT table.
- *
- * @param[in] handle
- * The service's handle.
- */
- void setHandle(uint16_t handle) {
- _handle = handle;
- }
-
- /**
- * Get this service's characteristic at a specific index.
- *
- * @param[in] index
- * The index of the characteristic.
- *
- * @return A pointer to the characterisitic at index @p index.
- */
GattCharacteristic *getCharacteristic(uint8_t index) {
if (index >= _characteristicCount) {
return NULL;
@@ -120,25 +77,10 @@
}
private:
- /**
- * This service's UUID.
- */
UUID _primaryServiceID;
- /**
- * Total number of characteristics within this service.
- */
uint8_t _characteristicCount;
- /**
- * An array with pointers to the characteristics added to this service.
- */
GattCharacteristic **_characteristics;
- /**
- * Handle of the service declaration attribute in the ATT table.
- *
- * @note This handle is generally assigned by the underlying BLE stack when the
- * service is added to the ATT table.
- */
uint16_t _handle;
};
-#endif /* ifndef __GATT_SERVICE_H__ */
\ No newline at end of file
+#endif // ifndef __GATT_SERVICE_H__
\ No newline at end of file
--- a/ble/SafeBool.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/SafeBool.h Wed Apr 06 19:15:30 2016 +0100
@@ -17,32 +17,26 @@
#ifndef BLE_API_SAFE_BOOL_H_
#define BLE_API_SAFE_BOOL_H_
-/* Safe bool idiom, see : http://www.artima.com/cppsource/safebool.html */
+//safe bool idiom, see : http://www.artima.com/cppsource/safebool.html
namespace SafeBool_ {
/**
- * @brief Base class for all intances of SafeBool.
- * This base class reduces instantiation of trueTag function.
+ * @brief Base class for all intances of SafeBool,
+ * This base class reduce instantiation of trueTag function
*/
class base {
template<typename>
friend class SafeBool;
protected:
- /**
- * The bool type is a pointer to method which can be used in boolean context.
- */
- typedef void (base::*BoolType_t)() const;
+ //the bool type is a pointer to method which can be used in boolean context
+ typedef void (base::*BoolType_t)() const;
- /**
- * Non implemented call, use to disallow conversion between unrelated types.
- */
- void invalidTag() const;
+ // non implemented call, use to disallow conversion between unrelated types
+ void invalidTag() const;
- /**
- * Member function which indicate true value.
- */
- void trueTag() const {}
+ // member function which indicate true value
+ void trueTag() const {}
};
@@ -50,75 +44,71 @@
/**
* @brief template class SafeBool use CRTP to made boolean conversion easy and correct.
- * Derived class should implement the function bool toBool() const to make this work. Inheritance
+ * Derived class should implement the function bool toBool() const to make this work. Inheritance
* should be public.
*
* @tparam T Type of the derived class
- *
- * @code
- *
- * class A : public SafeBool<A> {
+ *
+ * \code
+ *
+ * class A : public SafeBool<A> {
* public:
- *
+ *
* // boolean conversion
- * bool toBool() {
- *
- * }
+ * bool toBool() {
+ *
+ * }
* };
- *
- * class B : public SafeBool<B> {
+ *
+ * class B : public SafeBool<B> {
* public:
- *
+ *
* // boolean conversion
- * bool toBool() const {
- *
- * }
+ * bool toBool() const {
+ *
+ * }
* };
- *
+ *
* A a;
* B b;
- *
- * // will compile
- * if(a) {
- *
+ *
+ * // will compile
+ * if(a) {
+ *
* }
- *
- * // compilation error
- * if(a == b) {
- *
+ *
+ * // compilation error
+ * if(a == b) {
+ *
* }
- *
- *
- * @endcode
+ *
+ *
+ * \endcode
*/
-template <typename T>
+template <typename T>
class SafeBool : public SafeBool_::base {
public:
- /**
- * Bool operator implementation, derived class has to provide bool toBool() const function.
- */
- operator BoolType_t() const {
- return (static_cast<const T*>(this))->toBool()
- ? &SafeBool<T>::trueTag : 0;
- }
+ /**
+ * bool operator implementation, derived class has to provide bool toBool() const function.
+ */
+ operator BoolType_t() const {
+ return (static_cast<const T*>(this))->toBool()
+ ? &SafeBool<T>::trueTag : 0;
+ }
};
-/**
- * Avoid conversion to bool between different classes.
- */
+//Avoid conversion to bool between different classes
template <typename T, typename U>
void operator==(const SafeBool<T>& lhs,const SafeBool<U>& rhs) {
lhs.invalidTag();
- // return false;
+// return false;
}
-/**
- * Avoid conversion to bool between different classes.
- */
+//Avoid conversion to bool between different classes
template <typename T,typename U>
void operator!=(const SafeBool<T>& lhs,const SafeBool<U>& rhs) {
- lhs.invalidTag();
- // return false;
+ lhs.invalidTag();
+// return false;
}
#endif /* BLE_API_SAFE_BOOL_H_ */
\ No newline at end of file
--- a/ble/SecurityManager.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/SecurityManager.h Wed Apr 06 19:15:30 2016 +0100
@@ -166,7 +166,7 @@
/**
* Get a list of addresses from all peers in the bond table.
*
- * @param[in,out] addresses
+ * @param[in/out] addresses
* (on input) addresses.capacity contains the maximum
* number of addresses to be returned.
* (on output) The populated table with copies of the
@@ -192,14 +192,14 @@
* SecurityManager 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
+ * @Note: It is possible to chain together multiple onShutdown callbacks
* (potentially from different modules of an application) to be notified
* before the SecurityManager 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 SecurityManagerShutdownCallback_t& callback) {
shutdownCallChain.add(callback);
--- a/ble/ServiceDiscovery.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/ServiceDiscovery.h Wed Apr 06 19:15:30 2016 +0100
@@ -117,7 +117,7 @@
const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) = 0;
/**
- * Check whether service-discovery is currently active.
+ * Is service-discovery currently active?
*/
virtual bool isActive(void) const = 0;
@@ -154,30 +154,11 @@
}
protected:
- /**
- * Connection handle as provided by the SoftDevice.
- */
- Gap::Handle_t connHandle;
- /**
- * UUID-based filter that specifies the service that the application is
- * interested in.
- */
+ Gap::Handle_t connHandle; /**< Connection handle as provided by the SoftDevice. */
UUID matchingServiceUUID;
- /**
- * The registered callback handle for when a matching service is found
- * during service-discovery.
- */
ServiceCallback_t serviceCallback;
- /**
- * UUID-based filter that specifies the characteristic that the
- * application is interested in.
- */
UUID matchingCharacteristicUUID;
- /**
- * The registered callback handler for when a matching characteristic is
- * found during service-discovery.
- */
CharacteristicCallback_t characteristicCallback;
};
-#endif /* ifndef __SERVICE_DISOVERY_H__ */
\ No newline at end of file
+#endif // ifndef __SERVICE_DISOVERY_H__
\ No newline at end of file
--- a/ble/UUID.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/UUID.h Wed Apr 06 19:15:30 2016 +0100
@@ -24,12 +24,9 @@
#include "blecommon.h"
/**
- * A trivial converter for single hexadecimal character to an unsigned integer.
- *
- * @param c
- * Hexadecimal character.
- *
- * @return The corresponding value as unsigned integer.
+ * A trivial converter for single hexadecimal character to unsigned-int.
+ * @param c hexadecimal character.
+ * @return the corresponding value as unsigned int.
*/
static uint8_t char2int(char c) {
if ((c >= '0') && (c <= '9')) {
@@ -43,47 +40,26 @@
}
}
-/**
- * An instance of this class represents a Universally Unique Identifier (UUID)
- * in the BLE API.
- */
class UUID {
public:
- /**
- * Enumeration of the possible types of UUIDs in BLE with regards to length.
- */
enum UUID_Type_t {
- UUID_TYPE_SHORT = 0, /**< Short 16-bit UUID. */
- UUID_TYPE_LONG = 1 /**< Full 128-bit UUID. */
+ UUID_TYPE_SHORT = 0, // Short BLE UUID.
+ UUID_TYPE_LONG = 1 // Full 128-bit UUID.
};
/**
- * Enumeration to specify byte ordering of the long version of the UUID.
+ * An enumeration to specify byte ordering of the long version of the UUID.
*/
typedef enum {
- MSB, /**< Most-significant byte first (at the smallest address) */
- LSB /**< least-significant byte first (at the smallest address) */
+ MSB, /*!< Most-significant byte first (at the smallest address) */
+ LSB /*!< least-significant byte first (at the smallest address) */
} ByteOrder_t;
- /**
- * Type for a 16-bit UUID.
- */
typedef uint16_t ShortUUIDBytes_t;
- /**
- * Length of a long UUID in bytes.
- */
static const unsigned LENGTH_OF_LONG_UUID = 16;
- /**
- * Type for a 128-bit UUID.
- */
typedef uint8_t LongUUIDBytes_t[LENGTH_OF_LONG_UUID];
- /**
- * Maximum length of a string representation of a UUID not including the
- * null termination ('\0'): two characters per
- * byte plus four '-' characters.
- */
static const unsigned MAX_UUID_STRING_LENGTH = LENGTH_OF_LONG_UUID * 2 + 4;
public:
@@ -107,32 +83,30 @@
size_t baseIndex = 0;
uint8_t tempUUID[LENGTH_OF_LONG_UUID];
- /*
- * Iterate through string, abort if NULL is encountered prematurely.
- * Ignore upto four hyphens.
- */
+ // Iterate through string, abort if NULL is encountered prematurely.
+ // Ignore upto four hyphens.
for (size_t index = 0; (index < MAX_UUID_STRING_LENGTH) && (baseIndex < LENGTH_OF_LONG_UUID); index++) {
if (stringUUID[index] == '\0') {
- /* Error abort */
+ // error abort
break;
} else if (stringUUID[index] == '-') {
- /* Ignore hyphen */
+ // ignore hyphen
continue;
} else if (nibble) {
- /* Got second nibble */
+ // got second nibble
byte |= char2int(stringUUID[index]);
nibble = false;
- /* Store copy */
+ // store copy
tempUUID[baseIndex++] = byte;
} else {
- /* Got first nibble */
+ // got first nibble
byte = char2int(stringUUID[index]) << 4;
nibble = true;
}
}
- /* Populate internal variables if string was successfully parsed */
+ // populate internal variables if string was successfully parsed
if (baseIndex == LENGTH_OF_LONG_UUID) {
setupLong(tempUUID, UUID::MSB);
} else {
@@ -145,13 +119,13 @@
/**
* Creates a new 128-bit UUID.
*
- * @param[in] longUUID
- * The 128-bit (16-byte) UUID value.
- * @param[in] order
- * The bit order of the UUID, MSB by default.
- *
* @note The UUID is a unique 128-bit (16 byte) ID used to identify
* different service or characteristics on the BLE device.
+ *
+ * @param longUUID
+ * The 128-bit (16-byte) UUID value.
+ * @param order
+ * The bit order of the UUID, MSB by default.
*/
UUID(const LongUUIDBytes_t longUUID, ByteOrder_t order = UUID::MSB) : type(UUID_TYPE_LONG), baseUUID(), shortUUID(0) {
setupLong(longUUID, order);
@@ -160,6 +134,9 @@
/**
* Creates a new 16-bit UUID.
*
+ * @note The UUID is a unique 16-bit (2 byte) ID used to identify
+ * different service or characteristics on the BLE device.
+ *
* For efficiency, and because 16 bytes would take a large chunk of the
* 27-byte data payload length of the Link Layer, the BLE specification adds
* two additional UUID formats: 16-bit and 32-bit UUIDs. These shortened
@@ -173,61 +150,34 @@
*
* 0000xxxx-0000-1000-8000-00805F9B34FB
*
- * @param[in] _shortUUID
- * The short UUID value.
- *
* @note Shortening is not available for UUIDs that are not derived from the
* Bluetooth Base UUID. Such non-standard UUIDs are commonly called
* vendor-specific UUIDs. In these cases, you’ll need to use the full
* 128-bit UUID value at all times.
*
- * @note The UUID is a unique 16-bit (2 byte) ID used to identify
- * different service or characteristics on the BLE device.
- *
- * @note We do not yet support 32-bit shortened UUIDs.
+ * @note We don't yet support 32-bit shortened UUIDs.
*/
UUID(ShortUUIDBytes_t _shortUUID) : type(UUID_TYPE_SHORT), baseUUID(), shortUUID(_shortUUID) {
/* Empty */
}
- /**
- * Copy constructor.
- *
- * @param[in] source
- * The UUID to copy.
- */
UUID(const UUID &source) {
type = source.type;
shortUUID = source.shortUUID;
memcpy(baseUUID, source.baseUUID, LENGTH_OF_LONG_UUID);
}
- /**
- * The empty constructor.
- *
- * @note The type of the resulting UUID instance is UUID_TYPE_SHORT and the
- * value BLE_UUID_UNKNOWN.
- */
UUID(void) : type(UUID_TYPE_SHORT), shortUUID(BLE_UUID_UNKNOWN) {
/* empty */
}
/**
- * Fill in a 128-bit UUID; this is useful when the UUID is not known at the
- * time of the object construction.
- *
- * @param[in] longUUID
- * The UUID value to copy.
- * @param[in] order
- * The byte ordering of the UUID at @p longUUID.
+ * Fill in a 128-bit UUID; this is useful when the UUID isn't known at the time of the object construction.
*/
void setupLong(const LongUUIDBytes_t longUUID, ByteOrder_t order = UUID::MSB) {
type = UUID_TYPE_LONG;
if (order == UUID::MSB) {
- /*
- * Switch endian. Input is big-endian, internal representation
- * is little endian.
- */
+ // Switch endian. Input is big-endian, internal representation is little endian.
std::reverse_copy(longUUID, longUUID + LENGTH_OF_LONG_UUID, baseUUID);
} else {
std::copy(longUUID, longUUID + LENGTH_OF_LONG_UUID, baseUUID);
@@ -236,23 +186,8 @@
}
public:
- /**
- * Check whether this UUID is short or long.
- *
- * @return UUID_TYPE_SHORT if the UUID is short, UUID_TYPE_LONG otherwise.
- */
- UUID_Type_t shortOrLong(void) const {
- return type;
- }
-
- /**
- * Get a pointer to the UUID value based on the current UUID type.
- *
- * @return A pointer to the short UUID if the type is set to
- * UUID_TYPE_SHORT. Otherwise, a pointer to the long UUID if the
- * type is set to UUID_TYPE_LONG.
- */
- const uint8_t *getBaseUUID(void) const {
+ UUID_Type_t shortOrLong(void) const {return type; }
+ const uint8_t *getBaseUUID(void) const {
if (type == UUID_TYPE_SHORT) {
return (const uint8_t*)&shortUUID;
} else {
@@ -260,33 +195,11 @@
}
}
- /**
- * Get the short UUID.
- *
- * @return The short UUID.
- */
- ShortUUIDBytes_t getShortUUID(void) const {
- return shortUUID;
- }
-
- /**
- * Get the length (in bytes) of the UUID based on its type.
- *
- * @retval sizeof(ShortUUIDBytes_t) if the UUID type is UUID_TYPE_SHORT.
- * @retval LENGTH_OF_LONG_UUID if the UUID type is UUID_TYPE_LONG.
- */
- uint8_t getLen(void) const {
+ ShortUUIDBytes_t getShortUUID(void) const {return shortUUID;}
+ uint8_t getLen(void) const {
return ((type == UUID_TYPE_SHORT) ? sizeof(ShortUUIDBytes_t) : LENGTH_OF_LONG_UUID);
}
- /**
- * Overload == operator to enable UUID comparisons.
- *
- * @param[in] other
- * The other UUID in the comparison.
- *
- * @return true if this == @p other, false otherwise.
- */
bool operator== (const UUID &other) const {
if ((this->type == UUID_TYPE_SHORT) && (other.type == UUID_TYPE_SHORT) &&
(this->shortUUID == other.shortUUID)) {
@@ -301,31 +214,14 @@
return false;
}
- /**
- * Overload != operator to enable UUID comparisons.
- *
- * @param[in] other
- * The other UUID in the comparison.
- *
- * @return true if this != @p other, false otherwise.
- */
bool operator!= (const UUID &other) const {
return !(*this == other);
}
private:
- /**
- * The UUID type. Refer to UUID_Type_t.
- */
- UUID_Type_t type;
- /**
- * The long UUID value.
- */
- LongUUIDBytes_t baseUUID;
- /**
- * The short UUID value.
- */
- ShortUUIDBytes_t shortUUID;
+ UUID_Type_t type; // UUID_TYPE_SHORT or UUID_TYPE_LONG
+ LongUUIDBytes_t baseUUID; // The long UUID
+ ShortUUIDBytes_t shortUUID; // 16 bit UUID
};
#endif // ifndef __UUID_H__
\ No newline at end of file
--- a/ble/services/BatteryService.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/services/BatteryService.h Wed Apr 06 19:15:30 2016 +0100
@@ -28,7 +28,7 @@
class BatteryService {
public:
/**
- * @param[in] _ble
+ * @param[ref] _ble
* BLE object for the underlying controller.
* @param[in] level
* 8bit batterly level. Usually used to represent percentage of batterly charge remaining.
@@ -45,7 +45,7 @@
}
/**
- * @brief Update the battery level with a new value. Valid values lie between 0 and 100,
+ * @brief Update the battery level with a new value. [Valid values lie between 0 and 100];
* anything outside this range will be ignored.
*
* @param newLevel
@@ -57,20 +57,9 @@
}
protected:
- /**
- * A reference to the underlying BLE instance that this object is attached to.
- * The services and characteristics will be registered in this BLE instance.
- */
BLE &ble;
- /**
- * The current battery level represented as an integer from 0% to 100%.
- */
uint8_t batteryLevel;
- /**
- * A ReadOnlyGattCharacteristic that allows access to the peer device to the
- * batteryLevel value through BLE.
- */
ReadOnlyGattCharacteristic<uint8_t> batteryLevelCharacteristic;
};
--- a/ble/services/DeviceInformationService.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/services/DeviceInformationService.h Wed Apr 06 19:15:30 2016 +0100
@@ -28,21 +28,21 @@
class DeviceInformationService {
public:
/**
- * @brief Device Information Service Constructor: copies device-specific information
+ * @brief Device Information Service Constructor: copies device-specific information
* into the BLE stack.
*
- * @param[in] _ble
- * A reference to a BLE object for the underlying controller.
+ * @param[ref] _ble
+ * BLE object for the underlying controller.
* @param[in] manufacturersName
* The name of the manufacturer of the device.
* @param[in] modelNumber
* The model number that is assigned by the device vendor.
* @param[in] serialNumber
- * The serial number for a particular instance of the device.
+ * The serial number for a particular instance of the device.
* @param[in] hardwareRevision
* The hardware revision for the hardware within the device.
* @param[in] firmwareRevision
- * The device's firmware version.
+ * The device's firmware version.
* @param[in] softwareRevision
* The device's software version.
*/
@@ -104,34 +104,12 @@
}
protected:
- /**
- * A reference to the BLE instance object to which the services and
- * characteristics will be added.
- */
BLE &ble;
- /**
- * BLE characterising to allow BLE peers access to the manufacturer's name.
- */
GattCharacteristic manufacturersNameStringCharacteristic;
- /**
- * BLE characterising to allow BLE peers access to the model number.
- */
GattCharacteristic modelNumberStringCharacteristic;
- /**
- * BLE characterising to allow BLE peers access to the serial number.
- */
GattCharacteristic serialNumberStringCharacteristic;
- /**
- * BLE characterising to allow BLE peers access to the hardware revision string.
- */
GattCharacteristic hardwareRevisionStringCharacteristic;
- /**
- * BLE characterising to allow BLE peers access to the firmware revision string.
- */
GattCharacteristic firmwareRevisionStringCharacteristic;
- /**
- * BLE characterising to allow BLE peers access to the software revision string.
- */
GattCharacteristic softwareRevisionStringCharacteristic;
};