Schoumi/BLE_API
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

New version

Browse source 
Based on the main repo's master version, with edits to the API.
This commit is contained in:
Irit Arkin 2015-11-16 08:46:13 +00:00
parent 042c89746c
commit c39f5f7fd4
1 changed files with 72 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

144
ble/Gap.h
View file

@ -24,7 +24,7 @@
#include "CallChainOfFunctionPointersWithContext.h"
#include "FunctionPointerWithContext.h"
/* Forward declarations for classes which will only be used for pointers or references in the following. */
/* Forward declarations for classes that will only be used for pointers or references in the following. */
class GapAdvertisingParams;
class GapScanningParams;
class GapAdvertisingData;
@ -37,11 +37,11 @@ public:
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 @@ public:
/**
* Enumeration for disconnection reasons. The values for these reasons are
* derived from Nordic's implementation; but the reasons are meant to be
* independent of the transport. If you are returned a reason which is not
* covered by this enumeration, then please refer to the underlying
* derived from Nordic's implementation, but the reasons are meant to be
* independent of the transport. If you are returned a reason that is not
* covered by this enumeration, please refer to the underlying
* transport library.
*/
enum DisconnectionReason_t {
CONNECTION_TIMEOUT = 0x08,
REMOTE_USER_TERMINATED_CONNECTION = 0x13,
REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, /**< Remote Device Terminated Connection due to low resources.*/
REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /**< Remote Device Terminated Connection due to power off. */
REMOTE_DEV_TERMINATION_DUE_TO_LOW_RESOURCES = 0x14, /**< Remote device terminated connection due to low resources.*/
REMOTE_DEV_TERMINATION_DUE_TO_POWER_OFF = 0x15, /**< Remote device terminated connection due to power off. */
LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
CONN_INTERVAL_UNACCEPTABLE = 0x3B,
};
/* Describes the current state of the device (more than one bit can be set) */
/* Describes the current state of the device (more than one bit can be set). */
struct GapState_t {
unsigned advertising : 1; /**< peripheral is currently advertising */
unsigned connected : 1; /**< peripheral is connected to a central */
unsigned advertising : 1; /**< Peripheral is currently advertising. */
unsigned connected : 1; /**< Peripheral is connected to a central. */
};
typedef uint16_t Handle_t; /* Type for connection handle. */
@ -152,7 +152,7 @@ public:
public:
/**
* Set the BTLE MAC address and type. Please note that the address format is
* LSB (least significant byte first). Please refer to Address_t.
* least significant byte first (LSB). Please refer to Address_t.
*
* @return BLE_ERROR_NONE on success.
*/
@ -170,7 +170,7 @@ public:
* @return BLE_ERROR_NONE on success.
*/
virtual ble_error_t getAddress(AddressType_t *typeP, Address_t address) {
/* avoid compiler warnings about unused variables */
/* Avoid compiler warnings about unused variables. */
(void)typeP;
(void)address;
@ -230,7 +230,7 @@ public:
Gap::AddressType_t peerAddrType,
const ConnectionParams_t *connectionParams,
const GapScanningParams *scanParams) {
/* avoid compiler warnings about unused variables */
/* Avoid compiler warnings about unused variables. */
(void)peerAddr;
(void)peerAddrType;
(void)connectionParams;
@ -245,7 +245,7 @@ public:
* disconnectionCallback.
*
* @param reason
* The reason for disconnection to be sent back to the peer.
* The reason for disconnection; to be sent back to the peer.
*/
virtual ble_error_t disconnect(Handle_t connectionHandle, DisconnectionReason_t reason) {
/* avoid compiler warnings about unused variables */
@ -261,15 +261,15 @@ public:
* disconnectionCallback.
*
* @param reason
* The reason for disconnection to be sent back to the peer.
* The reason for disconnection; to be sent back to the peer.
*
* @note: this version of disconnect() doesn't take a connection handle. It
* will work reliably only for stacks which are limited to a single
* @note: This version of disconnect() doesn't take a connection handle. It
* works reliably only for stacks that are limited to a single
* connection. This API should be considered *deprecated* in favour of the
* altertive which takes a connection handle. It will be dropped in the future.
* alternative, which takes a connection handle. It will be dropped in the future.
*/
virtual ble_error_t disconnect(DisconnectionReason_t reason) {
/* avoid compiler warnings about unused variables */
/* Avoid compiler warnings about unused variables. */
(void)reason;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@ -288,7 +288,7 @@ public:
* the given structure pointed to by params.
*/
virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) {
/* avoid compiler warnings about unused variables */
/* Avoid compiler warnings about unused variables. */
(void)params;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@ -303,7 +303,7 @@ public:
* The structure containing the desired parameters.
*/
virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) {
/* avoid compiler warnings about unused variables */
/* Avoid compiler warnings about unused variables. */
(void)params;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@ -311,12 +311,12 @@ public:
/**
* Update connection parameters.
* In the central role this will initiate a Link Layer connection parameter update procedure,
* otherwise in the peripheral role, this will send the corresponding L2CAP request and wait for
* In the central role this will initiate a Link Layer connection parameter update procedure.
* In the peripheral role, this will send the corresponding L2CAP request and wait for
* the central to perform the procedure.
*
* @param[in] handle
* Connection Handle
* Connection Handle.
* @param[in] params
* Pointer to desired connection parameters. If NULL is provided on a peripheral role,
* the parameters in the PPCP characteristic of the GAP service will be used instead.
@ -335,7 +335,7 @@ public:
* The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
*/
virtual ble_error_t setDeviceName(const uint8_t *deviceName) {
/* avoid compiler warnings about unused variables */
/* Avoid compiler warnings about unused variables. */
(void)deviceName;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@ -373,7 +373,7 @@ public:
* The new value for the device-appearance.
*/
virtual ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
/* avoid compiler warnings about unused variables */
/* Avoid compiler warnings about unused variables. */
(void)appearance;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@ -385,7 +385,7 @@ public:
* The new value for the device-appearance.
*/
virtual ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
/* avoid compiler warnings about unused variables */
/* Avoid compiler warnings about unused variables. */
(void)appearanceP;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@ -396,7 +396,7 @@ public:
* @param[in] txPower Radio transmit power in dBm.
*/
virtual ble_error_t setTxPower(int8_t txPower) {
/* avoid compiler warnings about unused variables */
/* Avoid compiler warnings about unused variables. */
(void)txPower;
return BLE_ERROR_NOT_IMPLEMENTED; /* Requesting action from porter(s): override this API if this capability is supported. */
@ -411,7 +411,7 @@ public:
* Out parameter to receive the array's size.
*/
virtual void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
/* avoid compiler warnings about unused variables */
/* Avoid compiler warnings about unused variables. */
(void)valueArrayPP;
(void)countP;
@ -430,8 +430,8 @@ protected:
*/
public:
/**
* Returns the current GAP state of the device using a bitmask which
* describes whether the device is advertising and/or connected.
* Returns the current GAP state of the device using a bitmask that
* describes whether the device is advertising or connected.
*/
GapState_t getState(void) const {
return state;
@ -456,7 +456,7 @@ public:
* to ADV_CONNECTABLE_DIRECTED.
*
* @note: Decreasing this value will allow central devices to detect a
* peripheral faster at the expense of more power being used by the radio
* peripheral faster, at the expense of more power being used by the radio
* due to the higher data transmit rate.
*
* @note: This API is now *deprecated* and will be dropped in the future.
@ -468,7 +468,7 @@ public:
* 'interval' argument. That required an explicit conversion from
* milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
* no longer required as the new units are milliseconds. Any application
* code depending on the old semantics would need to be updated accordingly.
* code depending on the old semantics needs to be updated accordingly.
*/
void setAdvertisingInterval(uint16_t interval) {
if (interval == 0) {
@ -492,14 +492,14 @@ public:
* Start advertising.
*/
ble_error_t startAdvertising(void) {
setAdvertisingData(); /* update the underlying stack */
setAdvertisingData(); /* Update the underlying stack. */
return startAdvertising(_advParams);
}
/**
* Reset any advertising payload prepared from prior calls to
* accumulateAdvertisingPayload(). This automatically propagates the re-
* initialized adv payload to the underlying stack.
* initialized advertising payload to the underlying stack.
*
* Note: This should be followed by a call to setAdvertisingPayload() or
* startAdvertising() before the update takes effect.
@ -512,7 +512,7 @@ public:
/**
* Accumulate an AD structure in the advertising payload. Please note that
* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
* as an additional 31 bytes if the advertising payload proves to be too
* as an additional 31 bytes if the advertising payload is too
* small.
*
* @param[in] flags
@ -532,7 +532,7 @@ public:
/**
* Accumulate an AD structure in the advertising payload. Please note that
* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
* as an additional 31 bytes if the advertising payload proves to be too
* as an additional 31 bytes if the advertising payload is too
* small.
*
* @param app
@ -552,7 +552,7 @@ public:
/**
* Accumulate an AD structure in the advertising payload. Please note that
* the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
* as an additional 31 bytes if the advertising payload proves to be too
* as an additional 31 bytes if the advertising payload is too
* small.
*
* @param app
@ -572,11 +572,11 @@ public:
* Accumulate a variable length byte-stream as an AD structure in the
* advertising payload. Please note that the payload is limited to 31 bytes.
* The SCAN_RESPONSE message may be used as an additional 31 bytes if the
* advertising payload proves to be too small.
* advertising payload is too small.
*
* @param type The type which describes the variable length data.
* @param data data bytes.
* @param len length of data.
* @param type The type describing the variable length data.
* @param data Data bytes.
* @param len Length of data.
*/
ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@ -596,14 +596,14 @@ public:
* matching type and length). Note: the length of the new data must be the
* same as the old one.
*
* @param[in] type The ADV type field which describes the variable length data.
* @param[in] data data bytes.
* @param[in] len length of data.
* @param[in] type The ADV type field describing the variable length data.
* @param[in] data Data bytes.
* @param[in] len Length of data.
*
* @note: If advertisements are enabled, then the update will take effect immediately.
*
* @return BLE_ERROR_NONE if the advertisement payload was updated based on
* a <type, len> match; else an appropriate error.
* a <type, len> match; otherwise, an appropriate error.
*/
ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@ -619,7 +619,7 @@ public:
}
/**
* Setup a particular, user-constructed advertisement payload for the
* Set up a particular, user-constructed advertisement payload for the
* underlying stack. It would be uncommon for this API to be used directly;
* there are other APIs to build an advertisement payload (see above).
*/
@ -640,9 +640,9 @@ public:
* Accumulate a variable length byte-stream as an AD structure in the
* scanResponse payload.
*
* @param[in] type The type which describes the variable length data.
* @param[in] data data bytes.
* @param[in] len length of data.
* @param[in] type The type describing the variable length data.
* @param[in] data Data bytes.
* @param[in] len Length of data.
*/
ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
ble_error_t rc;
@ -666,13 +666,13 @@ public:
}
/**
* Setup parameters for GAP scanning--i.e. observer mode.
* Set up parameters for GAP scanning (observer mode).
* @param[in] interval
* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
* @param[in] window
* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
* @param[in] timeout
* Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout.
* Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
* @param[in] activeScanning
* Set to True if active-scanning is required. This is used to fetch the
* scan response from a peer if possible.
@ -705,7 +705,7 @@ public:
}
/**
* Setup the scanInterval parameter for GAP scanning--i.e. observer mode.
* Set up the scanInterval parameter for GAP scanning (observer mode).
* @param[in] interval
* Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
*
@ -724,7 +724,7 @@ public:
}
/**
* Setup the scanWindow parameter for GAP scanning--i.e. observer mode.
* Set up the scanWindow parameter for GAP scanning (observer mode).
* @param[in] window
* Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
*
@ -756,9 +756,9 @@ public:
}
/**
* Setup parameters for GAP scanning--i.e. observer mode.
* Set up parameters for GAP scanning (observer mode).
* @param[in] timeout
* Scan timeout (in seconds) between 0x0001 and 0xFFFF, 0x0000 disables timeout.
* Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables the timeout.
*
* Once the scanning parameters have been configured, scanning can be
* enabled by using startScan().
@ -781,7 +781,7 @@ public:
}
/**
* Setup parameters for GAP scanning--i.e. observer mode.
* Set up parameters for GAP scanning (observer mode).
* @param[in] activeScanning
* Set to True if active-scanning is required. This is used to fetch the
* scan response from a peer if possible.
@ -808,7 +808,7 @@ public:
* effect.
*
* @param[in] callback
* The application specific callback to be invoked upon
* The application-specific callback to be invoked upon
* receiving every advertisement report. This can be passed in
* as NULL, in which case scanning may not be enabled at all.
*/
@ -842,17 +842,17 @@ public:
/**
* 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.
@ -867,8 +867,8 @@ private:
}
private:
virtual ble_error_t setAdvertisingData(const GapAdvertisingData &, const GapAdvertisingData &) = 0;
virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
virtual ble_error_t setAdvertisingData(const GapAdvertisingData &advData, const GapAdvertisingData &scanResponse) = 0;
virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
public:
/**
@ -882,7 +882,7 @@ public:
}
/**
* Setup a particular, user-constructed set of advertisement parameters for
* Set up a particular, user-constructed set of advertisement parameters for
* the underlying stack. It would be uncommon for this API to be used
* directly; there are other APIs to tweak advertisement parameters
* individually.
@ -894,7 +894,7 @@ public:
/* Event callback handlers. */
public:
/**
* Setup a callback for timeout events. Refer to TimeoutSource_t for
* Set up a callback for timeout events. Refer to TimeoutSource_t for
* possible event types.
*/
void onTimeout(TimeoutEventCallback_t callback) {timeoutCallback = callback;}
@ -922,18 +922,18 @@ public:
* (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
@ -1028,7 +1028,7 @@ protected:
CallChainOfFunctionPointersWithContext<const DisconnectionCallbackParams_t*> disconnectionCallChain;
private:
/* disallow copy and assignment */
/* Disallow copy and assignment. */
Gap(const Gap &);
Gap& operator=(const Gap &);
};