Jörg Küfen
fka mod
Fork of
BLE_API
by 
Bluetooth Low Energy
Diff: ble/Gap.h
- Revision:
- 993:4d62b7967c11
- Parent:
- 992:ca834f7ae8ed
- Child:
- 1009:255f75c96eaa
diff -r ca834f7ae8ed -r 4d62b7967c11 ble/Gap.h
--- a/ble/Gap.h Wed Dec 02 10:29:44 2015 +0000
+++ b/ble/Gap.h Wed Dec 02 10:29:44 2015 +0000
@@ -24,7 +24,7 @@
#include "CallChainOfFunctionPointersWithContext.h"
#include "FunctionPointerWithContext.h"
-/* Forward declarations for classes which will only be used for pointers or references in the following. */
+/* Forward declarations for classes that will only be used for pointers or references in the following. */
class GapAdvertisingParams;
class GapScanningParams;
class GapAdvertisingData;
@@ -37,11 +37,11 @@
ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE,
ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE
};
- typedef enum AddressType_t addr_type_t; /* @Note: deprecated. Use AddressType_t instead. */
+ typedef enum AddressType_t addr_type_t; /* @Note: Deprecated. Use AddressType_t instead. */
static const unsigned ADDR_LEN = 6;
typedef uint8_t Address_t[ADDR_LEN]; /* 48-bit address, LSB format. */
- typedef Address_t address_t; /* @Note: deprecated. Use Address_t instead. */
+ typedef Address_t address_t; /* @Note: Deprecated. Use Address_t instead. */
enum TimeoutSource_t {
TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */
@@ -52,24 +52,24 @@
/**
* Enumeration for disconnection reasons. The values for these reasons are
- * derived from Nordic's implementation; but the reasons are meant to be
- * independent of the transport. If you are returned a reason which is not
- * covered by this enumeration, then please refer to the underlying
+ * derived from Nordic's implementation, but the reasons are meant to be
+ * independent of the transport. If you are returned a reason that is not
+ * covered by this enumeration, please refer to the underlying
* transport library.
*/
enum DisconnectionReason_t {
CONNECTION_TIMEOUT = 0x08,
REMOTE_USER_TERMINATED_CONNECTION = 0x13,
- REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, /**< Remote Device Terminated Connection due to low resources.*/
- REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /**< Remote Device Terminated Connection due to power off. */
+ REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, /**< Remote device terminated connection due to low resources.*/
+ REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /**< Remote device terminated connection due to power off. */
LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
CONN_INTERVAL_UNACCEPTABLE = 0x3B,
};
- /* 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 */
+ unsigned advertising : 1; /**< Peripheral is currently advertising. */
+ unsigned connected : 1; /**< Peripheral is connected to a central. */
};
typedef uint16_t Handle_t; /* Type for connection handle. */
@@ -140,10 +140,15 @@
return (durationInMillis * 1000) / UNIT_1_25_MS;
}
+ typedef FunctionPointerWithContext<TimeoutSource_t> TimeoutEventCallback_t;
+ typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> TimeoutEventCallbackChain_t;
- typedef void (*TimeoutEventCallback_t)(TimeoutSource_t source);
- typedef void (*ConnectionEventCallback_t)(const ConnectionCallbackParams_t *params);
- typedef void (*DisconnectionEventCallback_t)(const DisconnectionCallbackParams_t *params);
+ typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallback_t;
+ typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t;
+
+ typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
+ typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t;
+
typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
/*
@@ -152,7 +157,7 @@
public:
/**
* Set the BTLE MAC address and type. Please note that the address format is
- * LSB (least significant byte first). Please refer to Address_t.
+ * least significant byte first (LSB). Please refer to Address_t.
*
* @return BLE_ERROR_NONE on success.
*/
@@ -170,7 +175,7 @@
* @return BLE_ERROR_NONE on success.
*/
virtual ble_error_t getAddress(AddressType_t *typeP, Address_t address) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)typeP;
(void)address;
@@ -230,7 +235,7 @@
Gap::AddressType_t peerAddrType,
const ConnectionParams_t *connectionParams,
const GapScanningParams *scanParams) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)peerAddr;
(void)peerAddrType;
(void)connectionParams;
@@ -245,7 +250,7 @@
* disconnectionCallback.
*
* @param reason
- * The reason for disconnection to be sent back to the peer.
+ * 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 */
@@ -261,15 +266,15 @@
* disconnectionCallback.
*
* @param reason
- * The reason for disconnection to be sent back to the peer.
+ * The reason for disconnection; to be sent back to the peer.
*
- * @note: this version of disconnect() doesn't take a connection handle. It
- * will work reliably only for stacks which are limited to a single
+ * @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
- * altertive which takes a connection handle. It will be dropped in the future.
+ * 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 */
+ /* Avoid compiler warnings about unused variables. */
(void)reason;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -288,7 +293,7 @@
* the given structure pointed to by params.
*/
virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)params;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -303,7 +308,7 @@
* The structure containing the desired parameters.
*/
virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)params;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -311,12 +316,12 @@
/**
* Update connection parameters.
- * In the central role this will initiate a Link Layer connection parameter update procedure,
- * otherwise in the peripheral role, this will send the corresponding L2CAP request and wait for
+ * 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
+ * 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.
@@ -335,7 +340,7 @@
* The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
*/
virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)deviceName;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -373,7 +378,7 @@
* The new value for the device-appearance.
*/
virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)appearance;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -385,7 +390,7 @@
* The new value for the device-appearance.
*/
virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)appearanceP;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -396,7 +401,7 @@
* @param[in] txPower Radio transmit power in dBm.
*/
virtual ble_error_t setTxPower(int8_t txPower) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)txPower;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -411,7 +416,7 @@
* Out parameter to receive the array's size.
*/
virtual void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
- /* avoid compiler warnings about unused variables */
+ /* Avoid compiler warnings about unused variables. */
(void)valueArrayPP;
(void)countP;
@@ -430,8 +435,8 @@
*/
public:
/**
- * Returns the current GAP state of the device using a bitmask which
- * describes whether the device is advertising and/or connected.
+ * Returns the current GAP state of the device using a bitmask that
+ * describes whether the device is advertising or connected.
*/
GapState_t getState(void) const {
return state;
@@ -456,7 +461,7 @@
* 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
+ * peripheral faster, at the expense of more power being used by the radio
* due to the higher data transmit rate.
*
* @note: This API is now *deprecated* and will be dropped in the future.
@@ -468,7 +473,7 @@
* '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 would need to be updated accordingly.
+ * code depending on the old semantics needs to be updated accordingly.
*/
void setAdvertisingInterval(uint16_t interval) {
if (interval == 0) {
@@ -492,17 +497,14 @@
* Start advertising.
*/
ble_error_t startAdvertising(void) {
- setAdvertisingData(); /* update the underlying stack */
+ setAdvertisingData(); /* Update the underlying stack. */
return startAdvertising(_advParams);
}
/**
* Reset any advertising payload prepared from prior calls to
* accumulateAdvertisingPayload(). This automatically propagates the re-
- * initialized adv payload to the underlying stack.
- *
- * Note: This should be followed by a call to setAdvertisingPayload() or
- * startAdvertising() before the update takes effect.
+ * initialized advertising payload to the underlying stack.
*/
void clearAdvertisingPayload(void) {
_advPayload.clear();
@@ -512,7 +514,7 @@
/**
* Accumulate an AD structure in the advertising payload. Please note that
* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
- * as an additional 31 bytes if the advertising payload proves to be too
+ * as an additional 31 bytes if the advertising payload is too
* small.
*
* @param[in] flags
@@ -532,7 +534,7 @@
/**
* Accumulate an AD structure in the advertising payload. Please note that
* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
- * as an additional 31 bytes if the advertising payload proves to be too
+ * as an additional 31 bytes if the advertising payload is too
* small.
*
* @param app
@@ -552,12 +554,11 @@
/**
* Accumulate an AD structure in the advertising payload. Please note that
* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
- * as an additional 31 bytes if the advertising payload proves to be too
+ * as an additional 31 bytes if the advertising payload is too
* small.
*
- * @param app
+ * @param power
* The max transmit power to be used by the controller (in dBm).
- * This is only a hint.
*/
ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
ble_error_t rc;
@@ -572,11 +573,11 @@
* Accumulate a variable length byte-stream as an AD structure in the
* advertising payload. Please note that the payload is limited to 31 bytes.
* The SCAN_RESPONSE message may be used as an additional 31 bytes if the
- * advertising payload proves to be too small.
+ * advertising payload is too small.
*
- * @param type The type which describes the variable length data.
- * @param data data bytes.
- * @param len length of data.
+ * @param type The type describing the variable length data.
+ * @param data Data bytes.
+ * @param len Length of data.
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@@ -596,14 +597,14 @@
* matching type and length). Note: the length of the new data must be the
* same as the old one.
*
- * @param[in] type The ADV type field which describes 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.
*
* @return BLE_ERROR_NONE if the advertisement payload was updated based on
- * a <type, len> match; else an appropriate error.
+ * a <type, len> match; otherwise, an appropriate error.
*/
ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@@ -619,7 +620,7 @@
}
/**
- * Setup a particular, user-constructed advertisement payload for the
+ * Set up a particular, user-constructed advertisement payload for the
* underlying stack. It would be uncommon for this API to be used directly;
* there are other APIs to build an advertisement payload (see above).
*/
@@ -640,9 +641,9 @@
* Accumulate a variable length byte-stream as an AD structure in the
* scanResponse payload.
*
- * @param[in] type The type which describes the variable length data.
- * @param[in] data data bytes.
- * @param[in] len length of data.
+ * @param[in] type The type describing the variable length data.
+ * @param[in] data Data bytes.
+ * @param[in] len Length of data.
*/
ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
ble_error_t rc;
@@ -666,13 +667,13 @@
}
/**
- * Setup parameters for GAP scanning--i.e. observer mode.
+ * 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
* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
* @param[in] timeout
- * Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout.
+ * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
* @param[in] activeScanning
* Set to True if active-scanning is required. This is used to fetch the
* scan response from a peer if possible.
@@ -705,7 +706,7 @@
}
/**
- * Setup the scanInterval parameter for GAP scanning--i.e. observer mode.
+ * 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].
*
@@ -724,7 +725,7 @@
}
/**
- * Setup the scanWindow parameter for GAP scanning--i.e. observer mode.
+ * 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].
*
@@ -756,9 +757,9 @@
}
/**
- * Setup parameters for GAP scanning--i.e. observer mode.
+ * Set up parameters for GAP scanning (observer mode).
* @param[in] timeout
- * Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout.
+ * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
*
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
@@ -781,7 +782,7 @@
}
/**
- * Setup parameters for GAP scanning--i.e. observer mode.
+ * Set up parameters for GAP scanning (observer mode).
* @param[in] activeScanning
* Set to True if active-scanning is required. This is used to fetch the
* scan response from a peer if possible.
@@ -808,7 +809,7 @@
* effect.
*
* @param[in] callback
- * The application specific callback to be invoked upon
+ * 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.
*/
@@ -842,17 +843,17 @@
/**
* Initialize radio-notification events to be generated from the stack.
- * This API doesn't need to be called directly;
+ * This API doesn't need to be called directly.
*
* Radio Notification is a feature that enables ACTIVE and INACTIVE
* (nACTIVE) signals from the stack that notify the application when the
* radio is in use.
*
- * The ACTIVE signal is sent before the Radio Event starts. The nACTIVE
- * signal is sent at the end of the Radio Event. These signals can be used
+ * The ACTIVE signal is sent before the radio event starts. The nACTIVE
+ * signal is sent at the end of the radio event. These signals can be used
* by the application programmer to synchronize application logic with radio
* activity. For example, the ACTIVE signal can be used to shut off external
- * devices to manage peak current drawn during periods when the radio is on,
+ * 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.
*
* @return BLE_ERROR_NONE on successful initialization, otherwise an error code.
@@ -882,7 +883,7 @@
}
/**
- * Setup a particular, user-constructed set of advertisement parameters for
+ * Set up a particular, user-constructed set of advertisement parameters for
* the underlying stack. It would be uncommon for this API to be used
* directly; there are other APIs to tweak advertisement parameters
* individually.
@@ -894,13 +895,27 @@
/* Event callback handlers. */
public:
/**
- * Setup a callback for timeout events. Refer to TimeoutSource_t for
+ * Set up a callback for timeout events. Refer to TimeoutSource_t for
* possible event types.
+ * @note It is possible to unregister callbacks using onTimeout().detach(callback)
*/
- void onTimeout(TimeoutEventCallback_t callback) {timeoutCallback = callback;}
+ void onTimeout(TimeoutEventCallback_t callback) {
+ timeoutCallbackChain.add(callback);
+ }
+
+ /**
+ * @brief provide access to the callchain of timeout event callbacks
+ * It is possible to register callbacks using onTimeout().add(callback);
+ * It is possible to unregister callbacks using onTimeout().detach(callback)
+ * @return The timeout event callbacks chain
+ */
+ TimeoutEventCallbackChain_t& onTimeout() {
+ return timeoutCallbackChain;
+ }
/**
* Append to a chain of callbacks to be invoked upon GAP connection.
+ * @note It is possible to unregister callbacks using onConnection().detach(callback)
*/
void onConnection(ConnectionEventCallback_t callback) {connectionCallChain.add(callback);}
@@ -908,7 +923,18 @@
void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
/**
+ * @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;
+ }
+
+ /**
* Append to a chain of callbacks to be invoked upon GAP disconnection.
+ * @note It is possible to unregister callbacks using onDisconnection().detach(callback)
*/
void onDisconnection(DisconnectionEventCallback_t callback) {disconnectionCallChain.add(callback);}
@@ -916,24 +942,34 @@
void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
/**
+ * @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;
+ }
+
+ /**
* Set the application callback for radio-notification events.
*
* Radio Notification is a feature that enables ACTIVE and INACTIVE
* (nACTIVE) signals from the stack that notify the application when the
* radio is in use.
*
- * The ACTIVE signal is sent before the Radio Event starts. The nACTIVE
- * signal is sent at the end of the Radio Event. These signals can be used
+ * The ACTIVE signal is sent before the radio event starts. The nACTIVE
+ * signal is sent at the end of the radio event. These signals can be used
* by the application programmer to synchronize application logic with radio
* activity. For example, the ACTIVE signal can be used to shut off external
- * devices to manage peak current drawn during periods when the radio is on,
+ * devices, to manage peak current drawn during periods when the radio is on,
* or to trigger sensor data collection for transmission in the Radio Event.
*
* @param callback
* The application handler to be invoked in response to a radio
* ACTIVE/INACTIVE event.
*
- * or in the other version:
+ * Or in the other version:
*
* @param tptr
* Pointer to the object of a class defining the member callback
@@ -944,12 +980,10 @@
*/
void onRadioNotification(void (*callback)(bool param)) {
radioNotificationCallback.attach(callback);
- initRadioNotification();
}
template <typename T>
void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
radioNotificationCallback.attach(tptr, mptr);
- initRadioNotification();
}
protected:
@@ -960,7 +994,7 @@
_scanResponse(),
state(),
scanningActive(false),
- timeoutCallback(NULL),
+ timeoutCallbackChain(),
radioNotificationCallback(),
onAdvertisementReport(),
connectionCallChain(),
@@ -1006,8 +1040,8 @@
}
void processTimeoutEvent(TimeoutSource_t source) {
- if (timeoutCallback) {
- timeoutCallback(source);
+ if (timeoutCallbackChain) {
+ timeoutCallbackChain(source);
}
}
@@ -1021,14 +1055,14 @@
bool scanningActive;
protected:
- TimeoutEventCallback_t timeoutCallback;
- RadioNotificationEventCallback_t radioNotificationCallback;
- AdvertisementReportCallback_t onAdvertisementReport;
- CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t*> connectionCallChain;
- CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> disconnectionCallChain;
+ TimeoutEventCallbackChain_t timeoutCallbackChain;
+ RadioNotificationEventCallback_t radioNotificationCallback;
+ AdvertisementReportCallback_t onAdvertisementReport;
+ ConnectionEventCallbackChain_t connectionCallChain;
+ DisconnectionEventCallbackChain_t disconnectionCallChain;
private:
- /* disallow copy and assignment */
+ /* Disallow copy and assignment. */
Gap(const Gap &);
Gap& operator=(const Gap &);
};