Lancaster University's fork of the mbed BLE API. Lives on github, https://github.com/lancaster-university/BLE_API
Dependents: microbit-dal microbit-dal microbit-ble-open microbit-dal ... more
Fork of BLE_API by
Diff: ble/Gap.h
- Revision:
- 1042:21a86ac7f5b1
- Parent:
- 1036:7af23cdcfcac
- Child:
- 1048:efb29faf12fc
--- a/ble/Gap.h Thu Dec 10 09:15:05 2015 +0000 +++ b/ble/Gap.h Mon Jan 11 08:51:25 2016 +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; @@ -183,16 +178,14 @@ } /** - * @return Minimum Advertising interval in milliseconds for connectable - * undirected and connectable directed event types. + * @return Minimum Advertising interval in milliseconds. */ virtual uint16_t getMinAdvertisingInterval(void) const { return 0; /* Requesting action from porter(s): override this API if this capability is supported. */ } /** - * @return Minimum Advertising interval in milliseconds for scannable - * undirected and non-connectable undirected event types. + * @return Minimum Advertising interval in milliseconds for non-connectible mode. */ virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const { return 0; /* Requesting action from porter(s): override this API if this capability is supported. */ @@ -237,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; @@ -252,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 */ @@ -268,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. */ @@ -295,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. */ @@ -310,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. */ @@ -318,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. @@ -342,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. */ @@ -380,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. */ @@ -392,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. */ @@ -403,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. */ @@ -418,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; @@ -437,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; @@ -463,14 +456,19 @@ * 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. + * You should use the parallel API from Gap directly. A former call to + * ble.setAdvertisingInterval(...) should now be achieved using + * ble.gap().setAdvertisingInterval(...). + * * @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. + * code depending on the old semantics would need to be updated accordingly. */ void setAdvertisingInterval(uint16_t interval) { if (interval == 0) { @@ -494,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(); @@ -511,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 @@ -531,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 @@ -551,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; @@ -570,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) { @@ -594,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) { @@ -617,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). */ @@ -638,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; @@ -664,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. @@ -703,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]. * @@ -722,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]. * @@ -754,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(). @@ -779,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. @@ -806,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. */ @@ -840,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. @@ -880,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. @@ -892,27 +894,13 @@ /* 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. - * @note It is possible to unregister callbacks using onTimeout().detach(callback) */ - void onTimeout(TimeoutEventCallback_t callback) { - timeoutCallbackChain.add(callback); - } - - /** - * @brief provide access to the callchain of timeout event callbacks - * It is possible to register callbacks using onTimeout().add(callback); - * It is possible to unregister callbacks using onTimeout().detach(callback) - * @return The timeout event callbacks chain - */ - TimeoutEventCallbackChain_t& onTimeout() { - return timeoutCallbackChain; - } + void onTimeout(TimeoutEventCallback_t callback) {timeoutCallback = callback;} /** * 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);} @@ -920,18 +908,7 @@ 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);} @@ -939,34 +916,24 @@ 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 @@ -977,10 +944,12 @@ */ 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: @@ -991,7 +960,7 @@ _scanResponse(), state(), scanningActive(false), - timeoutCallbackChain(), + timeoutCallback(NULL), radioNotificationCallback(), onAdvertisementReport(), connectionCallChain(), @@ -1037,8 +1006,8 @@ } void processTimeoutEvent(TimeoutSource_t source) { - if (timeoutCallbackChain) { - timeoutCallbackChain(source); + if (timeoutCallback) { + timeoutCallback(source); } } @@ -1052,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 &); };