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:
- 1179:4ab722f8dca0
- Parent:
- 1160:c6c088802d38
- Child:
- 1180:e11b058d005e
--- a/ble/Gap.h Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/Gap.h Wed Apr 06 19:15:30 2016 +0100
@@ -40,24 +40,23 @@
/**
* Address-type for BLEProtocol addresses.
*
- * @deprecated Use BLEProtocol::AddressType_t instead.
+ * @note: deprecated. Use BLEProtocol::AddressType_t instead.
*/
typedef BLEProtocol::AddressType_t AddressType_t;
/**
* Address-type for BLEProtocol addresses.
- *
- * @deprecated Use BLEProtocol::AddressType_t instead.
+ * @note: deprecated. Use BLEProtocol::AddressType_t instead.
*/
typedef BLEProtocol::AddressType_t addr_type_t;
/**
* Address-type for BLEProtocol addresses.
+ * \deprecated: Use BLEProtocol::AddressType_t instead.
*
- * @deprecated Use BLEProtocol::AddressType_t instead. The following
- * constants have been left in their deprecated state to
- * transparenly support existing applications which may have
- * used Gap::ADDR_TYPE_*.
+ * DEPRECATION ALERT: The following constants have been left in their
+ * deprecated state to transparenly support existing applications which may
+ * have used Gap::ADDR_TYPE_*.
*/
enum DeprecatedAddressType_t {
ADDR_TYPE_PUBLIC = BLEProtocol::AddressType::PUBLIC,
@@ -66,27 +65,11 @@
ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE = BLEProtocol::AddressType::RANDOM_PRIVATE_NON_RESOLVABLE
};
- /**
- * Length (in octets) of the BLE MAC address.
- */
- static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN;
- /**
- * 48-bit address, LSB format.
- *
- * @deprecated Use BLEProtocol::AddressBytes_t instead.
- */
- typedef BLEProtocol::AddressBytes_t Address_t;
- /**
- * 48-bit address, LSB format.
- *
- * @deprecated Use BLEProtocol::AddressBytes_t instead.
- */
- typedef BLEProtocol::AddressBytes_t address_t;
+ static const unsigned ADDR_LEN = BLEProtocol::ADDR_LEN; /**< Length (in octets) of the BLE MAC address. */
+ typedef BLEProtocol::AddressBytes_t Address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::AddressBytes_t instead. */
+ typedef BLEProtocol::AddressBytes_t address_t; /**< 48-bit address, LSB format. @Note: Deprecated. Use BLEProtocol::AddressBytes_t instead. */
public:
- /**
- * Enumeration for timeout sources.
- */
enum TimeoutSource_t {
TIMEOUT_SRC_ADVERTISING = 0x00, /**< Advertising timeout. */
TIMEOUT_SRC_SECURITY_REQUEST = 0x01, /**< Security request timeout. */
@@ -154,94 +137,51 @@
* @experimental
*/
struct Whitelist_t {
- BLEProtocol::Address_t *addresses; /**< List of BLE addresses in the whitelist. */
- uint8_t size; /**< Total number of BLE addresses in this whitelist */
- uint8_t capacity; /**< Maximum number of BLE addresses that can be added to this whitelist. */
+ BLEProtocol::Address_t *addresses;
+ uint8_t size;
+ uint8_t capacity;
};
- /**
- * Describes the current state of the device (more than one bit can be set).
- */
+ /* Describes the current state of the device (more than one bit can be set). */
struct GapState_t {
unsigned advertising : 1; /**< Peripheral is currently advertising. */
unsigned connected : 1; /**< Peripheral is connected to a central. */
};
- /**
- * Type for connection handle.
- */
- typedef uint16_t Handle_t;
+ typedef uint16_t Handle_t; /* Type for connection handle. */
- /**
- * Structure containing GAP connection parameters. When in peripheral role
- * the connection parameters are suggestions. The choice of the connection
- * parameters is eventually up to the central.
- */
typedef struct {
- uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see BLE_GAP_CP_LIMITS.*/
- uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see BLE_GAP_CP_LIMITS.*/
- uint16_t slaveLatency; /**< Slave Latency in number of connection events, see BLE_GAP_CP_LIMITS.*/
- uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see BLE_GAP_CP_LIMITS.*/
+ uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
+ uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
+ uint16_t slaveLatency; /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
+ uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
} ConnectionParams_t;
- /**
- * Enumeration for the possible GAP roles of a BLE device.
- */
enum Role_t {
PERIPHERAL = 0x1, /**< Peripheral Role. */
CENTRAL = 0x2, /**< Central Role. */
};
- /**
- * Structure containing data and metadata of a scanned advertising packet.
- */
struct AdvertisementCallbackParams_t {
- BLEProtocol::AddressBytes_t peerAddr; /**< The peer's BLE address. */
- int8_t rssi; /**< The advertisement packet RSSI value. */
- bool isScanResponse; /**< Whether this packet is the response to a scan request. */
- GapAdvertisingParams::AdvertisingType_t type; /**< The type of advertisement. */
- uint8_t advertisingDataLen; /**< Length of the advertisement data. */
- const uint8_t *advertisingData; /**< Pointer to the advertisement packet's data. */
+ BLEProtocol::AddressBytes_t peerAddr;
+ int8_t rssi;
+ bool isScanResponse;
+ GapAdvertisingParams::AdvertisingType_t type;
+ uint8_t advertisingDataLen;
+ const uint8_t *advertisingData;
};
-
- /**
- * Type for the handlers of advertisement callback events. Refer to
- * Gap::startScan().
- */
typedef FunctionPointerWithContext<const AdvertisementCallbackParams_t *> AdvertisementReportCallback_t;
- /**
- * Encapsulates the parameters of a connection. This information is passed
- * to the registered handler of connection events. Refer to Gap::onConnection().
- */
struct ConnectionCallbackParams_t {
- Handle_t handle; /**< The ID for this connection */
- Role_t role; /**< This device's role in the connection */
- BLEProtocol::AddressType_t peerAddrType; /**< The peer's BLE address type */
- BLEProtocol::AddressBytes_t peerAddr; /**< The peer's BLE address */
- BLEProtocol::AddressType_t ownAddrType; /**< This device's BLE address type */
- BLEProtocol::AddressBytes_t ownAddr; /**< This devices's BLE address */
- const ConnectionParams_t *connectionParams; /**< The currently configured connection parameters */
+ Handle_t handle;
+ Role_t role;
+ BLEProtocol::AddressType_t peerAddrType;
+ BLEProtocol::AddressBytes_t peerAddr;
+ BLEProtocol::AddressType_t ownAddrType;
+ BLEProtocol::AddressBytes_t ownAddr;
+ const ConnectionParams_t *connectionParams;
- /**
- * Constructor for ConnectionCallbackParams_t.
- *
- * @param[in] handleIn
- * Value for ConnectionCallbackParams_t::handle
- * @param[in] roleIn
- * Value for ConnectionCallbackParams_t::role
- * @param[in] peerAddrTypeIn
- * Value for ConnectionCallbackParams_t::peerAddrType
- * @param[in] peerAddrIn
- * Value for ConnectionCallbackParams_t::peerAddr
- * @param[in] ownAddrTypeIn
- * Value for ConnectionCallbackParams_t::ownAddrType
- * @param[in] ownAddrIn
- * Value for ConnectionCallbackParams_t::ownAddr
- * @param[in] connectionParamsIn
- * Value for ConnectionCallbackParams_t::connectionParams
- */
ConnectionCallbackParams_t(Handle_t handleIn,
Role_t roleIn,
BLEProtocol::AddressType_t peerAddrTypeIn,
@@ -261,22 +201,10 @@
}
};
- /**
- * Structure that encapsulates information about a disconnection event.
- * Refer to Gap::onDisconnection().
- */
struct DisconnectionCallbackParams_t {
- Handle_t handle; /**< The ID of the connection that caused the disconnection event */
- DisconnectionReason_t reason; /**< The reason of the disconnection event */
+ Handle_t handle;
+ DisconnectionReason_t reason;
- /**
- * Constructor for DisconnectionCallbackParams_t.
- *
- * @param[in] handleIn
- * Value for DisconnectionCallbackParams_t::handle.
- * @param[in] reasonIn
- * Value for DisconnectionCallbackParams_t::reason.
- */
DisconnectionCallbackParams_t(Handle_t handleIn,
DisconnectionReason_t reasonIn) :
handle(handleIn),
@@ -285,63 +213,22 @@
};
static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
- /**
- * Helper function to convert from units of milliseconds to GAP duration
- * units.
- *
- * @param[in] durationInMillis
- * The duration in milliseconds.
- *
- * @return The duration in GAP duration units.
- */
static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
return (durationInMillis * 1000) / UNIT_1_25_MS;
}
- /**
- * Type for the registered callbacks added to the timeout event callchain.
- * Refer to Gap::onTimeout().
- */
typedef FunctionPointerWithContext<TimeoutSource_t> TimeoutEventCallback_t;
- /**
- * Type for the timeout event callchain. Refer to Gap::onTimeout().
- */
typedef CallChainOfFunctionPointersWithContext<TimeoutSource_t> TimeoutEventCallbackChain_t;
- /**
- * Type for the registered callbacks added to the connection event
- * callchain. Refer to Gap::onConnection().
- */
typedef FunctionPointerWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallback_t;
- /**
- * Type for the connection event callchain. Refer to Gap::onConnection().
- */
typedef CallChainOfFunctionPointersWithContext<const ConnectionCallbackParams_t *> ConnectionEventCallbackChain_t;
- /**
- * Type for the registered callbacks added to the disconnection event
- * callchain. Refer to Gap::onDisconnetion().
- */
typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
- /**
- * Type for the disconnection event callchain. Refer to Gap::onDisconnection().
- */
typedef CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallbackChain_t;
- /**
- * Type for the handlers of radio notification callback events. Refer to
- * Gap::onRadioNotification().
- */
typedef FunctionPointerWithContext<bool> RadioNotificationEventCallback_t;
- /**
- * Type for the handlers of shutdown callback events. Refer to
- * Gap::onShutdown().
- */
typedef FunctionPointerWithContext<const Gap *> GapShutdownCallback_t;
- /**
- * Type for the shutdown event callchain. Refer to Gap::onShutdown().
- */
typedef CallChainOfFunctionPointersWithContext<const Gap *> GapShutdownCallbackChain_t;
/*
@@ -352,11 +239,6 @@
* Set the BTLE MAC address and type. Please note that the address format is
* least significant byte first (LSB). Please refer to BLEProtocol::AddressBytes_t.
*
- * @param[in] type
- * The type of the BLE address to set.
- * @param[in] address
- * The BLE address to set.
- *
* @return BLE_ERROR_NONE on success.
*/
virtual ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
@@ -370,11 +252,6 @@
/**
* Fetch the BTLE MAC address and type.
*
- * @param[out] typeP
- * The current BLE address type.
- * @param[out] address
- * The current BLE address.
- *
* @return BLE_ERROR_NONE on success.
*/
virtual ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
@@ -386,44 +263,28 @@
}
/**
- * Get the minimum advertising interval in milliseconds for connectable
- * undirected and connectable directed event types supported by the
- * underlying BLE stack.
- *
* @return Minimum Advertising interval in milliseconds for connectable
- * undirected and connectable directed event types.
+ * undirected and connectable directed event types.
*/
virtual uint16_t getMinAdvertisingInterval(void) const {
return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
}
/**
- * Get the minimum advertising interval in milliseconds for scannable
- * undirected and non-connectable undirected even types supported by the
- * underlying BLE stack.
- *
* @return Minimum Advertising interval in milliseconds for scannable
- * undirected and non-connectable undirected event types.
+ * undirected and non-connectable undirected event types.
*/
virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const {
return 0; /* Requesting action from porter(s): override this API if this capability is supported. */
}
/**
- * Get the maximum advertising interval in milliseconds for all event types
- * supported by the underlying BLE stack.
- *
* @return Maximum Advertising interval in milliseconds.
*/
virtual uint16_t getMaxAdvertisingInterval(void) const {
return 0xFFFF; /* Requesting action from porter(s): override this API if this capability is supported. */
}
- /**
- * Stop advertising. The current advertising parameters remain in effect.
- *
- * @retval BLE_ERROR_NONE if successfully stopped advertising procedure.
- */
virtual ble_error_t stopAdvertising(void) {
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
}
@@ -440,18 +301,17 @@
/**
* Create a connection (GAP Link Establishment).
*
- * @param[in] peerAddr
- * 48-bit address, LSB format.
- * @param[in] peerAddrType
- * Address type of the peer.
- * @param[in] connectionParams
- * Connection parameters.
- * @param[in] scanParams
- * Paramters to be used while scanning for the peer.
- *
+ * @param peerAddr
+ * 48-bit address, LSB format.
+ * @param peerAddrType
+ * Address type of the peer.
+ * @param connectionParams
+ * Connection parameters.
+ * @param scanParams
+ * Paramters to be used while scanning for the peer.
* @return BLE_ERROR_NONE if connection establishment procedure is started
- * successfully. The connectionCallChain (if set) will be invoked upon
- * a connection event.
+ * successfully. The connectionCallChain (if set) will be invoked upon
+ * a connection event.
*/
virtual ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
BLEProtocol::AddressType_t peerAddrType,
@@ -469,12 +329,11 @@
/**
* Create a connection (GAP Link Establishment).
*
- * @deprecated This funtion overloads Gap::connect(const BLEProtocol::Address_t peerAddr,
- * BLEProtocol::AddressType_t peerAddrType,
- * const ConnectionParams_t *connectionParams,
- * const GapScanningParams *scanParams)
- * to maintain backward compatibility for change from Gap::AddressType_t to
- * BLEProtocol::AddressType_t.
+ * \deprecated: This funtion overloads Gap::connect(const BLEProtocol::Address_t peerAddr,
+ BLEProtocol::AddressType_t peerAddrType,
+ const ConnectionParams_t *connectionParams,
+ const GapScanningParams *scanParams)
+ * to maintain backward compatibility for change from Gap::AddressType_t to BLEProtocol::AddressType_t
*/
ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
DeprecatedAddressType_t peerAddrType,
@@ -489,12 +348,8 @@
* be communicated to the application with an invocation of the
* disconnectionCallback.
*
- * @param[in] reason
- * The reason for disconnection; to be sent back to the peer.
- * @param[in] connectionHandle
- * The handle of the connection to disconnect from.
- *
- * @return BLE_ERROR_NONE if disconnection was successful.
+ * @param reason
+ * The reason for disconnection; to be sent back to the peer.
*/
virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
/* avoid compiler warnings about unused variables */
@@ -509,15 +364,13 @@
* be communicated to the application with an invocation of the
* disconnectionCallback.
*
- * @param[in] reason
- * The reason for disconnection; to be sent back to the peer.
- *
- * @return BLE_ERROR_NONE if disconnection was successful.
+ * @param reason
+ * The reason for disconnection; to be sent back to the peer.
*
- * @deprecated This version of disconnect() doesn't take a connection handle. It
- * works reliably only for stacks that are limited to a single
- * connection. Use instead Gap::disconnect(Handle_t connectionHandle,
- * DisconnectionReason_t reason) instead.
+ * @note: This version of disconnect() doesn't take a connection handle. It
+ * works reliably only for stacks that are limited to a single
+ * connection. This API should be considered *deprecated* in favour of the
+ * alternative, which takes a connection handle. It will be dropped in the future.
*/
virtual ble_error_t disconnect(DisconnectionReason_t reason) {
/* Avoid compiler warnings about unused variables. */
@@ -536,7 +389,7 @@
* for this is owned by the caller.
*
* @return BLE_ERROR_NONE if the parameters were successfully filled into
- * the given structure pointed to by params.
+ * the given structure pointed to by params.
*/
virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
/* Avoid compiler warnings about unused variables. */
@@ -552,9 +405,6 @@
*
* @param[in] params
* The structure containing the desired parameters.
- *
- * @return BLE_ERROR_NONE if the preferred connection params were set
- * correctly.
*/
virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
/* Avoid compiler warnings about unused variables. */
@@ -564,18 +414,16 @@
}
/**
- * Update connection parameters. In the central role this will initiate a
- * Link Layer connection parameter update procedure. In the peripheral role,
- * this will send the corresponding L2CAP request and wait for the central
- * to perform the procedure.
+ * Update connection parameters.
+ * In the central role this will initiate a Link Layer connection parameter update procedure.
+ * In the peripheral role, this will send the corresponding L2CAP request and wait for
+ * the central to perform the procedure.
*
* @param[in] handle
* Connection Handle.
* @param[in] params
* Pointer to desired connection parameters. If NULL is provided on a peripheral role,
* the parameters in the PPCP characteristic of the GAP service will be used instead.
- *
- * @return BLE_ERROR_NONE if the connection parameters were updated correctly.
*/
virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) {
/* avoid compiler warnings about unused variables */
@@ -587,11 +435,8 @@
/**
* Set the device name characteristic in the GAP service.
- *
* @param[in] deviceName
* The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
- *
- * @return BLE_ERROR_NONE if the device name was set correctly.
*/
virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
/* Avoid compiler warnings about unused variables. */
@@ -602,25 +447,21 @@
/**
* Get the value of the device name characteristic in the GAP service.
- *
* @param[out] deviceName
* Pointer to an empty buffer where the UTF-8 *non NULL-
* terminated* string will be placed. Set this
* value to NULL in order to obtain the deviceName-length
* from the 'length' parameter.
*
- * @param[in,out] lengthP
+ * @param[in/out] lengthP
* (on input) Length of the buffer pointed to by deviceName;
* (on output) the complete device name length (without the
* null terminator).
*
- * @return BLE_ERROR_NONE if the device name was fetched correctly from the
- * underlying BLE stack.
- *
* @note If the device name is longer than the size of the supplied buffer,
- * length will return the complete device name length, and not the
- * number of bytes actually returned in deviceName. The application may
- * use this information to retry with a suitable buffer size.
+ * length will return the complete device name length, and not the
+ * number of bytes actually returned in deviceName. The application may
+ * use this information to retry with a suitable buffer size.
*/
virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
/* avoid compiler warnings about unused variables */
@@ -632,11 +473,8 @@
/**
* Set the appearance characteristic in the GAP service.
- *
* @param[in] appearance
* The new value for the device-appearance.
- *
- * @return BLE_ERROR_NONE if the new appearance was set correctly.
*/
virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
/* Avoid compiler warnings about unused variables. */
@@ -647,12 +485,8 @@
/**
* Get the appearance characteristic in the GAP service.
- *
* @param[out] appearance
- * The current device-appearance value.
- *
- * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
- * from the underlying BLE stack.
+ * The new value for the device-appearance.
*/
virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
/* Avoid compiler warnings about unused variables. */
@@ -663,12 +497,7 @@
/**
* Set the radio's transmit power.
- *
- * @param[in] txPower
- * Radio's transmit power in dBm.
- *
- * @return BLE_ERROR_NONE if the new radio's transmit power was set
- * correctly.
+ * @param[in] txPower Radio transmit power in dBm.
*/
virtual ble_error_t setTxPower(int8_t txPower) {
/* Avoid compiler warnings about unused variables. */
@@ -694,14 +523,8 @@
}
/**
- * Get the maximum size of the whitelist.
- *
* @return Maximum size of the whitelist.
*
- * @note If using mbed OS the size of the whitelist can be configured by
- * setting the YOTTA_CFG_WHITELIST_MAX_SIZE macro in your yotta
- * config file.
- *
* @experimental
*/
virtual uint8_t getMaxWhitelistSize(void) const
@@ -713,7 +536,7 @@
* Get the internal whitelist to be used by the Link Layer when scanning,
* advertising or initiating a connection depending on the filter policies.
*
- * @param[in,out] whitelist
+ * @param[in/out] whitelist
* (on input) whitelist.capacity contains the maximum number
* of addresses to be returned.
* (on output) The populated whitelist with copies of the
@@ -851,15 +674,6 @@
protected:
/* Override the following in the underlying adaptation layer to provide the functionality of scanning. */
-
- /**
- * Start scanning procedure in the underlying BLE stack.
- *
- * @param[in] scanningParams
- * The GAP scanning parameters.
- *
- * @return BLE_ERROR_NONE if the scan procedure started successfully.
- */
virtual ble_error_t startRadioScan(const GapScanningParams &scanningParams) {
(void)scanningParams;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@@ -870,10 +684,8 @@
*/
public:
/**
- * Get the current GAP state of the device using a bitmask that
+ * Returns the current GAP state of the device using a bitmask that
* describes whether the device is advertising or connected.
- *
- * @return The current GAP state of the device.
*/
GapState_t getState(void) const {
return state;
@@ -881,17 +693,12 @@
/**
* Set the GAP advertising mode to use for this device.
- *
- * @param[in] advType
- * The new type of the advertising packets.
*/
void setAdvertisingType(GapAdvertisingParams::AdvertisingType_t advType) {
_advParams.setAdvertisingType(advType);
}
/**
- * Set the advertising interval.
- *
* @param[in] interval
* Advertising interval in units of milliseconds. Advertising
* is disabled if interval is 0. If interval is smaller than
@@ -902,15 +709,15 @@
* This field must be set to 0 if connectionMode is equal
* to ADV_CONNECTABLE_DIRECTED.
*
- * @note Decreasing this value will allow central devices to detect a
- * peripheral faster, at the expense of more power being used by the radio
- * due to the higher data transmit rate.
+ * @note: Decreasing this value will allow central devices to detect a
+ * peripheral faster, at the expense of more power being used by the radio
+ * due to the higher data transmit rate.
*
- * @note [WARNING] This API previously used 0.625ms as the unit for its
- * @p interval argument. That required an explicit conversion from
- * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
- * no longer required as the new units are milliseconds. Any application
- * code depending on the old semantics needs to be updated accordingly.
+ * @Note: [WARNING] This API previously used 0.625ms as the unit for its
+ * 'interval' argument. That required an explicit conversion from
+ * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
+ * no longer required as the new units are milliseconds. Any application
+ * code depending on the old semantics needs to be updated accordingly.
*/
void setAdvertisingInterval(uint16_t interval) {
if (interval == 0) {
@@ -922,9 +729,6 @@
}
/**
- * Set the advertising timeout. The length of time to advertise for before
- * a timeout event is generated.
- *
* @param[in] timeout
* Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
* and 16383). Use 0 to disable the advertising timeout.
@@ -935,8 +739,6 @@
/**
* Start advertising.
- *
- * @return BLE_ERROR_NONE if the device started advertising successfully.
*/
ble_error_t startAdvertising(void) {
setAdvertisingData(); /* Update the underlying stack. */
@@ -963,9 +765,6 @@
* The flags to be added. Please refer to
* GapAdvertisingData::Flags for valid flags. Multiple
* flags may be specified in combination.
- *
- * @return BLE_ERROR_NONE if the data was successfully added to the
- * advertising payload.
*/
ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
ble_error_t rc;
@@ -982,11 +781,8 @@
* as an additional 31 bytes if the advertising payload is too
* small.
*
- * @param[in] app
- * The appearance of the peripheral.
- *
- * @return BLE_ERROR_NONE if the data was successfully added to the
- * advertising payload.
+ * @param app
+ * The appearance of the peripheral.
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
setAppearance(app);
@@ -1005,11 +801,8 @@
* as an additional 31 bytes if the advertising payload is too
* small.
*
- * @param[in] power
- * The max transmit power to be used by the controller (in dBm).
- *
- * @return BLE_ERROR_NONE if the data was successfully added to the
- * advertising payload.
+ * @param power
+ * The max transmit power to be used by the controller (in dBm).
*/
ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
ble_error_t rc;
@@ -1026,12 +819,9 @@
* The SCAN_RESPONSE message may be used as an additional 31 bytes if the
* advertising payload is too small.
*
- * @param[in] type
- * The type describing the variable length data.
- * @param[in] data
- * Data bytes.
- * @param[in] len
- * Length of data.
+ * @param type The type describing the variable length data.
+ * @param data Data bytes.
+ * @param len Length of data.
*
* @return BLE_ERROR_NONE if the advertisement payload was updated based on
* matching AD type; otherwise, an appropriate error.
@@ -1060,14 +850,11 @@
* Update a particular ADV field in the advertising payload (based on
* matching type).
*
- * @param[in] type
- * The ADV type field describing the variable length data.
- * @param[in] data
- * Data bytes.
- * @param[in] len
- * Length of data.
+ * @param[in] type The ADV type field describing the variable length data.
+ * @param[in] data Data bytes.
+ * @param[in] len Length of data.
*
- * @note If advertisements are enabled, then the update will take effect immediately.
+ * @note: If advertisements are enabled, then the update will take effect immediately.
*
* @return BLE_ERROR_NONE if the advertisement payload was updated based on
* matching AD type; otherwise, an appropriate error.
@@ -1088,15 +875,7 @@
/**
* Set up a particular, user-constructed advertisement payload for the
* underlying stack. It would be uncommon for this API to be used directly;
- * there are other APIs to build an advertisement payload (refer to
- * Gap::accumulateAdvertisingPayload()).
- *
- * @param[in] payload
- * A reference to a user constructed advertisement
- * payload.
- *
- * @return BLE_ERROR_NONE if the advertisement payload was successfully
- * set.
+ * there are other APIs to build an advertisement payload (see above).
*/
ble_error_t setAdvertisingPayload(const GapAdvertisingData &payload) {
_advPayload = payload;
@@ -1104,11 +883,8 @@
}
/**
- * Get a reference to the advertising payload.
- *
- * @return Read back advertising data.
- *
- * @note Useful for storing and restoring payload.
+ * @return Read back advertising data. Useful for storing and
+ * restoring payload.
*/
const GapAdvertisingData &getAdvertisingPayload(void) const {
return _advPayload;
@@ -1118,15 +894,9 @@
* Accumulate a variable length byte-stream as an AD structure in the
* scanResponse payload.
*
- * @param[in] type
- * The type describing the variable length data.
- * @param[in] data
- * Data bytes.
- * @param[in] len
- * Length of data.
- *
- * @return BLE_ERROR_NONE if the data was successfully added to the scan
- * response payload.
+ * @param[in] type The type describing the variable length data.
+ * @param[in] data Data bytes.
+ * @param[in] len Length of data.
*/
ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
ble_error_t rc;
@@ -1139,10 +909,10 @@
/**
* Reset any scan response prepared from prior calls to
- * Gap::accumulateScanResponse().
+ * accumulateScanResponse().
*
- * @note This should be followed by a call to Gap::setAdvertisingPayload() or
- * Gap::startAdvertising() before the update takes effect.
+ * Note: This should be followed by a call to setAdvertisingPayload() or
+ * startAdvertising() before the update takes effect.
*/
void clearScanResponse(void) {
_scanResponse.clear();
@@ -1151,7 +921,6 @@
/**
* Set up parameters for GAP scanning (observer mode).
- *
* @param[in] interval
* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
* @param[in] window
@@ -1162,19 +931,17 @@
* Set to True if active-scanning is required. This is used to fetch the
* scan response from a peer if possible.
*
- * @return BLE_ERROR_NONE if the scan parameters were correctly set.
+ * The scanning window divided by the interval determines the duty cycle for
+ * scanning. For example, if the interval is 100ms and the window is 10ms,
+ * then the controller will scan for 10 percent of the time. It is possible
+ * to have the interval and window set to the same value. In this case,
+ * scanning is continuous, with a change of scanning frequency once every
+ * interval.
*
- * @note The scanning window divided by the interval determines the duty cycle for
- * scanning. For example, if the interval is 100ms and the window is 10ms,
- * then the controller will scan for 10 percent of the time. It is possible
- * to have the interval and window set to the same value. In this case,
- * scanning is continuous, with a change of scanning frequency once every
- * interval.
+ * Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
*
- * @note Once the scanning parameters have been configured, scanning can be
- * enabled by using startScan().
- *
- * @note The scan interval and window are recommendations to the BLE stack.
+ * @Note: The scan interval and window are recommendations to the BLE stack.
*/
ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
@@ -1193,21 +960,18 @@
/**
* Set up the scanInterval parameter for GAP scanning (observer mode).
- *
* @param[in] interval
* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
*
- * @return BLE_ERROR_NONE if the scan interval was correctly set.
+ * The scanning window divided by the interval determines the duty cycle for
+ * scanning. For example, if the interval is 100ms and the window is 10ms,
+ * then the controller will scan for 10 percent of the time. It is possible
+ * to have the interval and window set to the same value. In this case,
+ * scanning is continuous, with a change of scanning frequency once every
+ * interval.
*
- * @note The scanning window divided by the interval determines the duty cycle for
- * scanning. For example, if the interval is 100ms and the window is 10ms,
- * then the controller will scan for 10 percent of the time. It is possible
- * to have the interval and window set to the same value. In this case,
- * scanning is continuous, with a change of scanning frequency once every
- * interval.
- *
- * @note Once the scanning parameters have been configured, scanning can be
- * enabled by using startScan().
+ * Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
*/
ble_error_t setScanInterval(uint16_t interval) {
return _scanningParams.setInterval(interval);
@@ -1215,24 +979,21 @@
/**
* Set up the scanWindow parameter for GAP scanning (observer mode).
- *
* @param[in] window
* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
*
- * @return BLE_ERROR_NONE if the scan window was correctly set.
+ * The scanning window divided by the interval determines the duty cycle for
+ * scanning. For example, if the interval is 100ms and the window is 10ms,
+ * then the controller will scan for 10 percent of the time. It is possible
+ * to have the interval and window set to the same value. In this case,
+ * scanning is continuous, with a change of scanning frequency once every
+ * interval.
*
- * @note The scanning window divided by the interval determines the duty cycle for
- * scanning. For example, if the interval is 100ms and the window is 10ms,
- * then the controller will scan for 10 percent of the time. It is possible
- * to have the interval and window set to the same value. In this case,
- * scanning is continuous, with a change of scanning frequency once every
- * interval.
+ * Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
*
- * @note Once the scanning parameters have been configured, scanning can be
- * enabled by using startScan().
- *
- * @note If scanning is already active, the updated value of scanWindow will be
- * propagated to the underlying BLE stack.
+ * If scanning is already active, the updated value of scanWindow will be
+ * propagated to the underlying BLE stack.
*/
ble_error_t setScanWindow(uint16_t window) {
ble_error_t rc;
@@ -1250,17 +1011,14 @@
/**
* Set up parameters for GAP scanning (observer mode).
- *
* @param[in] timeout
* Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
*
- * @return BLE_ERROR_NONE if the scan timeout was correctly set.
+ * Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
*
- * @note Once the scanning parameters have been configured, scanning can be
- * enabled by using startScan().
- *
- * @note If scanning is already active, the updated value of scanTimeout will be
- * propagated to the underlying BLE stack.
+ * If scanning is already active, the updated value of scanTimeout will be
+ * propagated to the underlying BLE stack.
*/
ble_error_t setScanTimeout(uint16_t timeout) {
ble_error_t rc;
@@ -1277,19 +1035,16 @@
}
/**
- * Modify the active scanning parameter for GAP scanning (observer mode).
- * This is used to fetch the scan response from a peer if possible.
- *
+ * Set up parameters for GAP scanning (observer mode).
* @param[in] activeScanning
- * Set to True if active-scanning is required.
+ * Set to True if active-scanning is required. This is used to fetch the
+ * scan response from a peer if possible.
*
- * @return BLE_ERROR_NONE if active scanning was successfully set.
+ * Once the scanning parameters have been configured, scanning can be
+ * enabled by using startScan().
*
- * @note Once the scanning parameters have been configured, scanning can be
- * enabled by using startScan().
- *
- * @note If scanning is already in progress, then active-scanning will be enabled
- * for the underlying BLE stack.
+ * If scanning is already in progress, then active-scanning will be enabled
+ * for the underlying BLE stack.
*/
ble_error_t setActiveScanning(bool activeScanning) {
_scanningParams.setActiveScanning(activeScanning);
@@ -1310,9 +1065,6 @@
* The application-specific callback to be invoked upon
* receiving every advertisement report. This can be passed in
* as NULL, in which case scanning may not be enabled at all.
- *
- * @return BLE_ERROR_NONE if the device successfully started the scan
- * procedure.
*/
ble_error_t startScan(void (*callback)(const AdvertisementCallbackParams_t *params)) {
ble_error_t err = BLE_ERROR_NONE;
@@ -1327,19 +1079,7 @@
}
/**
- * Same as Gap::startScan(), but allows the possibility to add an object
- * reference and member function as handler for advertisement event
- * callbacks.
- *
- * @param[in] object
- * Pointer to the object of a class defining the member callback
- * function (@p callbackMember).
- * @param[in] callbackMember
- * The member callback (within the context of an object) to be
- * invoked.
- *
- * @return BLE_ERROR_NONE if the device successfully started the scan
- * procedure.
+ * Same as above, but this takes an (object, method) pair for a callback.
*/
template<typename T>
ble_error_t startScan(T *object, void (T::*callbackMember)(const AdvertisementCallbackParams_t *params)) {
@@ -1376,58 +1116,21 @@
}
private:
- /**
- * Helper function used to set the advertising data in the underlying BLE stack.
- *
- * @return BLE_ERROR_NONE if the advertising data was successfully set.
- */
ble_error_t setAdvertisingData(void) {
return setAdvertisingData(_advPayload, _scanResponse);
}
private:
- /**
- * Functionality that is BLE stack-dependent and must be implemented by the
- * ported. This is a helper function to set the advertising data in the
- * BLE stack.
- *
- * @param[in] advData
- * The new advertising data.
- * @param[in] scanResponse
- * The new scan response data.
- *
- * @return BLE_ERROR_NONE if the advertising data was set successfully.
- */
virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0;
-
- /**
- * Functionality that is BLE stack-dependent and must be implemented by the
- * ported. This is a helper function to start the advertising procedure in
- * the underlying BLE stack.
- *
- * @param[in]
- * The advertising parameters.
- *
- * @return BLE_ERROR_NONE if the advertising procedure was successfully
- * started.
- */
virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
public:
/**
- * Accessor to read back currently active advertising parameters.
- *
- * @return A reference to the current advertising parameters.
+ * Accessors to read back currently active advertising params.
*/
GapAdvertisingParams &getAdvertisingParams(void) {
return _advParams;
}
-
- /**
- * A const alternative to Gap::getAdvertisingParams().
- *
- * @return A const reference to the current advertising parameters.
- */
const GapAdvertisingParams &getAdvertisingParams(void) const {
return _advParams;
}
@@ -1437,9 +1140,6 @@
* the underlying stack. It would be uncommon for this API to be used
* directly; there are other APIs to tweak advertisement parameters
* individually.
- *
- * @param[in] newParams
- * The new advertising parameters.
*/
void setAdvertisingParams(const GapAdvertisingParams &newParams) {
_advParams = newParams;
@@ -1450,24 +1150,17 @@
/**
* Set up a callback for timeout events. Refer to TimeoutSource_t for
* possible event types.
- *
- * @param[in] callback
- * Event handler being registered.
- *
- * @note It is possible to unregister callbacks using onTimeout().detach(callback).
+ * @note It is possible to unregister callbacks using onTimeout().detach(callback)
*/
void onTimeout(TimeoutEventCallback_t callback) {
timeoutCallbackChain.add(callback);
}
/**
- * @brief Provide access to the callchain of timeout event callbacks.
- *
- * @note It is possible to register callbacks using onTimeout().add(callback).
- *
- * @note It is possible to unregister callbacks using onTimeout().detach(callback).
- *
- * @return A reference to the timeout event callbacks chain.
+ * @brief provide access to the callchain of timeout event callbacks
+ * It is possible to register callbacks using onTimeout().add(callback);
+ * It is possible to unregister callbacks using onTimeout().detach(callback)
+ * @return The timeout event callbacks chain
*/
TimeoutEventCallbackChain_t& onTimeout() {
return timeoutCallbackChain;
@@ -1475,41 +1168,18 @@
/**
* Append to a chain of callbacks to be invoked upon GAP connection.
- *
- * @param[in] callback
- * Event handler being registered.
- *
* @note It is possible to unregister callbacks using onConnection().detach(callback)
*/
- void onConnection(ConnectionEventCallback_t callback) {
- connectionCallChain.add(callback);
- }
+ void onConnection(ConnectionEventCallback_t callback) {connectionCallChain.add(callback);}
+
+ template<typename T>
+ void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {connectionCallChain.add(tptr, mptr);}
/**
- * Same as Gap::onConnection(), but allows the possibility to add an object
- * reference and member function as handler for connection event
- * callbacks.
- *
- * @param[in] tptr
- * Pointer to the object of a class defining the member callback
- * function (@p mptr).
- * @param[in] mptr
- * The member callback (within the context of an object) to be
- * invoked.
- */
- template<typename T>
- void onConnection(T *tptr, void (T::*mptr)(const ConnectionCallbackParams_t*)) {
- connectionCallChain.add(tptr, mptr);
- }
-
- /**
- * @brief Provide access to the callchain of connection event callbacks.
- *
- * @return A reference to the connection event callbacks chain.
- *
- * @note It is possible to register callbacks using onConnection().add(callback).
- *
- * @note It is possible to unregister callbacks using onConnection().detach(callback).
+ * @brief provide access to the callchain of connection event callbacks
+ * It is possible to register callbacks using onConnection().add(callback);
+ * It is possible to unregister callbacks using onConnection().detach(callback)
+ * @return The connection event callbacks chain
*/
ConnectionEventCallbackChain_t& onConnection() {
return connectionCallChain;
@@ -1517,41 +1187,18 @@
/**
* Append to a chain of callbacks to be invoked upon GAP disconnection.
- *
- * @param[in] callback
- Event handler being registered.
- *
- * @note It is possible to unregister callbacks using onDisconnection().detach(callback).
+ * @note It is possible to unregister callbacks using onDisconnection().detach(callback)
*/
- void onDisconnection(DisconnectionEventCallback_t callback) {
- disconnectionCallChain.add(callback);
- }
+ void onDisconnection(DisconnectionEventCallback_t callback) {disconnectionCallChain.add(callback);}
+
+ template<typename T>
+ void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {disconnectionCallChain.add(tptr, mptr);}
/**
- * Same as Gap::onDisconnection(), but allows the possibility to add an object
- * reference and member function as handler for disconnection event
- * callbacks.
- *
- * @param[in] tptr
- * Pointer to the object of a class defining the member callback
- * function (@p mptr).
- * @param[in] mptr
- * The member callback (within the context of an object) to be
- * invoked.
- */
- template<typename T>
- void onDisconnection(T *tptr, void (T::*mptr)(const DisconnectionCallbackParams_t*)) {
- disconnectionCallChain.add(tptr, mptr);
- }
-
- /**
- * @brief Provide access to the callchain of disconnection event callbacks.
- *
- * @return A reference to the disconnection event callback chain.
- *
- * @note It is possible to register callbacks using onDisconnection().add(callback).
- *
- * @note It is possible to unregister callbacks using onDisconnection().detach(callback).
+ * @brief provide access to the callchain of disconnection event callbacks
+ * It is possible to register callbacks using onDisconnection().add(callback);
+ * It is possible to unregister callbacks using onDisconnection().detach(callback)
+ * @return The disconnection event callbacks chain
*/
DisconnectionEventCallbackChain_t& onDisconnection() {
return disconnectionCallChain;
@@ -1571,26 +1218,22 @@
* devices, to manage peak current drawn during periods when the radio is on,
* or to trigger sensor data collection for transmission in the Radio Event.
*
- * @param[in] callback
- * The application handler to be invoked in response to a radio
- * ACTIVE/INACTIVE event.
+ * @param callback
+ * The application handler to be invoked in response to a radio
+ * ACTIVE/INACTIVE event.
+ *
+ * Or in the other version:
+ *
+ * @param tptr
+ * Pointer to the object of a class defining the member callback
+ * function (mptr).
+ * @param mptr
+ * The member callback (within the context of an object) to be
+ * invoked in response to a radio ACTIVE/INACTIVE event.
*/
void onRadioNotification(void (*callback)(bool param)) {
radioNotificationCallback.attach(callback);
}
-
- /**
- * Same as Gap::onRadioNotification(), but allows the posibility to
- * register an object reference and member function as handler for radio
- * notification events.
- *
- * @param[in] tptr
- * Pointer to the object of a class defining the member callback
- * function (@p mptr).
- * @param[in] mptr
- * The member callback (within the context of an object) to be
- * invoked in response to a radio ACTIVE/INACTIVE event.
- */
template <typename T>
void onRadioNotification(T *tptr, void (T::*mptr)(bool)) {
radioNotificationCallback.attach(tptr, mptr);
@@ -1601,48 +1244,28 @@
* Gap instance is about to shutdown (possibly as a result of a call
* to BLE::shutdown()).
*
- * @param[in] callback
- * The handler that is being registered to be notified of
- * shutdown events.
- *
- * @note It is possible to chain together multiple onShutdown callbacks
+ * @Note: It is possible to chain together multiple onShutdown callbacks
* (potentially from different modules of an application) to be notified
* before the Gap instance is shutdown.
*
- * @note It is also possible to set up a callback into a member function of
+ * @Note: It is also possible to set up a callback into a member function of
* some object.
*
- * @note It is possible to unregister a callback using onShutdown().detach(callback)
+ * @Note It is possible to unregister a callback using onShutdown().detach(callback)
*/
void onShutdown(const GapShutdownCallback_t& callback) {
shutdownCallChain.add(callback);
}
-
- /**
- * Same as Gap::onShutdown(), but allows the posibility to
- * register an object reference and member function as handler for shutdown
- * events.
- *
- * @param[in] objPtr
- * Pointer to the object of a class defining the member callback
- * function (@p memberPtr).
- * @param[in] memberPtr
- * The member callback (within the context of an object) to be
- * invoked in response to a shutdown event.
- */
template <typename T>
void onShutdown(T *objPtr, void (T::*memberPtr)(void)) {
shutdownCallChain.add(objPtr, memberPtr);
}
/**
- * @brief Provide access to the callchain of shutdown event callbacks.
- *
- * @return A reference to the shutdown event callback chain.
- *
- * @note It is possible to register callbacks using onShutdown().add(callback).
- *
- * @note It is possible to unregister callbacks using onShutdown().detach(callback).
+ * @brief provide access to the callchain of shutdown event callbacks
+ * It is possible to register callbacks using onShutdown().add(callback);
+ * It is possible to unregister callbacks using onShutdown().detach(callback)
+ * @return The shutdown event callbacks chain
*/
GapShutdownCallbackChain_t& onShutdown() {
return shutdownCallChain;
@@ -1661,7 +1284,7 @@
*
* @return BLE_ERROR_NONE on success.
*
- * @note Currently a call to reset() does not reset the advertising and
+ * @note: Currently a call to reset() does not reset the advertising and
* scan parameters to default values.
*/
virtual ble_error_t reset(void) {
@@ -1691,9 +1314,6 @@
}
protected:
- /**
- * Construct a Gap instance.
- */
Gap() :
_advParams(),
_advPayload(),
@@ -1712,26 +1332,6 @@
/* Entry points for the underlying stack to report events back to the user. */
public:
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of a connection event. This function is meant to be called from the
- * BLE stack specific implementation when a connection event occurs.
- *
- * @param[in] handle
- * The ID of the connection that generated the event.
- * @param[in] role
- * The role of this BLE device in the connection.
- * @param[in] peerAddrType
- * The peer's BLE address type.
- * @param[in] peerAddr
- * The peer's BLE address.
- * @param[in] ownAddrType
- * This device's BLE address type.
- * @param[in] ownAddr
- * This device's BLE address.
- * @param[in] connectionParams
- * The parameters configured for this connection.
- */
void processConnectionEvent(Handle_t handle,
Role_t role,
BLEProtocol::AddressType_t peerAddrType,
@@ -1744,40 +1344,12 @@
connectionCallChain.call(&callbackParams);
}
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of a disconnection event. This function is meant to be called from the
- * BLE stack specific implementation when a disconnection event occurs.
- *
- * @param[in] handle
- * The ID of the connection that generated the event.
- * @param[in] reason
- * The reason for disconnection.
- */
void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
state.connected = 0;
DisconnectionCallbackParams_t callbackParams(handle, reason);
disconnectionCallChain.call(&callbackParams);
}
- /**
- * Helper function that notifies the registered handler of a scanned
- * advertisement packet. This function is meant to be called from the
- * BLE stack specific implementation when a such event occurs.
- *
- * @param[in] peerAddr
- * The peer's BLE address.
- * @param[in] rssi
- * The advertisement packet RSSI value.
- * @param[in] isScanReponse
- * Whether this packet is the response to a scan request.
- * @param[in] type
- * The type of advertisement.
- * @param[in] advertisingDataLen
- * Length of the advertisement data.
- * @param[in] advertisingData
- * Pointer to the advertisement packet's data.
- */
void processAdvertisementReport(const BLEProtocol::AddressBytes_t peerAddr,
int8_t rssi,
bool isScanResponse,
@@ -1794,79 +1366,33 @@
onAdvertisementReport.call(¶ms);
}
- /**
- * Helper function that notifies all registered handlers of an occurrence
- * of a timeout event. This function is meant to be called from the
- * BLE stack specific implementation when a timeout event occurs.
- *
- * @param[in] source
- * The source of the timout event.
- */
void processTimeoutEvent(TimeoutSource_t source) {
+ if (source == TIMEOUT_SRC_ADVERTISING) {
+ /* Update gap state if the source is an advertising timeout */
+ state.advertising = 0;
+ }
if (timeoutCallbackChain) {
timeoutCallbackChain(source);
}
}
protected:
- /**
- * Currently set advertising parameters.
- */
GapAdvertisingParams _advParams;
- /**
- * Currently set advertising data.
- */
GapAdvertisingData _advPayload;
- /**
- * Currently set scanning parameters.
- */
GapScanningParams _scanningParams;
- /**
- * Currently set scan response data.
- */
GapAdvertisingData _scanResponse;
- /**
- * The current GAP state.
- */
GapState_t state;
- /**
- * Whether active scanning is set. This is used to fetch the scan response
- * from a peer if possible.
- */
bool scanningActive;
protected:
- /**
- * Callchain containing all registered callback handlers for timeout
- * events.
- */
TimeoutEventCallbackChain_t timeoutCallbackChain;
- /**
- * The registered callback handler for radio notification events.
- */
RadioNotificationEventCallback_t radioNotificationCallback;
- /**
- * The registered callback handler for scanned advertisement packet
- * notifications.
- */
AdvertisementReportCallback_t onAdvertisementReport;
- /**
- * Callchain containing all registered callback handlers for connection
- * events.
- */
ConnectionEventCallbackChain_t connectionCallChain;
- /**
- * Callchain containing all registered callback handlers for disconnection
- * events.
- */
DisconnectionEventCallbackChain_t disconnectionCallChain;
private:
- /**
- * Callchain containing all registered callback handlers for shutdown
- * events.
- */
GapShutdownCallbackChain_t shutdownCallChain;
private: