Alex Cordonnier
High level Bluetooth Low Energy API and radio abstraction layer
Fork of
BLE_API
by 
Bluetooth Low Energy
Diff: ble/Gap.h
- Revision:
- 933:3ec277a0d780
- Parent:
- 923:ca1964e56ddf
- Child:
- 934:5e3acddfcd82
--- a/ble/Gap.h Thu Nov 26 12:52:05 2015 +0000
+++ b/ble/Gap.h Thu Nov 26 12:52:06 2015 +0000
@@ -24,7 +24,7 @@
#include "CallChainOfFunctionPointersWithContext.h"
#include "FunctionPointerWithContext.h"
-/* Forward declarations for classes that will only be used for pointers or references in the following. */
+/* Forward declarations for classes which 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 that is not
- * covered by this enumeration, 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 which is not
+ * covered by this enumeration, then 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,15 +140,10 @@
return (durationInMillis * 1000) / UNIT_1_25_MS;
}
- typedef FunctionPointerWithContext<TimeoutSource_t> TimeoutEventCallback_t;
- typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> TimeoutEventCallbackChain_t;
- 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 void (*TimeoutEventCallback_t)(TimeoutSource_t source);
+ typedef void (*ConnectionEventCallback_t)(const ConnectionCallbackParams_t *params);
+ typedef void (*DisconnectionEventCallback_t)(const DisconnectionCallbackParams_t *params);
typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
/*
@@ -157,7 +152,7 @@
public:
/**
* Set the BTLE MAC address and type. Please note that the address format is
- * least significant byte first (LSB). Please refer to Address_t.
+ * LSB (least significant byte first). Please refer to Address_t.
*
* @return BLE_ERROR_NONE on success.
*/
@@ -175,7 +170,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;
@@ -235,7 +230,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;
@@ -250,7 +245,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 */
@@ -266,15 +261,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
- * works reliably only for stacks that are limited to a single
+ * @note: this version of disconnect() doesn't take a connection handle. It
+ * will work reliably only for stacks which 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.
+ * altertive 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. */
@@ -293,7 +288,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. */
@@ -308,7 +303,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. */
@@ -316,12 +311,12 @@
/**
* 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
+ * 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
* 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.
@@ -340,7 +335,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. */
@@ -378,7 +373,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. */
@@ -390,7 +385,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. */
@@ -401,7 +396,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. */
@@ -416,7 +411,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;
@@ -435,8 +430,8 @@
*/
public:
/**
- * Returns the current GAP state of the device using a bitmask that
- * describes whether the device is advertising or connected.
+ * Returns the current GAP state of the device using a bitmask which
+ * describes whether the device is advertising and/or connected.
*/
GapState_t getState(void) const {
return state;
@@ -461,7 +456,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.
@@ -473,7 +468,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 needs to be updated accordingly.
+ * code depending on the old semantics would need to be updated accordingly.
*/
void setAdvertisingInterval(uint16_t interval) {
if (interval == 0) {
@@ -497,14 +492,17 @@
* 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 advertising payload to the underlying stack.
+ * initialized adv payload to the underlying stack.
+ *
+ * Note: This should be followed by a call to setAdvertisingPayload() or
+ * startAdvertising() before the update takes effect.
*/
void clearAdvertisingPayload(void) {
_advPayload.clear();
@@ -514,7 +512,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 is too
+ * as an additional 31 bytes if the advertising payload proves to be too
* small.
*
* @param[in] flags
@@ -534,7 +532,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 is too
+ * as an additional 31 bytes if the advertising payload proves to be too
* small.
*
* @param app
@@ -554,11 +552,12 @@
/**
* 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 is too
+ * as an additional 31 bytes if the advertising payload proves to be too
* small.
*
- * @param power
+ * @param app
* 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;
@@ -573,11 +572,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 is too small.
+ * advertising payload proves to be too small.
*
- * @param type The type describing the variable length data.
- * @param data Data bytes.
- * @param len Length of data.
+ * @param type The type which describes 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) {
@@ -597,14 +596,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 describing the variable length data.
- * @param[in] data Data bytes.
- * @param[in] len Length of data.
+ * @param[in] type The ADV type field which describes 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; otherwise, an appropriate error.
+ * a <type, len> match; else an appropriate error.
*/
ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@@ -620,7 +619,7 @@
}
/**
- * Set up a particular, user-constructed advertisement payload for the
+ * Setup 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).
*/
@@ -641,9 +640,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.
+ * @param[in] type The type which describes 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;
@@ -667,13 +666,13 @@
}
/**
- * Set up parameters for GAP scanning (observer mode).
+ * Setup parameters for GAP scanning--i.e. 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 the timeout.
+ * Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables 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.
@@ -706,7 +705,7 @@
}
/**
- * Set up the scanInterval parameter for GAP scanning (observer mode).
+ * Setup the scanInterval parameter for GAP scanning--i.e. observer mode.
* @param[in] interval
* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
*
@@ -725,7 +724,7 @@
}
/**
- * Set up the scanWindow parameter for GAP scanning (observer mode).
+ * Setup the scanWindow parameter for GAP scanning--i.e. observer mode.
* @param[in] window
* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
*
@@ -757,9 +756,9 @@
}
/**
- * Set up parameters for GAP scanning (observer mode).
+ * Setup parameters for GAP scanning--i.e. observer mode.
* @param[in] timeout
- * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
+ * Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout.
*
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
@@ -782,7 +781,7 @@
}
/**
- * Set up parameters for GAP scanning (observer mode).
+ * Setup parameters for GAP scanning--i.e. 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.
@@ -809,7 +808,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.
*/
@@ -843,17 +842,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.
@@ -883,7 +882,7 @@
}
/**
- * Set up a particular, user-constructed set of advertisement parameters for
+ * Setup 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.
@@ -895,16 +894,10 @@
/* Event callback handlers. */
public:
/**
- * Set up a callback for timeout events. Refer to TimeoutSource_t for
+ * Setup a callback for timeout events. Refer to TimeoutSource_t for
* possible event types.
*/
- void onTimeout(TimeoutEventCallback_t callback) {
- timeoutCallbackChain.add(callback);
- }
-
- TimeoutEventCallbackChain_t& onTimeout() {
- return timeoutCallbackChain;
- }
+ void onTimeout(TimeoutEventCallback_t callback) {timeoutCallback = callback;}
/**
* Append to a chain of callbacks to be invoked upon GAP connection.
@@ -914,10 +907,6 @@
template<typename T>
void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
- ConnectionEventCallbackChain_t& onconnection() {
- return connectionCallChain;
- }
-
/**
* Append to a chain of callbacks to be invoked upon GAP disconnection.
*/
@@ -926,10 +915,6 @@
template<typename T>
void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
- DisconnectionEventCallbackChain_t& onDisconnection() {
- return disconnectionCallChain;
- }
-
/**
* Set the application callback for radio-notification events.
*
@@ -937,18 +922,18 @@
* (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
@@ -959,14 +944,11 @@
*/
void onRadioNotification(void (*callback)(bool param)) {
radioNotificationCallback.attach(callback);
- // why does it start radio notification ? It is not even indicated in the
- // doc that it start the listening process
initRadioNotification();
}
template <typename T>
void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
radioNotificationCallback.attach(tptr, mptr);
- // why does it start radio notification ?
initRadioNotification();
}
@@ -978,7 +960,7 @@
_scanResponse(),
state(),
scanningActive(false),
- timeoutCallbackChain(),
+ timeoutCallback(NULL),
radioNotificationCallback(),
onAdvertisementReport(),
connectionCallChain(),
@@ -1024,8 +1006,8 @@
}
void processTimeoutEvent(TimeoutSource_t source) {
- if (timeoutCallbackChain) {
- timeoutCallbackChain(source);
+ if (timeoutCallback) {
+ timeoutCallback(source);
}
}
@@ -1039,14 +1021,14 @@
bool scanningActive;
protected:
- TimeoutEventCallbackChain_t timeoutCallbackChain;
- RadioNotificationEventCallback_t radioNotificationCallback;
- AdvertisementReportCallback_t onAdvertisementReport;
- ConnectionEventCallbackChain_t connectionCallChain;
- DisconnectionEventCallbackChain_t disconnectionCallChain;
+ TimeoutEventCallback_t timeoutCallback;
+ RadioNotificationEventCallback_t radioNotificationCallback;
+ AdvertisementReportCallback_t onAdvertisementReport;
+ CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t*> connectionCallChain;
+ CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> disconnectionCallChain;
private:
- /* Disallow copy and assignment. */
+ /* disallow copy and assignment */
Gap(const Gap &);
Gap& operator=(const Gap &);
};