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:
- 1131:73c11a85c6d6
- Parent:
- 1124:7ffed715734a
- Child:
- 1132:be7a1281777f
--- a/ble/Gap.h Tue Jan 12 19:47:52 2016 +0000 +++ b/ble/Gap.h Wed Apr 06 18:40:26 2016 +0100 @@ -17,14 +17,12 @@ #ifndef __GAP_H__ #define __GAP_H__ -#include "ble/BLEProtocol.h" #include "GapAdvertisingData.h" #include "GapAdvertisingParams.h" #include "GapScanningParams.h" #include "GapEvents.h" #include "CallChainOfFunctionPointersWithContext.h" #include "FunctionPointerWithContext.h" -#include "deprecate.h" /* Forward declarations for classes that will only be used for pointers or references in the following. */ class GapAdvertisingParams; @@ -32,44 +30,19 @@ class GapAdvertisingData; class Gap { - /* - * DEPRECATION ALERT: all of the APIs in this `public` block are deprecated. - * They have been relocated to the class BLEProtocol. - */ public: - /** - * Address-type for BLEProtocol addresses. - * - * @note: deprecated. Use BLEProtocol::AddressType_t instead. - */ - typedef BLEProtocol::AddressType_t AddressType_t; - - /** - * Address-type for BLEProtocol addresses. - * @note: deprecated. Use BLEProtocol::AddressType_t instead. - */ - typedef BLEProtocol::AddressType_t addr_type_t; + enum AddressType_t { + ADDR_TYPE_PUBLIC = 0, + ADDR_TYPE_RANDOM_STATIC, + ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE, + ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE + }; + typedef enum AddressType_t addr_type_t; /* @Note: Deprecated. Use AddressType_t instead. */ - /** - * Address-type for BLEProtocol addresses. - * \deprecated: Use BLEProtocol::AddressType_t instead. - * - * DEPRECATION ALERT: The following constants have been left in their - * deprecated state to transparenly support existing applications which may - * have used Gap::ADDR_TYPE_*. - */ - enum DeprecatedAddressType_t { - ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC, - ADDR_TYPE_RANDOM_STATIC = BLEProtocol::AddressType::RANDOM_STATIC, - ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_RESOLVABLE, - ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE - }; + 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. */ - 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: enum TimeoutSource_t { TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */ TIMEOUT_SRC_SECURITY_REQUEST = 0x01, /**< Security request timeout. */ @@ -93,56 +66,6 @@ CONN_INTERVAL_UNACCEPTABLE = 0x3B, }; - /** - * Enumeration for whitelist advertising policy filter modes. The possible - * filter modes were obtained from the Bluetooth Core Specification - * 4.2 (Vol. 6), Part B, Section 4.3.2. - * - * @experimental - */ - enum AdvertisingPolicyMode_t { - ADV_POLICY_IGNORE_WHITELIST = 0, - ADV_POLICY_FILTER_SCAN_REQS = 1, - ADV_POLICY_FILTER_CONN_REQS = 2, - ADV_POLICY_FILTER_ALL_REQS = 3, - }; - - /** - * Enumeration for whitelist scanning policy filter modes. The possible - * filter modes were obtained from the Bluetooth Core Specification - * 4.2 (Vol. 6), Part B, Section 4.3.3. - * - * @experimental - */ - enum ScanningPolicyMode_t { - SCAN_POLICY_IGNORE_WHITELIST = 0, - SCAN_POLICY_FILTER_ALL_ADV = 1, - }; - - /** - * Enumeration for the whitelist initiator policy fiter modes. The possible - * filter modes were obtained from the Bluetooth Core Specification - * 4.2 (vol. 6), Part B, Section 4.4.4. - * - * @experimental - */ - enum InitiatorPolicyMode_t { - INIT_POLICY_IGNORE_WHITELIST = 0, - INIT_POLICY_FILTER_ALL_ADV = 1, - }; - - /** - * Representation of a Bluetooth Low Enery Whitelist containing addresses. - * - * @experimental - */ - struct Whitelist_t { - BLEProtocol::Address_t *addresses; - uint8_t size; - uint8_t capacity; - }; - - /* Describes the current state of the device (more than one bit can be set). */ struct GapState_t { unsigned advertising : 1; /**< Peripheral is currently advertising. */ @@ -152,9 +75,9 @@ typedef uint16_t Handle_t; /* Type for connection handle. */ typedef struct { - uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/ - uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/ - uint16_t slaveLatency; /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/ + uint16_t 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; @@ -164,31 +87,31 @@ }; struct AdvertisementCallbackParams_t { - BLEProtocol::AddressBytes_t peerAddr; - int8_t rssi; - bool isScanResponse; - GapAdvertisingParams::AdvertisingType_t type; - uint8_t advertisingDataLen; - const uint8_t *advertisingData; + Address_t peerAddr; + int8_t rssi; + bool isScanResponse; + GapAdvertisingParams::AdvertisingType_t type; + uint8_t advertisingDataLen; + const uint8_t *advertisingData; }; typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> AdvertisementReportCallback_t; struct ConnectionCallbackParams_t { - Handle_t handle; - Role_t role; - BLEProtocol::AddressType_t peerAddrType; - BLEProtocol::AddressBytes_t peerAddr; - BLEProtocol::AddressType_t ownAddrType; - BLEProtocol::AddressBytes_t ownAddr; - const ConnectionParams_t *connectionParams; + Handle_t handle; + Role_t role; + AddressType_t peerAddrType; + Address_t peerAddr; + AddressType_t ownAddrType; + Address_t ownAddr; + const ConnectionParams_t *connectionParams; - ConnectionCallbackParams_t(Handle_t handleIn, - Role_t roleIn, - BLEProtocol::AddressType_t peerAddrTypeIn, - const uint8_t *peerAddrIn, - BLEProtocol::AddressType_t ownAddrTypeIn, - const uint8_t *ownAddrIn, - const ConnectionParams_t *connectionParamsIn) : + ConnectionCallbackParams_t(Handle_t handleIn, + Role_t roleIn, + AddressType_t peerAddrTypeIn, + const uint8_t *peerAddrIn, + AddressType_t ownAddrTypeIn, + const uint8_t *ownAddrIn, + const ConnectionParams_t *connectionParamsIn) : handle(handleIn), role(roleIn), peerAddrType(peerAddrTypeIn), @@ -224,24 +147,21 @@ typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t; typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t; - typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t; + typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t; typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t; - typedef FunctionPointerWithContext<const Gap *> GapShutdownCallback_t; - typedef CallChainOfFunctionPointersWithContext<const Gap *> GapShutdownCallbackChain_t; - /* * The following functions are meant to be overridden in the platform-specific sub-class. */ public: /** * 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. + * least significant byte first (LSB). Please refer to Address_t. * * @return BLE_ERROR_NONE on success. */ - virtual ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) { + virtual ble_error_t setAddress(AddressType_t type, const Address_t address) { /* avoid compiler warnings about unused variables */ (void)type; (void)address; @@ -254,7 +174,7 @@ * * @return BLE_ERROR_NONE on success. */ - virtual ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) { + virtual ble_error_t getAddress(AddressType_t *typeP, Address_t address) { /* Avoid compiler warnings about unused variables. */ (void)typeP; (void)address; @@ -263,16 +183,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. */ @@ -313,10 +231,10 @@ * 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, - const ConnectionParams_t *connectionParams, - const GapScanningParams *scanParams) { + virtual ble_error_t connect(const Address_t peerAddr, + Gap::AddressType_t peerAddrType, + const ConnectionParams_t *connectionParams, + const GapScanningParams *scanParams) { /* Avoid compiler warnings about unused variables. */ (void)peerAddr; (void)peerAddrType; @@ -327,23 +245,6 @@ } /** - * 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 - */ - ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr, - DeprecatedAddressType_t peerAddrType, - const ConnectionParams_t *connectionParams, - const GapScanningParams *scanParams) - __deprecated_message("Gap::DeprecatedAddressType_t is deprecated, use BLEProtocol::AddressType_t instead") { - return connect(peerAddr, (BLEProtocol::AddressType_t) peerAddrType, connectionParams, scanParams); - } - - /** * This call initiates the disconnection procedure, and its completion will * be communicated to the application with an invocation of the * disconnectionCallback. @@ -522,156 +423,6 @@ *countP = 0; /* Requesting action from porter(s): override this API if this capability is supported. */ } - /** - * @return Maximum size of the whitelist. - * - * @experimental - */ - virtual uint8_t getMaxWhitelistSize(void) const - { - return 0; - } - - /** - * 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 - * (on input) whitelist.capacity contains the maximum number - * of addresses to be returned. - * (on output) The populated whitelist with copies of the - * addresses in the implementation's whitelist. - * - * @return BLE_ERROR_NONE if the implementation's whitelist was successfully - * copied into the supplied reference. - * - * @experimental - */ - virtual ble_error_t getWhitelist(Whitelist_t &whitelist) const - { - (void) whitelist; - return BLE_ERROR_NOT_IMPLEMENTED; - } - - /** - * Set the internal whitelist to be used by the Link Layer when scanning, - * advertising or initiating a connection depending on the filter policies. - * - * @param[in] whitelist - * A reference to a whitelist containing the addresses to - * be added to the internal whitelist. - * - * @return BLE_ERROR_NONE if the implementation's whitelist was successfully - * populated with the addresses in the given whitelist. - * - * @note The whitelist must not contain addresses of type @ref - * BLEProtocol::AddressType_t::RANDOM_PRIVATE_NON_RESOLVABLE, this - * this will result in a @ref BLE_ERROR_INVALID_PARAM since the - * remote peer might change its private address at any time and it - * is not possible to resolve it. - * @note If the input whitelist is larger than @ref getMaxWhitelistSize() - * the @ref BLE_ERROR_PARAM_OUT_OF_RANGE is returned. - * - * @experimental - */ - virtual ble_error_t setWhitelist(const Whitelist_t &whitelist) - { - (void) whitelist; - return BLE_ERROR_NOT_IMPLEMENTED; - } - - /** - * Set the advertising policy filter mode to be used in the next call - * to startAdvertising(). - * - * @param[in] mode - * The new advertising policy filter mode. - * - * @return BLE_ERROR_NONE if the specified policy filter mode was set - * successfully. - * - * @experimental - */ - virtual ble_error_t setAdvertisingPolicyMode(AdvertisingPolicyMode_t mode) - { - (void) mode; - return BLE_ERROR_NOT_IMPLEMENTED; - } - - /** - * Set the scan policy filter mode to be used in the next call - * to startScan(). - * - * @param[in] mode - * The new scan policy filter mode. - * - * @return BLE_ERROR_NONE if the specified policy filter mode was set - * successfully. - * - * @experimental - */ - virtual ble_error_t setScanningPolicyMode(ScanningPolicyMode_t mode) - { - (void) mode; - return BLE_ERROR_NOT_IMPLEMENTED; - } - - /** - * Set the initiator policy filter mode to be used. - * - * @param[in] mode - * The new initiator policy filter mode. - * - * @return BLE_ERROR_NONE if the specified policy filter mode was set - * successfully. - * - * @experimental - */ - virtual ble_error_t setInitiatorPolicyMode(InitiatorPolicyMode_t mode) - { - (void) mode; - return BLE_ERROR_NOT_IMPLEMENTED; - } - - /** - * Get the advertising policy filter mode that will be used in the next - * call to startAdvertising(). - * - * @return The set advertising policy filter mode. - * - * @experimental - */ - virtual AdvertisingPolicyMode_t getAdvertisingPolicyMode(void) const - { - return ADV_POLICY_IGNORE_WHITELIST; - } - - /** - * Get the scan policy filter mode that will be used in the next - * call to startScan(). - * - * @return The set scan policy filter mode. - * - * @experimental - */ - virtual ScanningPolicyMode_t getScanningPolicyMode(void) const - { - return SCAN_POLICY_IGNORE_WHITELIST; - } - - /** - * Get the initiator policy filter mode that will be used. - * - * @return The set scan policy filter mode. - * - * @experimental - */ - virtual InitiatorPolicyMode_t getInitiatorPolicyMode(void) const - { - return INIT_POLICY_IGNORE_WHITELIST; - } - - protected: /* Override the following in the underlying adaptation layer to provide the functionality of scanning. */ virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams) { @@ -713,6 +464,11 @@ * 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 @@ -822,16 +578,6 @@ * @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. - * - * @note 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, - * COMPLETE_LIST_128BIT_SERVICE_IDS or LIST_128BIT_SOLICITATION_IDS the - * supplied value is appended to the values previously added to the - * payload. */ ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) { if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) { @@ -848,7 +594,8 @@ /** * Update a particular ADV field in the advertising payload (based on - * matching type). + * 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. @@ -857,7 +604,7 @@ * @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. + * 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) { @@ -1159,7 +906,7 @@ /** * @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) + * It is possible to unregister callbacks using onTimeout().detach(callback) * @return The timeout event callbacks chain */ TimeoutEventCallbackChain_t& onTimeout() { @@ -1178,10 +925,10 @@ /** * @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) + * It is possible to unregister callbacks using onConnection().detach(callback) * @return The connection event callbacks chain */ - ConnectionEventCallbackChain_t& onConnection() { + ConnectionEventCallbackChain_t& onconnection() { return connectionCallChain; } @@ -1197,7 +944,7 @@ /** * @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) + * It is possible to unregister callbacks using onDisconnection().detach(callback) * @return The disconnection event callbacks chain */ DisconnectionEventCallbackChain_t& onDisconnection() { @@ -1239,80 +986,6 @@ radioNotificationCallback.attach(tptr, mptr); } - /** - * Setup a callback to be invoked to notify the user application that the - * Gap instance is about to shutdown (possibly as a result of a call - * to BLE::shutdown()). - * - * @Note: It is possible to chain together multiple onShutdown callbacks - * (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 - * some object. - * - * @Note It is possible to unregister a callback using onShutdown().detach(callback) - */ - void onShutdown(const GapShutdownCallback_t& callback) { - shutdownCallChain.add(callback); - } - template <typename T> - void onShutdown(T *objPtr, void (T::*memberPtr)(void)) { - shutdownCallChain.add(objPtr, memberPtr); - } - - /** - * @brief provide access to the callchain of shutdown event callbacks - * It is possible to register callbacks using onShutdown().add(callback); - * It is possible to unregister callbacks using onShutdown().detach(callback) - * @return The shutdown event callbacks chain - */ - GapShutdownCallbackChain_t& onShutdown() { - return shutdownCallChain; - } - -public: - /** - * Notify all registered onShutdown callbacks that the Gap instance is - * about to be shutdown and clear all Gap state of the - * associated object. - * - * This function is meant to be overridden in the platform-specific - * sub-class. Nevertheless, the sub-class is only expected to reset its - * state and not the data held in Gap members. This shall be achieved by a - * call to Gap::reset() from the sub-class' reset() implementation. - * - * @return BLE_ERROR_NONE on success. - * - * @note: Currently a call to reset() does not reset the advertising and - * scan parameters to default values. - */ - virtual ble_error_t reset(void) { - /* Notify that the instance is about to shutdown */ - shutdownCallChain.call(this); - shutdownCallChain.clear(); - - /* Clear Gap state */ - state.advertising = 0; - state.connected = 0; - - /* Clear scanning state */ - scanningActive = false; - - /* Clear advertising and scanning data */ - _advPayload.clear(); - _scanResponse.clear(); - - /* Clear callbacks */ - timeoutCallbackChain.clear(); - connectionCallChain.clear(); - disconnectionCallChain.clear(); - radioNotificationCallback = NULL; - onAdvertisementReport = NULL; - - return BLE_ERROR_NONE; - } - protected: Gap() : _advParams(), @@ -1332,13 +1005,13 @@ /* Entry points for the underlying stack to report events back to the user. */ public: - void processConnectionEvent(Handle_t handle, - Role_t role, - BLEProtocol::AddressType_t peerAddrType, - const BLEProtocol::AddressBytes_t peerAddr, - BLEProtocol::AddressType_t ownAddrType, - const BLEProtocol::AddressBytes_t ownAddr, - const ConnectionParams_t *connectionParams) { + void processConnectionEvent(Handle_t handle, + Role_t role, + AddressType_t peerAddrType, + const Address_t peerAddr, + AddressType_t ownAddrType, + const Address_t ownAddr, + const ConnectionParams_t *connectionParams) { state.connected = 1; ConnectionCallbackParams_t callbackParams(handle, role, peerAddrType, peerAddr, ownAddrType, ownAddr, connectionParams); connectionCallChain.call(&callbackParams); @@ -1350,12 +1023,12 @@ disconnectionCallChain.call(&callbackParams); } - void processAdvertisementReport(const BLEProtocol::AddressBytes_t peerAddr, - int8_t rssi, - bool isScanResponse, + void processAdvertisementReport(const Address_t peerAddr, + int8_t rssi, + bool isScanResponse, GapAdvertisingParams::AdvertisingType_t type, - uint8_t advertisingDataLen, - const uint8_t *advertisingData) { + uint8_t advertisingDataLen, + const uint8_t *advertisingData) { AdvertisementCallbackParams_t params; memcpy(params.peerAddr, peerAddr, ADDR_LEN); params.rssi = rssi; @@ -1389,9 +1062,6 @@ DisconnectionEventCallbackChain_t disconnectionCallChain; private: - GapShutdownCallbackChain_t shutdownCallChain; - -private: /* Disallow copy and assignment. */ Gap(const Gap &); Gap& operator=(const Gap &);