YuLin Jiang
/
nRF51BLE_API
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Fork of
BLE_API
by 
Bluetooth Low Energy
Revision 1135:22aada733dbd, committed 2016-04-06
- Comitter:
- vcoubard
- Date:
- Wed Apr 06 19:13:54 2016 +0100
- Parent:
- 1134:d540a48f650d
- Child:
- 1136:6b1e6b7282a6
- Commit message:
- Synchronized with git rev 17e37360
Author: Vincent Coubard
Merge pull request #161 from ARMmbed/develop
merge branch develop (v2.4.0)
Changed in this revision
--- a/ble/BLE.h Wed Apr 06 19:13:52 2016 +0100
+++ b/ble/BLE.h Wed Apr 06 19:13:54 2016 +0100
@@ -196,7 +196,7 @@
* directly, as it returns references to singletons.
*
* @param[in] id
- * Instance-ID. This should be less than NUM_INSTANCES
+ * Instance-ID. This should be less than NUM_INSTANCES
* for the returned BLE singleton to be useful.
*
* @return a reference to a single object.
@@ -239,7 +239,7 @@
* ble.setAddress(...) should be replaced with
* ble.gap().setAddress(...).
*/
- ble_error_t setAddress(Gap::AddressType_t type, const Gap::Address_t address) {
+ ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
return gap().setAddress(type, address);
}
@@ -252,7 +252,7 @@
* ble.getAddress(...) should be replaced with
* ble.gap().getAddress(...).
*/
- ble_error_t getAddress(Gap::AddressType_t *typeP, Gap::Address_t address) {
+ ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
return gap().getAddress(typeP, address);
}
@@ -752,10 +752,10 @@
* ble.connect(...) should be replaced with
* ble.gap().connect(...).
*/
- ble_error_t connect(const Gap::Address_t peerAddr,
- Gap::AddressType_t peerAddrType = Gap::ADDR_TYPE_RANDOM_STATIC,
- const Gap::ConnectionParams_t *connectionParams = NULL,
- const GapScanningParams *scanParams = NULL) {
+ ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
+ BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
+ const Gap::ConnectionParams_t *connectionParams = NULL,
+ const GapScanningParams *scanParams = NULL) {
return gap().connect(peerAddr, peerAddrType, connectionParams, scanParams);
}
@@ -773,7 +773,7 @@
}
/**
- * This call initiates the disconnection procedure, and its completion
+ * This call initiates the disconnection procedure, and its completion
* is communicated to the application with an invocation of the
* onDisconnection callback.
*
@@ -1407,7 +1407,7 @@
/**
* Set up a callback for when the passkey needs to be displayed on a
* peripheral with DISPLAY capability. This happens when security is
- * configured to prevent Man-In-The-Middle attacks, and the peers need to exchange
+ * configured to prevent Man-In-The-Middle attacks, and the peers need to exchange
* a passkey (or PIN) to authenticate the connection
* attempt.
*
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ble/BLEProtocol.h Wed Apr 06 19:13:54 2016 +0100
@@ -0,0 +1,69 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __BLE_PROTOCOL_H__
+#define __BLE_PROTOCOL_H__
+
+#include <stddef.h>
+#include <stdint.h>
+#include <algorithm>
+
+/**
+ * A common namespace for types and constants used everywhere in BLE API.
+ */
+namespace BLEProtocol {
+ /**<
+ * A simple container for the enumeration of address-types for Protocol addresses.
+ *
+ * Adding a struct to encapsulate the contained enumeration prevents
+ * polluting the BLEProtocol namespace with the enumerated values. It also
+ * allows type-aliases for the enumeration while retaining the enumerated
+ * values. i.e. doing:
+ * typedef AddressType AliasedType;
+ *
+ * would allow the use of AliasedType::PUBLIC in code.
+ */
+ struct AddressType {
+ /**< Address-types for Protocol addresses. */
+ enum Type {
+ PUBLIC = 0,
+ RANDOM_STATIC,
+ RANDOM_PRIVATE_RESOLVABLE,
+ RANDOM_PRIVATE_NON_RESOLVABLE
+ };
+ };
+ typedef AddressType::Type AddressType_t; /**< Alias for AddressType::Type */
+
+ static const size_t ADDR_LEN = 6; /**< Length (in octets) of the BLE MAC address. */
+ typedef uint8_t AddressBytes_t[ADDR_LEN]; /**< 48-bit address, in LSB format. */
+
+ /**
+ * BLE address. It contains an address-type (@ref AddressType_t) and bytes (@ref AddressBytes_t).
+ */
+ struct Address_t {
+ AddressType_t type; /**< @ref AddressType_t */
+ AddressBytes_t address; /**< @ref AddressBytes_t */
+
+ Address_t(AddressType_t typeIn, const AddressBytes_t& addressIn) : type(typeIn) {
+ std::copy(addressIn, addressIn + ADDR_LEN, address);
+ }
+
+ Address_t() : type(), address() {
+ }
+ };
+};
+
+#endif /* __BLE_PROTOCOL_H__ */
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ble/CharacteristicDescriptorDiscovery.h Wed Apr 06 19:13:54 2016 +0100
@@ -0,0 +1,99 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2015 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
+#define __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
+
+#include "FunctionPointerWithContext.h"
+
+class DiscoveredCharacteristic; // forward declaration
+class DiscoveredCharacteristicDescriptor; // forward declaration
+
+/**
+ * @brief Contain all definitions of callbacks and callbacks parameters types
+ * related to characteristic descriptor discovery.
+ *
+ * @details This class act like a namespace for characteristic descriptor discovery
+ * types. It act like ServiceDiscovery by providing callbacks and callbacks
+ * parameters types related to the characteristic descriptor discovery process but
+ * contrary to ServiceDiscovery class, it does not force the porter to use a
+ * specific interface for the characteristic descriptor discovery process.
+ */
+class CharacteristicDescriptorDiscovery {
+public:
+ /**
+ * @brief Parameter type of CharacteristicDescriptorDiscovery::DiscoveryCallback_t.
+ * @detail Every time a characteristic descriptor has been discovered, the callback
+ * registered for the discovery operation through GattClient::discoverCharacteristicDescriptors
+ * or DiscoveredCharacteristic::discoverDescriptors will be called with this parameter.
+ *
+ */
+ struct DiscoveryCallbackParams_t {
+ /**
+ * The characteristic owning the DiscoveredCharacteristicDescriptor
+ */
+ const DiscoveredCharacteristic& characteristic;
+
+ /**
+ * The characteristic descriptor discovered
+ */
+ const DiscoveredCharacteristicDescriptor& descriptor;
+ };
+
+ /**
+ * @brief Parameter type of CharacteristicDescriptorDiscovery::TerminationCallback_t.
+ * @details Once a characteristic descriptor discovery process terminate, the termination
+ * callback registered for the discovery operation through
+ * GattClient::discoverCharacteristicDescriptors or DiscoveredCharacteristic::discoverDescriptors
+ * will be called with this parameter.
+ */
+ struct TerminationCallbackParams_t {
+ /**
+ * The characteristic for which the descriptors has been discovered
+ */
+ const DiscoveredCharacteristic& characteristic;
+
+ /**
+ * status of the discovery operation
+ */
+ ble_error_t status;
+ };
+
+ /**
+ * @brief Callback type for when a matching characteristic descriptor is found during
+ * characteristic descriptor discovery.
+ *
+ * @param param A pointer to a DiscoveryCallbackParams_t object which will remain
+ * valid for the lifetime of the callback. Memory for this object is owned by
+ * the BLE_API eventing framework. The application can safely make a persistent
+ * shallow-copy of this object in order to work with the service beyond the
+ * callback.
+ */
+ typedef FunctionPointerWithContext<const DiscoveryCallbackParams_t*> DiscoveryCallback_t;
+
+ /**
+ * @brief Callback type for when characteristic descriptor discovery terminates.
+ *
+ * @param param A pointer to a TerminationCallbackParams_t object which will remain
+ * valid for the lifetime of the callback. Memory for this object is owned by
+ * the BLE_API eventing framework. The application can safely make a persistent
+ * shallow-copy of this object in order to work with the service beyond the
+ * callback.
+ */
+ typedef FunctionPointerWithContext<const TerminationCallbackParams_t*> TerminationCallback_t;
+};
+
+#endif // ifndef __CHARACTERISTIC_DESCRIPTOR_DISCOVERY_H__
\ No newline at end of file
--- a/ble/DiscoveredCharacteristic.h Wed Apr 06 19:13:52 2016 +0100
+++ b/ble/DiscoveredCharacteristic.h Wed Apr 06 19:13:54 2016 +0100
@@ -21,10 +21,24 @@
#include "Gap.h"
#include "GattAttribute.h"
#include "GattClient.h"
+#include "CharacteristicDescriptorDiscovery.h"
+#include "ble/DiscoveredCharacteristicDescriptor.h"
/**
- * Structure for holding information about the service and the characteristics
- * found during the discovery process.
+ * @brief Representation of a characteristic discovered during a GattClient
+ * discovery procedure (see GattClient::launchServiceDiscovery ).
+ *
+ * @detail Provide detailed informations about a discovered characteristic like:
+ * - Its UUID (see #getUUID).
+ * - The most important handles of the characteristic definition
+ * (see #getDeclHandle, #getValueHandle, #getLastHandle )
+ * - Its properties (see #getProperties).
+ * This class also provide functions to operate on the characteristic:
+ * - Read the characteristic value (see #read)
+ * - Writing a characteristic value (see #write or #writeWoResponse)
+ * - Discover descriptors inside the characteristic definition. These descriptors
+ * extends the characteristic. More information about descriptor usage is
+ * available in DiscoveredCharacteristicDescriptor class.
*/
class DiscoveredCharacteristic {
public:
@@ -33,7 +47,7 @@
uint8_t _read :1; /**< Reading the value permitted. */
uint8_t _writeWoResp :1; /**< Writing the value with Write Command permitted. */
uint8_t _write :1; /**< Writing the value with Write Request permitted. */
- uint8_t _notify :1; /**< Notications of the value permitted. */
+ uint8_t _notify :1; /**< Notifications of the value permitted. */
uint8_t _indicate :1; /**< Indications of the value permitted. */
uint8_t _authSignedWrite :1; /**< Writing the value with Signed Write Command permitted. */
@@ -46,36 +60,50 @@
bool indicate(void) const {return _indicate; }
bool authSignedWrite(void) const {return _authSignedWrite;}
+ /**
+ * @brief "Equal to" operator for DiscoveredCharacteristic::Properties_t
+ *
+ * @param lhs[in] The left hand side of the equality expression
+ * @param rhs[in] The right hand side of the equality expression
+ *
+ * @return true if operands are equals, false otherwise.
+ */
+ friend bool operator==(Properties_t lhs, Properties_t rhs) {
+ return lhs._broadcast == rhs._broadcast &&
+ lhs._read == rhs._read &&
+ lhs._writeWoResp == rhs._writeWoResp &&
+ lhs._write == rhs._write &&
+ lhs._notify == rhs._notify &&
+ lhs._indicate == rhs._indicate &&
+ lhs._authSignedWrite == rhs._authSignedWrite;
+ }
+
+ /**
+ * @brief "Not equal to" operator for DiscoveredCharacteristic::Properties_t
+ *
+ * @param lhs The right hand side of the expression
+ * @param rhs The left hand side of the expression
+ *
+ * @return true if operands are not equals, false otherwise.
+ */
+ friend bool operator!=(Properties_t lhs, Properties_t rhs) {
+ return !(lhs == rhs);
+ }
+
private:
operator uint8_t() const; /* Disallow implicit conversion into an integer. */
operator unsigned() const; /* Disallow implicit conversion into an integer. */
};
/**
- * Structure for holding information about the service and the characteristics
- * found during the discovery process.
- */
- struct DiscoveredDescriptor {
- GattAttribute::Handle_t handle; /**< Descriptor Handle. */
- UUID uuid; /**< Descriptor UUID. */
- };
-
- /**
- * Callback type for when a characteristic descriptor is found during descriptor-
- * discovery. The receiving function is passed in a pointer to a
- * DiscoveredDescriptor object which will remain valid for the lifetime
- * of the callback. Memory for this object is owned by the BLE_API eventing
- * framework. The application can safely make a persistent shallow-copy of
- * this object in order to work with the characteristic beyond the callback.
- */
- typedef void (*DescriptorCallback_t)(const DiscoveredDescriptor *);
-
- /**
* Initiate (or continue) a read for the value attribute, optionally at a
* given offset. If the characteristic or descriptor to be read is longer
* than ATT_MTU - 1, this function must be called multiple times with
* appropriate offset to read the complete value.
*
+ * @param offset[in] The position - in the characteristic value bytes stream - where
+ * the read operation begin.
+ *
* @return BLE_ERROR_NONE if a read has been initiated, or
* BLE_ERROR_INVALID_STATE if some internal state about the connection is invalid, or
* BLE_STACK_BUSY if some client procedure is already in progress, or
@@ -83,14 +111,22 @@
*/
ble_error_t read(uint16_t offset = 0) const;
+ /**
+ * @brief Same as #read(uint16_t) const but allow the user to register a callback
+ * which will be fired once the read is done.
+ *
+ * @param offset[in] The position - in the characteristic value bytes stream - where
+ * the read operation begin.
+ * @param onRead[in] Continuation of the read operation
+ */
ble_error_t read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const;
/**
* Perform a write without response procedure.
*
- * @param length
+ * @param[in] length
* The amount of data being written.
- * @param value
+ * @param[in] value
* The bytes being written.
*
* @note It is important to note that a write without response will generate
@@ -110,20 +146,20 @@
/**
* Initiate a GATT Characteristic Descriptor Discovery procedure for descriptors within this characteristic.
*
- * @param callback
- * @param matchingUUID
- * Filter for descriptors. Defaults to wildcard which will discover all descriptors.
+ * @param[in] onDescriptorDiscovered This callback will be called every time a descriptor is discovered
+ * @param[in] onTermination This callback will be called when the discovery process is over.
*
- * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
+ * @return BLE_ERROR_NONE if descriptor discovery is launched successfully; else an appropriate error.
*/
- ble_error_t discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) const;
+ ble_error_t discoverDescriptors(const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onDescriptorDiscovered,
+ const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const;
/**
* Perform a write procedure.
*
- * @param length
+ * @param[in] length
* The amount of data being written.
- * @param value
+ * @param[in] value
* The bytes being written.
*
* @note It is important to note that a write will generate
@@ -138,36 +174,142 @@
ble_error_t write(uint16_t length, const uint8_t *value) const;
/**
- * Same as above but register the callback wich will be called once the data has been written
+ * Same as #write(uint16_t, const uint8_t *) const but register a callback
+ * which will be called once the data has been written.
+ *
+ * @param[in] length The amount of bytes to write.
+ * @param[in] value The bytes to write.
+ * @param[in] onRead Continuation callback for the write operation
*/
- ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onRead) const;
+ ble_error_t write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onWrite) const;
void setupLongUUID(UUID::LongUUIDBytes_t longUUID, UUID::ByteOrder_t order = UUID::MSB) {
uuid.setupLong(longUUID, order);
}
public:
+ /**
+ * @brief Get the UUID of the discovered characteristic
+ * @return the UUID of this characteristic
+ */
const UUID& getUUID(void) const {
return uuid;
}
+ /**
+ * @brief Get the properties of this characteristic
+ * @return the set of properties of this characteristic
+ */
const Properties_t& getProperties(void) const {
return props;
}
- const GattAttribute::Handle_t& getDeclHandle(void) const {
+ /**
+ * @brief Get the declaration handle of this characteristic.
+ * @detail The declaration handle is the first handle of a characteristic
+ * definition. The value accessible at this handle contains the following
+ * informations:
+ * - The characteristics properties (see Properties_t). This value can
+ * be accessed by using #getProperties .
+ * - The characteristic value attribute handle. This field can be accessed
+ * by using #getValueHandle .
+ * - The characteristic UUID, this value can be accessed by using the
+ * function #getUUID .
+ * @return the declaration handle of this characteristic.
+ */
+ GattAttribute::Handle_t getDeclHandle(void) const {
return declHandle;
}
- const GattAttribute::Handle_t& getValueHandle(void) const {
+
+ /**
+ * @brief Return the handle used to access the value of this characteristic.
+ * @details This handle is the one provided in the characteristic declaration
+ * value. Usually, it is equal to #getDeclHandle() + 1. But it is not always
+ * the case. Anyway, users are allowed to use #getDeclHandle() + 1 to access
+ * the value of a characteristic.
+ * @return The handle to access the value of this characteristic.
+ */
+ GattAttribute::Handle_t getValueHandle(void) const {
return valueHandle;
}
+ /**
+ * @brief Return the last handle of the characteristic definition.
+ * @details A Characteristic definition can contain a lot of handles:
+ * - one for the declaration (see #getDeclHandle)
+ * - one for the value (see #getValueHandle)
+ * - zero of more for the characteristic descriptors.
+ * This handle is the last handle of the characteristic definition.
+ * @return The last handle of this characteristic definition.
+ */
+ GattAttribute::Handle_t getLastHandle(void) const {
+ return lastHandle;
+ }
+
+ /**
+ * @brief Return the GattClient which can operate on this characteristic.
+ * @return The GattClient which can operate on this characteristic.
+ */
+ GattClient* getGattClient() {
+ return gattc;
+ }
+
+ /**
+ * @brief Return the GattClient which can operate on this characteristic.
+ * @return The GattClient which can operate on this characteristic.
+ */
+ const GattClient* getGattClient() const {
+ return gattc;
+ }
+
+ /**
+ * @brief Return the connection handle to the GattServer which contain
+ * this characteristic.
+ * @return the connection handle to the GattServer which contain
+ * this characteristic.
+ */
+ Gap::Handle_t getConnectionHandle() const {
+ return connHandle;
+ }
+
+ /**
+ * @brief "Equal to" operator for DiscoveredCharacteristic
+ *
+ * @param lhs[in] The left hand side of the equality expression
+ * @param rhs[in] The right hand side of the equality expression
+ *
+ * @return true if operands are equals, false otherwise.
+ */
+ friend bool operator==(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) {
+ return lhs.gattc == rhs.gattc &&
+ lhs.uuid == rhs.uuid &&
+ lhs.props == rhs.props &&
+ lhs.declHandle == rhs.declHandle &&
+ lhs.valueHandle == rhs.valueHandle &&
+ lhs.lastHandle == rhs.lastHandle &&
+ lhs.connHandle == rhs.connHandle;
+ }
+
+ /**
+ * @brief "Not equal to" operator for DiscoveredCharacteristic
+ *
+ * @param lhs[in] The right hand side of the expression
+ * @param rhs[in] The left hand side of the expression
+ *
+ * @return true if operands are not equals, false otherwise.
+ */
+ friend bool operator !=(const DiscoveredCharacteristic& lhs, const DiscoveredCharacteristic& rhs) {
+ return !(lhs == rhs);
+ }
+
public:
DiscoveredCharacteristic() : gattc(NULL),
uuid(UUID::ShortUUIDBytes_t(0)),
props(),
declHandle(GattAttribute::INVALID_HANDLE),
- valueHandle(GattAttribute::INVALID_HANDLE) {
+ valueHandle(GattAttribute::INVALID_HANDLE),
+ lastHandle(GattAttribute::INVALID_HANDLE),
+ connHandle() {
/* empty */
}
@@ -179,6 +321,7 @@
Properties_t props;
GattAttribute::Handle_t declHandle;
GattAttribute::Handle_t valueHandle;
+ GattAttribute::Handle_t lastHandle;
Gap::Handle_t connHandle;
};
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/ble/DiscoveredCharacteristicDescriptor.h Wed Apr 06 19:13:54 2016 +0100
@@ -0,0 +1,111 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2013 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__
+#define __DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__
+
+#include "UUID.h"
+#include "Gap.h"
+#include "GattAttribute.h"
+#include "GattClient.h"
+#include "CharacteristicDescriptorDiscovery.h"
+
+/**
+ * @brief Representation of a descriptor discovered during a GattClient
+ * discovery procedure (see GattClient::discoverCharacteristicDescriptors or
+ * DiscoveredCharacteristic::discoverDescriptors ).
+ *
+ * @detail Provide detailed informations about a discovered characteristic descriptor
+ * like:
+ * - Its UUID (see #getUUID).
+ * - Its handle (see #getAttributeHandle)
+ * Basic read (see GattClient::read) and write (see GattClient::write) procedure from
+ * GattClient can be used access the value of the descriptor.
+ *
+ * @todo read member function
+ * @todo write member function
+ * @todo enumeration of standard descriptors
+ */
+class DiscoveredCharacteristicDescriptor {
+
+public:
+
+ /**
+ * @brief construct a new instance of a DiscoveredCharacteristicDescriptor
+ *
+ * @param client The client from where the descriptor has been discovered
+ * @param connectionHandle The connection handle on which the descriptor has
+ * been discovered
+ * @param attributeHandle The handle of the attribute containing this descriptor
+ * @param uuid The UUID of the descriptor
+ */
+ DiscoveredCharacteristicDescriptor(
+ GattClient* client, Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, const UUID& uuid) :
+ _client(client), _connectionHandle(connectionHandle), _uuid(uuid), _gattHandle(attributeHandle) {
+
+ }
+
+ /**
+ * @brief Return the GattClient which can operate on this descriptor.
+ * @return The GattClient which can operate on this descriptor.
+ */
+ GattClient* getGattClient() {
+ return _client;
+ }
+
+ /**
+ * @brief Return the GattClient which can operate on this descriptor.
+ * @return The GattClient which can operate on this descriptor.
+ */
+ const GattClient* getGattClient() const {
+ return _client;
+ }
+
+ /**
+ * @brief Return the connection handle to the GattServer which contain
+ * this descriptor.
+ * @return the connection handle to the GattServer which contain
+ * this descriptor.
+ */
+ Gap::Handle_t getConnectionHandle() const {
+ return _connectionHandle;
+ }
+
+ /**
+ * @brief Return the UUID of this descriptor
+ * @return the UUID of this descriptor
+ */
+ const UUID& getUUID(void) const {
+ return _uuid;
+ }
+
+ /**
+ * @brief Return the attribute handle to use to access to this descriptor
+ * on the gatt server.
+ * @return The attribute handle of the descriptor
+ */
+ GattAttribute::Handle_t getAttributeHandle() const {
+ return _gattHandle;
+ }
+
+private:
+ GattClient *_client;
+ Gap::Handle_t _connectionHandle;
+ UUID _uuid;
+ GattAttribute::Handle_t _gattHandle;
+};
+
+#endif /*__DISCOVERED_CHARACTERISTIC_DESCRIPTOR_H__*/
\ No newline at end of file
--- a/ble/Gap.h Wed Apr 06 19:13:52 2016 +0100
+++ b/ble/Gap.h Wed Apr 06 19:13:54 2016 +0100
@@ -17,12 +17,14 @@
#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;
@@ -30,19 +32,44 @@
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:
- enum AddressType_t {
- ADDR_TYPE_PUBLIC = 0,
- ADDR_TYPE_RANDOM_STATIC,
- ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE,
- ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE
+ /**
+ * 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;
+
+ /**
+ * 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
};
- 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. */
+ 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. */
@@ -66,6 +93,56 @@
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. */
@@ -75,9 +152,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;
@@ -87,31 +164,31 @@
};
struct AdvertisementCallbackParams_t {
- Address_t peerAddr;
- int8_t rssi;
- bool isScanResponse;
- GapAdvertisingParams::AdvertisingType_t type;
- uint8_t advertisingDataLen;
- const uint8_t *advertisingData;
+ BLEProtocol::AddressBytes_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;
- AddressType_t peerAddrType;
- Address_t peerAddr;
- AddressType_t ownAddrType;
- Address_t ownAddr;
- const ConnectionParams_t *connectionParams;
+ 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;
- 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) :
+ 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) :
handle(handleIn),
role(roleIn),
peerAddrType(peerAddrTypeIn),
@@ -151,17 +228,20 @@
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 Address_t.
+ * least significant byte first (LSB). Please refer to BLEProtocol::AddressBytes_t.
*
* @return BLE_ERROR_NONE on success.
*/
- virtual ble_error_t setAddress(AddressType_t type, const Address_t address) {
+ virtual ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
/* avoid compiler warnings about unused variables */
(void)type;
(void)address;
@@ -174,7 +254,7 @@
*
* @return BLE_ERROR_NONE on success.
*/
- virtual ble_error_t getAddress(AddressType_t *typeP, Address_t address) {
+ virtual ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
/* Avoid compiler warnings about unused variables. */
(void)typeP;
(void)address;
@@ -233,10 +313,10 @@
* successfully. The connectionCallChain (if set) will be invoked upon
* a connection event.
*/
- virtual ble_error_t connect(const Address_t peerAddr,
- Gap::AddressType_t peerAddrType,
- const ConnectionParams_t *connectionParams,
- const GapScanningParams *scanParams) {
+ virtual ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
+ BLEProtocol::AddressType_t peerAddrType,
+ const ConnectionParams_t *connectionParams,
+ const GapScanningParams *scanParams) {
/* Avoid compiler warnings about unused variables. */
(void)peerAddr;
(void)peerAddrType;
@@ -247,6 +327,23 @@
}
/**
+ * 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.
@@ -425,6 +522,156 @@
*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) {
@@ -575,6 +822,16 @@
* @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) {
@@ -591,8 +848,7 @@
/**
* Update a particular ADV field in the advertising payload (based on
- * matching type and length). Note: the length of the new data must be the
- * same as the old one.
+ * matching type).
*
* @param[in] type The ADV type field describing the variable length data.
* @param[in] data Data bytes.
@@ -601,7 +857,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
- * a <type, len> match; otherwise, an appropriate error.
+ * matching AD type; otherwise, an appropriate error.
*/
ble_error_t updateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
if (type == GapAdvertisingData::COMPLETE_LOCAL_NAME) {
@@ -983,6 +1239,80 @@
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(),
@@ -1002,13 +1332,13 @@
/* Entry points for the underlying stack to report events back to the user. */
public:
- 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) {
+ 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) {
state.connected = 1;
ConnectionCallbackParams_t callbackParams(handle, role, peerAddrType, peerAddr, ownAddrType, ownAddr, connectionParams);
connectionCallChain.call(&callbackParams);
@@ -1020,12 +1350,12 @@
disconnectionCallChain.call(&callbackParams);
}
- void processAdvertisementReport(const Address_t peerAddr,
- int8_t rssi,
- bool isScanResponse,
+ void processAdvertisementReport(const BLEProtocol::AddressBytes_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;
@@ -1059,6 +1389,9 @@
DisconnectionEventCallbackChain_t disconnectionCallChain;
private:
+ GapShutdownCallbackChain_t shutdownCallChain;
+
+private:
/* Disallow copy and assignment. */
Gap(const Gap &);
Gap& operator=(const Gap &);
--- a/ble/GapAdvertisingData.h Wed Apr 06 19:13:52 2016 +0100
+++ b/ble/GapAdvertisingData.h Wed Apr 06 19:13:54 2016 +0100
@@ -187,6 +187,7 @@
PULSE_OXIMETER_GENERIC = 3136, /**< Generic Pulse Oximeter. */
PULSE_OXIMETER_FINGERTIP = 3137, /**< Fingertip Pulse Oximeter. */
PULSE_OXIMETER_WRIST_WORN = 3138, /**< Wrist Worn Pulse Oximeter. */
+ GENERIC_WEIGHT_SCALE = 3200, /**< Generic Weight Scale. */
OUTDOOR_GENERIC = 5184, /**< Generic Outdoor. */
OUTDOOR_LOCATION_DISPLAY_DEVICE = 5185, /**< Outdoor Location Display Device. */
OUTDOOR_LOCATION_AND_NAVIGATION_DISPLAY_DEVICE = 5186, /**< Outdoor Location and Navigation Display Device. */
@@ -201,149 +202,63 @@
/**
* Adds advertising data based on the specified AD type (see DataType).
- *
- * @param advDataType The Advertising 'DataType' to add.
- * @param payload Pointer to the payload contents.
- * @param len Size of the payload in bytes.
- *
- * @return BLE_ERROR_BUFFER_OVERFLOW if the specified data would cause the
- * advertising buffer to overflow, else BLE_ERROR_NONE.
- */
- ble_error_t addData(DataType advDataType, const uint8_t *payload, uint8_t len)
- {
- ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW;
-
- // find field
- uint8_t* field = findField(advDataType);
-
- // Field type already exist, either add to field or replace
- if (field) {
- switch(advDataType) {
- // These fields will be overwritten with the new value
- case FLAGS:
- case SHORTENED_LOCAL_NAME:
- case COMPLETE_LOCAL_NAME:
- case TX_POWER_LEVEL:
- case DEVICE_ID:
- case SLAVE_CONNECTION_INTERVAL_RANGE:
- case SERVICE_DATA:
- case APPEARANCE:
- case ADVERTISING_INTERVAL:
- case MANUFACTURER_SPECIFIC_DATA: {
- // current field length, with the type subtracted
- uint8_t dataLength = field[0] - 1;
-
- // new data has same length, do in-order replacement
- if (len == dataLength) {
- for (uint8_t idx = 0; idx < dataLength; idx++) {
- field[2 + idx] = payload[idx];
- }
- } else {
- // check if data fits
- if ((_payloadLen - dataLength + len) <= GAP_ADVERTISING_DATA_MAX_PAYLOAD) {
-
- // remove old field
- while ((field + dataLength + 2) < &_payload[_payloadLen]) {
- *field = field[dataLength + 2];
- field++;
- }
-
- // reduce length
- _payloadLen -= dataLength + 2;
-
- // add new field
- result = appendField(advDataType, payload, len);
- }
- }
-
- break;
- }
- // These fields will have the new data appended if there is sufficient space
- case INCOMPLETE_LIST_16BIT_SERVICE_IDS:
- case COMPLETE_LIST_16BIT_SERVICE_IDS:
- case INCOMPLETE_LIST_32BIT_SERVICE_IDS:
- case COMPLETE_LIST_32BIT_SERVICE_IDS:
- case INCOMPLETE_LIST_128BIT_SERVICE_IDS:
- case COMPLETE_LIST_128BIT_SERVICE_IDS:
- case LIST_128BIT_SOLICITATION_IDS: {
- // check if data fits
- if ((_payloadLen + len) <= GAP_ADVERTISING_DATA_MAX_PAYLOAD) {
- // make room for new field by moving the remainder of the
- // advertisement payload "to the right" starting after the
- // TYPE field.
- uint8_t* end = &_payload[_payloadLen];
-
- while (&field[1] < end) {
- end[len] = *end;
- end--;
- }
-
- // insert new data
- for (uint8_t idx = 0; idx < len; idx++) {
- field[2 + idx] = payload[idx];
- }
-
- // increment lengths
- field[0] += len;
- _payloadLen += len;
-
- result = BLE_ERROR_NONE;
- }
-
- break;
- }
- // Field exists but updating it is not supported. Abort operation.
- default:
- result = BLE_ERROR_NOT_IMPLEMENTED;
- break;
- }
- } else {
- // field doesn't exists, insert new
- result = appendField(advDataType, payload, len);
- }
-
- return result;
- }
-
- /**
- * Update a particular ADV field in the advertising payload (based on
- * matching type and length). Note: the length of the new data must be the
- * same as the old one.
+ * If the supplied AD type is already present in the advertising
+ * payload, then the value is updated.
*
* @param[in] advDataType The Advertising 'DataType' to add.
* @param[in] payload Pointer to the payload contents.
* @param[in] len Size of the payload in bytes.
*
- * @return BLE_ERROR_UNSPECIFIED if the specified field is not found, else
- * BLE_ERROR_NONE.
+ * @return BLE_ERROR_BUFFER_OVERFLOW if the new value causes the
+ * advertising buffer to overflow. BLE_ERROR_NONE is returned
+ * on success.
+ *
+ * @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 addData(DataType_t advDataType, const uint8_t *payload, uint8_t len)
+ {
+ // find field
+ uint8_t* field = findField(advDataType);
+
+ if (field) {
+ // Field type already exist, either add to field or replace
+ return addField(advDataType, payload, len, field);
+ } else {
+ // field doesn't exists, insert new
+ return appendField(advDataType, payload, len);
+ }
+ }
+
+ /**
+ * Update a particular ADV field in the advertising payload (based on
+ * matching type).
+ *
+ * @param[in] advDataType The Advertising 'DataType' to add.
+ * @param[in] payload Pointer to the payload contents.
+ * @param[in] len Size of the payload in bytes.
+ *
+ * @return BLE_ERROR_UNSPECIFIED if the specified field is not found,
+ * BLE_ERROR_BUFFER_OVERFLOW if the new value causes the
+ * advertising buffer to overflow. BLE_ERROR_NONE is returned
+ * on success.
*/
ble_error_t updateData(DataType_t advDataType, const uint8_t *payload, uint8_t len)
{
- if ((payload == NULL) || (len == 0)) {
- return BLE_ERROR_INVALID_PARAM;
- }
-
- /* A local struct to describe an ADV field. This definition comes from the Bluetooth Core Spec. (v4.2) Part C, Section 11. */
- struct ADVField_t {
- uint8_t len; /* Describes the length (in bytes) of the following type and bytes. */
- uint8_t type; /* Should have the same representation of DataType_t (above). */
- uint8_t bytes[0]; /* A placeholder for variable length data. */
- };
+ // find field
+ uint8_t* field = findField(advDataType);
- /* Iterate over the adv fields looking for the first match. */
- uint8_t byteIndex = 0;
- while (byteIndex < _payloadLen) {
- ADVField_t *currentADV = (ADVField_t *)&_payload[byteIndex];
- if ((currentADV->len == (len + 1)) && /* Incoming len only describes the payload, whereas ADV->len describes [type + payload]. */
- (currentADV->type == advDataType)) {
- memcpy(currentADV->bytes, payload, len);
- return BLE_ERROR_NONE;
- }
-
- byteIndex += (currentADV->len + 1); /* Advance by len+1; '+1' is needed to span the len field itself. */
+ if (field) {
+ // Field type already exist, replace field contents
+ return updateField(advDataType, payload, len, field);
+ } else {
+ // field doesn't exists, return an error
+ return BLE_ERROR_UNSPECIFIED;
}
-
- return BLE_ERROR_UNSPECIFIED;
}
/**
@@ -474,6 +389,107 @@
return NULL;
}
+ /**
+ * Given the a pointer to a field in the advertising payload it replaces
+ * the existing data in the field with the supplied data.
+ *
+ * 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.
+ *
+ * Returns BLE_ERROR_NONE on success.
+ */
+ ble_error_t addField(DataType_t advDataType, const uint8_t *payload, uint8_t len, uint8_t* field)
+ {
+ ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW;
+
+ switch(advDataType) {
+ // These fields will have the new data appended if there is sufficient space
+ case INCOMPLETE_LIST_16BIT_SERVICE_IDS:
+ case COMPLETE_LIST_16BIT_SERVICE_IDS:
+ case INCOMPLETE_LIST_32BIT_SERVICE_IDS:
+ case COMPLETE_LIST_32BIT_SERVICE_IDS:
+ case INCOMPLETE_LIST_128BIT_SERVICE_IDS:
+ case COMPLETE_LIST_128BIT_SERVICE_IDS:
+ case LIST_128BIT_SOLICITATION_IDS: {
+ // check if data fits
+ if ((_payloadLen + len) <= GAP_ADVERTISING_DATA_MAX_PAYLOAD) {
+ // make room for new field by moving the remainder of the
+ // advertisement payload "to the right" starting after the
+ // TYPE field.
+ uint8_t* end = &_payload[_payloadLen];
+
+ while (&field[1] < end) {
+ end[len] = *end;
+ end--;
+ }
+
+ // insert new data
+ for (uint8_t idx = 0; idx < len; idx++) {
+ field[2 + idx] = payload[idx];
+ }
+
+ // increment lengths
+ field[0] += len;
+ _payloadLen += len;
+
+ result = BLE_ERROR_NONE;
+ }
+
+ break;
+ }
+ // These fields will be overwritten with the new value
+ default: {
+ result = updateField(advDataType, payload, len, field);
+
+ break;
+ }
+ }
+
+ return result;
+ }
+
+ /**
+ * Given the a pointer to a field in the advertising payload it replaces
+ * the existing data in the field with the supplied data.
+ * Returns BLE_ERROR_NONE on success.
+ */
+ ble_error_t updateField(DataType_t advDataType, const uint8_t *payload, uint8_t len, uint8_t* field)
+ {
+ ble_error_t result = BLE_ERROR_BUFFER_OVERFLOW;
+ uint8_t dataLength = field[0] - 1;
+
+ // new data has same length, do in-order replacement
+ if (len == dataLength) {
+ for (uint8_t idx = 0; idx < dataLength; idx++) {
+ field[2 + idx] = payload[idx];
+ }
+
+ result = BLE_ERROR_NONE;
+ } else {
+ // check if data fits
+ if ((_payloadLen - dataLength + len) <= GAP_ADVERTISING_DATA_MAX_PAYLOAD) {
+
+ // remove old field
+ while ((field + dataLength + 2) < &_payload[_payloadLen]) {
+ *field = field[dataLength + 2];
+ field++;
+ }
+
+ // reduce length
+ _payloadLen -= dataLength + 2;
+
+ // add new field
+ result = appendField(advDataType, payload, len);
+ }
+ }
+
+ return result;
+ }
+
uint8_t _payload[GAP_ADVERTISING_DATA_MAX_PAYLOAD];
uint8_t _payloadLen;
uint16_t _appearance;
--- a/ble/GattClient.h Wed Apr 06 19:13:52 2016 +0100
+++ b/ble/GattClient.h Wed Apr 06 19:13:54 2016 +0100
@@ -20,6 +20,7 @@
#include "Gap.h"
#include "GattAttribute.h"
#include "ServiceDiscovery.h"
+#include "CharacteristicDescriptorDiscovery.h"
#include "GattCallbackParamTypes.h"
@@ -41,6 +42,9 @@
typedef FunctionPointerWithContext<const GattHVXCallbackParams*> HVXCallback_t;
typedef CallChainOfFunctionPointersWithContext<const GattHVXCallbackParams*> HVXCallbackChain_t;
+ typedef FunctionPointerWithContext<const GattClient *> GattClientShutdownCallback_t;
+ typedef CallChainOfFunctionPointersWithContext<const GattClient *> GattClientShutdownCallbackChain_t;
+
/*
* The following functions are meant to be overridden in the platform-specific sub-class.
*/
@@ -216,8 +220,8 @@
* Initiate a GATT Client write procedure.
*
* @param[in] cmd
- * Command can be either a write-request (which generates a
- * matching response from the peripheral), or a write-command
+ * Command can be either a write-request (which generates a
+ * matching response from the peripheral), or a write-command
* (which doesn't require the connected peer to respond).
* @param[in] connHandle
* Connection handle.
@@ -246,8 +250,8 @@
/* Event callback handlers. */
public:
/**
- * Set up a callback for read response events.
- * It is possible to remove registered callbacks using
+ * Set up a callback for read response events.
+ * It is possible to remove registered callbacks using
* onDataRead().detach(callbackToRemove)
*/
void onDataRead(ReadCallback_t callback) {
@@ -257,7 +261,7 @@
/**
* @brief provide access to the callchain of read callbacks
* It is possible to register callbacks using onDataRead().add(callback);
- * It is possible to unregister callbacks using onDataRead().detach(callback)
+ * It is possible to unregister callbacks using onDataRead().detach(callback)
* @return The read callbacks chain
*/
ReadCallbackChain_t& onDataRead() {
@@ -266,7 +270,7 @@
/**
* Set up a callback for write response events.
- * It is possible to remove registered callbacks using
+ * It is possible to remove registered callbacks using
* onDataWritten().detach(callbackToRemove).
* @Note: Write commands (issued using writeWoResponse) don't generate a response.
*/
@@ -277,10 +281,10 @@
/**
* @brief provide access to the callchain of data written callbacks
* It is possible to register callbacks using onDataWritten().add(callback);
- * It is possible to unregister callbacks using onDataWritten().detach(callback)
+ * It is possible to unregister callbacks using onDataWritten().detach(callback)
* @return The data written callbacks chain
*/
- WriteCallbackChain_t& onDataWritten() {
+ WriteCallbackChain_t& onDataWritten() {
return onDataWriteCallbackChain;
}
@@ -305,6 +309,59 @@
}
/**
+ * @brief launch discovery of descriptors for a given characteristic
+ * @details This function will discover all descriptors available for a
+ * specific characteristic.
+ *
+ * @param characteristic[in] The characteristic targeted by this discovery
+ * procedure
+ * @param discoveryCallback[in] User function called each time a descriptor
+ * is found during the procedure.
+ * @param terminationCallback[in] User provided function which will be called
+ * once the discovery procedure is terminating. This will get called when all
+ * the descriptors have been discovered or if an error occur during the discovery
+ * procedure.
+ *
+ * @return
+ * BLE_ERROR_NONE if characteristic descriptor discovery is launched
+ * successfully; else an appropriate error.
+ */
+ virtual ble_error_t discoverCharacteristicDescriptors(
+ const DiscoveredCharacteristic& characteristic,
+ const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& discoveryCallback,
+ const CharacteristicDescriptorDiscovery::TerminationCallback_t& terminationCallback) {
+ (void) characteristic;
+ (void) discoveryCallback;
+ (void) terminationCallback;
+ /* Requesting action from porter(s): override this API if this capability is supported. */
+ return BLE_ERROR_NOT_IMPLEMENTED;
+ }
+
+ /**
+ * @brief Indicate if the discovery of characteristic descriptors is active for a given characteristic
+ * or not.
+ * @param characteristic[in] The characteristic concerned by the descriptors discovery.
+ * @return true if a descriptors discovery is active for the characteristic in input; otherwise false.
+ */
+ virtual bool isCharacteristicDescriptorDiscoveryActive(const DiscoveredCharacteristic& characteristic) const
+ {
+ (void) characteristic;
+ return false; /* Requesting action from porter(s): override this API if this capability is supported. */
+ }
+
+ /**
+ * @brief Terminate an ongoing characteristic descriptor discovery.
+ * @detail This should result in an invocation of the TerminationCallback if
+ * the characteristic descriptor discovery is active.
+ * @param characteristic[in] The characteristic on which the running descriptors
+ * discovery should be stopped.
+ */
+ virtual void terminateCharacteristicDescriptorDiscovery(const DiscoveredCharacteristic& characteristic) {
+ /* Requesting action from porter(s): override this API if this capability is supported. */
+ (void) characteristic;
+ }
+
+ /**
* Set up a callback for when the GATT client receives an update event
* corresponding to a change in the value of a characteristic on the remote
* GATT server.
@@ -314,17 +371,74 @@
onHVXCallbackChain.add(callback);
}
+ /**
+ * Setup a callback to be invoked to notify the user application that the
+ * GattClient 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 GattClient 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 GattClientShutdownCallback_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
+ */
+ GattClientShutdownCallbackChain_t& onShutdown() {
+ return shutdownCallChain;
+ }
/**
* @brief provide access to the callchain of HVX callbacks
* It is possible to register callbacks using onHVX().add(callback);
- * It is possible to unregister callbacks using onHVX().detach(callback)
+ * It is possible to unregister callbacks using onHVX().detach(callback)
* @return The HVX callbacks chain
*/
- HVXCallbackChain_t& onHVX() {
+ HVXCallbackChain_t& onHVX() {
return onHVXCallbackChain;
}
+public:
+ /**
+ * Notify all registered onShutdown callbacks that the GattClient is
+ * about to be shutdown and clear all GattClient 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 GattClient members. This shall be achieved
+ * by a call to GattClient::reset() from the sub-class' reset()
+ * implementation.
+ *
+ * @return BLE_ERROR_NONE on success.
+ */
+ virtual ble_error_t reset(void) {
+ /* Notify that the instance is about to shutdown */
+ shutdownCallChain.call(this);
+ shutdownCallChain.clear();
+
+ onDataReadCallbackChain.clear();
+ onDataWriteCallbackChain.clear();
+ onHVXCallbackChain.clear();
+
+ return BLE_ERROR_NONE;
+ }
+
protected:
GattClient() {
/* Empty */
@@ -347,9 +461,10 @@
}
protected:
- ReadCallbackChain_t onDataReadCallbackChain;
- WriteCallbackChain_t onDataWriteCallbackChain;
- HVXCallbackChain_t onHVXCallbackChain;
+ ReadCallbackChain_t onDataReadCallbackChain;
+ WriteCallbackChain_t onDataWriteCallbackChain;
+ HVXCallbackChain_t onHVXCallbackChain;
+ GattClientShutdownCallbackChain_t shutdownCallChain;
private:
/* Disallow copy and assignment. */
--- a/ble/GattServer.h Wed Apr 06 19:13:52 2016 +0100
+++ b/ble/GattServer.h Wed Apr 06 19:13:54 2016 +0100
@@ -26,17 +26,19 @@
class GattServer {
public:
-
/* Event callback handlers. */
typedef FunctionPointerWithContext<unsigned> DataSentCallback_t;
typedef CallChainOfFunctionPointersWithContext<unsigned> DataSentCallbackChain_t;
typedef FunctionPointerWithContext<const GattWriteCallbackParams*> DataWrittenCallback_t;
- typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> DataWrittenCallbackChain_t;
+ typedef CallChainOfFunctionPointersWithContext<const GattWriteCallbackParams*> DataWrittenCallbackChain_t;
typedef FunctionPointerWithContext<const GattReadCallbackParams*> DataReadCallback_t;
typedef CallChainOfFunctionPointersWithContext<const GattReadCallbackParams *> DataReadCallbackChain_t;
+ typedef FunctionPointerWithContext<const GattServer *> GattServerShutdownCallback_t;
+ typedef CallChainOfFunctionPointersWithContext<const GattServer *> GattServerShutdownCallbackChain_t;
+
typedef FunctionPointerWithContext<GattAttribute::Handle_t> EventCallback_t;
protected:
@@ -254,9 +256,9 @@
}
/**
- * @brief get the callback chain called when the event DATA_EVENT is triggered.
+ * @brief get the callback chain called when the event DATA_EVENT is triggered.
*/
- DataSentCallbackChain_t& onDataSent() {
+ DataSentCallbackChain_t& onDataSent() {
return dataSentCallChain;
}
@@ -274,7 +276,7 @@
*
* @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 onDataWritten().detach(callback)
*/
void onDataWritten(const DataWrittenCallback_t& callback) {dataWrittenCallChain.add(callback);}
@@ -286,9 +288,9 @@
/**
* @brief provide access to the callchain of data written event callbacks
* It is possible to register callbacks using onDataWritten().add(callback);
- * It is possible to unregister callbacks using onDataWritten().detach(callback)
+ * It is possible to unregister callbacks using onDataWritten().detach(callback)
* @return The data written event callbacks chain
- */
+ */
DataWrittenCallbackChain_t& onDataWritten() {
return dataWrittenCallChain;
}
@@ -335,7 +337,7 @@
/**
* @brief provide access to the callchain of data read event callbacks
* It is possible to register callbacks using onDataRead().add(callback);
- * It is possible to unregister callbacks using onDataRead().detach(callback)
+ * It is possible to unregister callbacks using onDataRead().detach(callback)
* @return The data read event callbacks chain
*/
DataReadCallbackChain_t& onDataRead() {
@@ -343,6 +345,38 @@
}
/**
+ * Setup a callback to be invoked to notify the user application that the
+ * GattServer 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 GattServer 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 GattServerShutdownCallback_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
+ */
+ GattServerShutdownCallbackChain_t& onShutdown() {
+ return shutdownCallChain;
+ }
+
+ /**
* Set up a callback for when notifications or indications are enabled for a
* characteristic on the local GATT server.
*/
@@ -396,17 +430,50 @@
dataSentCallChain.call(count);
}
+public:
+ /**
+ * Notify all registered onShutdown callbacks that the GattServer is
+ * about to be shutdown and clear all GattServer 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 GattServer members. This shall be achieved
+ * by a call to GattServer::reset() from the sub-class' reset()
+ * implementation.
+ *
+ * @return BLE_ERROR_NONE on success.
+ */
+ virtual ble_error_t reset(void) {
+ /* Notify that the instance is about to shutdown */
+ shutdownCallChain.call(this);
+ shutdownCallChain.clear();
+
+ serviceCount = 0;
+ characteristicCount = 0;
+
+ dataSentCallChain.clear();
+ dataWrittenCallChain.clear();
+ dataReadCallChain.clear();
+ updatesEnabledCallback = NULL;
+ updatesDisabledCallback = NULL;
+ confirmationReceivedCallback = NULL;
+
+ return BLE_ERROR_NONE;
+ }
+
protected:
uint8_t serviceCount;
uint8_t characteristicCount;
private:
- DataSentCallbackChain_t dataSentCallChain;
- DataWrittenCallbackChain_t dataWrittenCallChain;
- DataReadCallbackChain_t dataReadCallChain;
- EventCallback_t updatesEnabledCallback;
- EventCallback_t updatesDisabledCallback;
- EventCallback_t confirmationReceivedCallback;
+ DataSentCallbackChain_t dataSentCallChain;
+ DataWrittenCallbackChain_t dataWrittenCallChain;
+ DataReadCallbackChain_t dataReadCallChain;
+ GattServerShutdownCallbackChain_t shutdownCallChain;
+ EventCallback_t updatesEnabledCallback;
+ EventCallback_t updatesDisabledCallback;
+ EventCallback_t confirmationReceivedCallback;
private:
/* Disallow copy and assignment. */
--- a/ble/SecurityManager.h Wed Apr 06 19:13:52 2016 +0100
+++ b/ble/SecurityManager.h Wed Apr 06 19:13:54 2016 +0100
@@ -20,6 +20,7 @@
#include <stdint.h>
#include "Gap.h"
+#include "CallChainOfFunctionPointersWithContext.h"
class SecurityManager {
public:
@@ -82,6 +83,9 @@
typedef void (*LinkSecuredCallback_t)(Gap::Handle_t handle, SecurityMode_t securityMode);
typedef void (*PasskeyDisplayCallback_t)(Gap::Handle_t handle, const Passkey_t passkey);
+ typedef FunctionPointerWithContext<const SecurityManager *> SecurityManagerShutdownCallback_t;
+ typedef CallChainOfFunctionPointersWithContext<const SecurityManager *> SecurityManagerShutdownCallbackChain_t;
+
/*
* The following functions are meant to be overridden in the platform-specific sub-class.
*/
@@ -120,7 +124,7 @@
* @param[in] connectionHandle Handle to identify the connection.
* @param[out] securityStatusP Security status.
*
- * @return BLE_SUCCESS or appropriate error code indicating the failure reason.
+ * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
*/
virtual ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, LinkSecurityStatus_t *securityStatusP) {
/* Avoid compiler warnings about unused variables. */
@@ -131,6 +135,23 @@
}
/**
+ * Set the security mode on a connection. Useful for elevating the security mode
+ * once certain conditions are met, e.g., a particular service is found.
+ *
+ * @param[in] connectionHandle Handle to identify the connection.
+ * @param[in] securityMode Requested security mode.
+ *
+ * @return BLE_ERROR_NONE or appropriate error code indicating the failure reason.
+ */
+ virtual ble_error_t setLinkSecurity(Gap::Handle_t connectionHandle, SecurityMode_t securityMode) {
+ /* Avoid compiler warnings about unused variables. */
+ (void)connectionHandle;
+ (void)securityMode;
+
+ return BLE_ERROR_NOT_IMPLEMENTED;
+ }
+
+ /**
* Delete all peer device context and all related bonding information from
* the database within the security manager.
*
@@ -145,6 +166,38 @@
/* Event callback handlers. */
public:
/**
+ * Setup a callback to be invoked to notify the user application that the
+ * SecurityManager 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 SecurityManager 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 SecurityManagerShutdownCallback_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
+ */
+ SecurityManagerShutdownCallbackChain_t& onShutdown() {
+ return shutdownCallChain;
+ }
+
+ /**
* To indicate that a security procedure for the link has started.
*/
virtual void onSecuritySetupInitiated(SecuritySetupInitiatedCallback_t callback) {securitySetupInitiatedCallback = callback;}
@@ -214,12 +267,43 @@
/* empty */
}
+public:
+ /**
+ * Notify all registered onShutdown callbacks that the SecurityManager is
+ * about to be shutdown and clear all SecurityManager 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 SecurityManager members. This shall be
+ * achieved by a call to SecurityManager::reset() from the sub-class'
+ * reset() implementation.
+ *
+ * @return BLE_ERROR_NONE on success.
+ */
+ virtual ble_error_t reset(void) {
+ /* Notify that the instance is about to shutdown */
+ shutdownCallChain.call(this);
+ shutdownCallChain.clear();
+
+ securitySetupInitiatedCallback = NULL;
+ securitySetupCompletedCallback = NULL;
+ linkSecuredCallback = NULL;
+ securityContextStoredCallback = NULL;
+ passkeyDisplayCallback = NULL;
+
+ return BLE_ERROR_NONE;
+ }
+
protected:
SecuritySetupInitiatedCallback_t securitySetupInitiatedCallback;
SecuritySetupCompletedCallback_t securitySetupCompletedCallback;
LinkSecuredCallback_t linkSecuredCallback;
HandleSpecificEvent_t securityContextStoredCallback;
PasskeyDisplayCallback_t passkeyDisplayCallback;
+
+private:
+ SecurityManagerShutdownCallbackChain_t shutdownCallChain;
};
#endif /*__SECURITY_MANAGER_H__*/
\ No newline at end of file
--- a/ble/ServiceDiscovery.h Wed Apr 06 19:13:52 2016 +0100
+++ b/ble/ServiceDiscovery.h Wed Apr 06 19:13:54 2016 +0100
@@ -132,6 +132,27 @@
*/
virtual void onTermination(TerminationCallback_t callback) = 0;
+ /**
+ * Clear all ServiceDiscovery 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 ServiceDiscovery members. This shall be
+ * achieved by a call to ServiceDiscovery::reset() from the sub-class'
+ * reset() implementation.
+ *
+ * @return BLE_ERROR_NONE on success.
+ */
+ virtual ble_error_t reset(void) {
+ connHandle = 0;
+ matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
+ serviceCallback = NULL;
+ matchingCharacteristicUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
+ characteristicCallback = NULL;
+
+ return BLE_ERROR_NONE;
+ }
+
protected:
Gap::Handle_t connHandle; /**< Connection handle as provided by the SoftDevice. */
UUID matchingServiceUUID;
--- a/ble/blecommon.h Wed Apr 06 19:13:52 2016 +0100
+++ b/ble/blecommon.h Wed Apr 06 19:13:54 2016 +0100
@@ -49,62 +49,6 @@
BLE_UUID_GAP_CHARACTERISTIC_PPCP = 0x2A04, /**< Peripheral Preferred Connection Parameters Characteristic. */
};
-/*! Bluetooth appearance values.
- * @note Retrieved from http://developer.bluetooth.org/gatt/characteristics/Pages/CharacteristicViewer.aspx?u=org.bluetooth.characteristic.gap.appearance.xml
- */
-enum {
- BLE_APPEARANCE_UNKNOWN = 0, /**< Unknown. */
- BLE_APPEARANCE_GENERIC_PHONE = 64, /**< Generic Phone. */
- BLE_APPEARANCE_GENERIC_COMPUTER = 128, /**< Generic Computer. */
- BLE_APPEARANCE_GENERIC_WATCH = 192, /**< Generic Watch. */
- BLE_APPEARANCE_WATCH_SPORTS_WATCH = 193, /**< Watch: Sports Watch. */
- BLE_APPEARANCE_GENERIC_CLOCK = 256, /**< Generic Clock. */
- BLE_APPEARANCE_GENERIC_DISPLAY = 320, /**< Generic Display. */
- BLE_APPEARANCE_GENERIC_REMOTE_CONTROL = 384, /**< Generic Remote Control. */
- BLE_APPEARANCE_GENERIC_EYE_GLASSES = 448, /**< Generic Eye-glasses. */
- BLE_APPEARANCE_GENERIC_TAG = 512, /**< Generic Tag. */
- BLE_APPEARANCE_GENERIC_KEYRING = 576, /**< Generic Keyring. */
- BLE_APPEARANCE_GENERIC_MEDIA_PLAYER = 640, /**< Generic Media Player. */
- BLE_APPEARANCE_GENERIC_BARCODE_SCANNER = 704, /**< Generic Barcode Scanner. */
- BLE_APPEARANCE_GENERIC_THERMOMETER = 768, /**< Generic Thermometer. */
- BLE_APPEARANCE_THERMOMETER_EAR = 769, /**< Thermometer: Ear. */
- BLE_APPEARANCE_GENERIC_HEART_RATE_SENSOR = 832, /**< Generic Heart Rate Sensor. */
- BLE_APPEARANCE_HEART_RATE_SENSOR_HEART_RATE_BELT = 833, /**< Heart Rate Sensor: Heart Rate Belt. */
- BLE_APPEARANCE_GENERIC_BLOOD_PRESSURE = 896, /**< Generic Blood Pressure. */
- BLE_APPEARANCE_BLOOD_PRESSURE_ARM = 897, /**< Blood Pressure: Arm. */
- BLE_APPEARANCE_BLOOD_PRESSURE_WRIST = 898, /**< Blood Pressure: Wrist. */
- BLE_APPEARANCE_GENERIC_HID = 960, /**< Human Interface Device (HID). */
- BLE_APPEARANCE_HID_KEYBOARD = 961, /**< Keyboard (HID subtype). */
- BLE_APPEARANCE_HID_MOUSE = 962, /**< Mouse (HID subtype). */
- BLE_APPEARANCE_HID_JOYSTICK = 963, /**< Joystick (HID subtype). */
- BLE_APPEARANCE_HID_GAMEPAD = 964, /**< Gamepad (HID subtype). */
- BLE_APPEARANCE_HID_DIGITIZERSUBTYPE = 965, /**< Digitizer Tablet (HID subtype). */
- BLE_APPEARANCE_HID_CARD_READER = 966, /**< Card Reader (HID subtype). */
- BLE_APPEARANCE_HID_DIGITAL_PEN = 967, /**< Digital Pen (HID subtype). */
- BLE_APPEARANCE_HID_BARCODE = 968, /**< Barcode Scanner (HID subtype). */
- BLE_APPEARANCE_GENERIC_GLUCOSE_METER = 1024, /**< Generic Glucose Meter. */
- BLE_APPEARANCE_GENERIC_RUNNING_WALKING_SENSOR = 1088, /**< Generic Running Walking Sensor. */
- BLE_APPEARANCE_RUNNING_WALKING_SENSOR_IN_SHOE = 1089, /**< Running Walking Sensor: In-Shoe. */
- BLE_APPEARANCE_RUNNING_WALKING_SENSOR_ON_SHOE = 1090, /**< Running Walking Sensor: On-Shoe. */
- BLE_APPEARANCE_RUNNING_WALKING_SENSOR_ON_HIP = 1091, /**< Running Walking Sensor: On-Hip. */
- BLE_APPEARANCE_GENERIC_CYCLING = 1152, /**< Generic Cycling. */
- BLE_APPEARANCE_CYCLING_CYCLING_COMPUTER = 1153, /**< Cycling: Cycling Computer. */
- BLE_APPEARANCE_CYCLING_SPEED_SENSOR = 1154, /**< Cycling: Speed Sensor. */
- BLE_APPEARANCE_CYCLING_CADENCE_SENSOR = 1155, /**< Cycling: Cadence Sensor. */
- BLE_APPEARANCE_CYCLING_POWER_SENSOR = 1156, /**< Cycling: Power Sensor. */
- BLE_APPEARANCE_CYCLING_SPEED_CADENCE_SENSOR = 1157, /**< Cycling: Speed and Cadence Sensor. */
- BLE_APPEARANCE_GENERIC_PULSE_OXIMETER = 3136, /**< Generic Pulse Oximeter. */
- BLE_APPEARANCE_PULSE_OXIMETER_FINGERTIP = 3137, /**< Fingertip (Pulse Oximeter subtype). */
- BLE_APPEARANCE_PULSE_OXIMETER_WRIST_WORN = 3138, /**< Wrist Worn (Pulse Oximeter subtype). */
- BLE_APPEARANCE_GENERIC_WEIGHT_SCALE = 3200, /**< Generic Weight Scale. */
- BLE_APPEARANCE_GENERIC_OUTDOOR_SPORTS_ACT = 5184, /**< Generic Outdoor Sports Activity. */
- BLE_APPEARANCE_OUTDOOR_SPORTS_ACT_LOC_DISP = 5185, /**< Location Display Device (Outdoor Sports Activity subtype). */
- BLE_APPEARANCE_OUTDOOR_SPORTS_ACT_LOC_AND_NAV_DISP = 5186, /**< Location and Navigation Display Device (Outdoor Sports Activity subtype). */
- BLE_APPEARANCE_OUTDOOR_SPORTS_ACT_LOC_POD = 5187, /**< Location Pod (Outdoor Sports Activity subtype). */
- BLE_APPEARANCE_OUTDOOR_SPORTS_ACT_LOC_AND_NAV_POD = 5188, /**< Location and Navigation Pod (Outdoor Sports Activity subtype). */
-};
-
-
/*! @brief Error codes for the BLE API. */
enum ble_error_t {
BLE_ERROR_NONE = 0, /**< No error. */
@@ -119,6 +63,7 @@
BLE_ERROR_INITIALIZATION_INCOMPLETE = 9,
BLE_ERROR_ALREADY_INITIALIZED = 10,
BLE_ERROR_UNSPECIFIED = 11, /**< Unknown error. */
+ BLE_ERROR_INTERNAL_STACK_FAILURE = 12, /**< The platform-specific stack failed */
};
/** @brief Default MTU size. */
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ble/deprecate.h Wed Apr 06 19:13:54 2016 +0100 @@ -0,0 +1,26 @@ +/* mbed Microcontroller Library + * Copyright (c) 2006-2013 ARM Limited + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +#ifndef __DEPRECATE_H__ +#define __DEPRECATE_H__ + +#ifdef YOTTA_CFG_MBED_OS + #include "compiler-polyfill/attributes.h" +#else + #define __deprecated_message(msg) +#endif + +#endif \ No newline at end of file
--- a/module.json Wed Apr 06 19:13:52 2016 +0100
+++ b/module.json Wed Apr 06 19:13:54 2016 +0100
@@ -1,6 +1,6 @@
{
"name": "ble",
- "version": "2.1.11",
+ "version": "2.4.0",
"description": "The BLE module offers a high level abstraction for using Bluetooth Low Energy on multiple platforms.",
"keywords": [
"Bluetooth",
@@ -23,10 +23,10 @@
"dependencies": {},
"targetDependencies": {
"st-ble-shield": {
- "x-nucleo-idb0xa1": "ARMmbed/ble-x-nucleo-idb0xa1"
+ "x-nucleo-idb0xa1": "^2.0.0"
},
"nrf51822": {
- "ble-nrf51822": "^2.1.3"
+ "ble-nrf51822": "^2.2.8"
},
"cordio": {
"ble-wicentric": "~0.0.4"
@@ -35,7 +35,8 @@
"mbed-classic": "~0.0.1"
},
"mbed-os": {
- "mbed-drivers": "*"
+ "mbed-drivers": "*",
+ "compiler-polyfill": "^1.2.1"
}
}
}
\ No newline at end of file
--- a/source/BLE.cpp Wed Apr 06 19:13:52 2016 +0100
+++ b/source/BLE.cpp Wed Apr 06 19:13:54 2016 +0100
@@ -131,7 +131,6 @@
ble_error_t BLE::shutdown(void)
{
- clearAdvertisingPayload();
if (!transport) {
error("bad handle to underlying transport");
}
--- a/source/DiscoveredCharacteristic.cpp Wed Apr 06 19:13:52 2016 +0100
+++ b/source/DiscoveredCharacteristic.cpp Wed Apr 06 19:13:54 2016 +0100
@@ -31,29 +31,29 @@
return gattc->read(connHandle, valueHandle, offset);
}
-struct OneShotReadCallback {
- static void launch(GattClient* client, Gap::Handle_t connHandle,
- GattAttribute::Handle_t handle, const GattClient::ReadCallback_t& cb) {
+struct OneShotReadCallback {
+ static void launch(GattClient* client, Gap::Handle_t connHandle,
+ GattAttribute::Handle_t handle, const GattClient::ReadCallback_t& cb) {
OneShotReadCallback* oneShot = new OneShotReadCallback(client, connHandle, handle, cb);
oneShot->attach();
// delete will be made when this callback is called
}
private:
- OneShotReadCallback(GattClient* client, Gap::Handle_t connHandle,
- GattAttribute::Handle_t handle, const GattClient::ReadCallback_t& cb) :
+ OneShotReadCallback(GattClient* client, Gap::Handle_t connHandle,
+ GattAttribute::Handle_t handle, const GattClient::ReadCallback_t& cb) :
_client(client),
_connHandle(connHandle),
- _handle(handle),
- _callback(cb) { }
+ _handle(handle),
+ _callback(cb) { }
- void attach() {
+ void attach() {
_client->onDataRead(makeFunctionPointer(this, &OneShotReadCallback::call));
}
void call(const GattReadCallbackParams* params) {
// verifiy that it is the right characteristic on the right connection
- if (params->connHandle == _connHandle && params->handle == _handle) {
+ if (params->connHandle == _connHandle && params->handle == _handle) {
_callback(params);
_client->onDataRead().detach(makeFunctionPointer(this, &OneShotReadCallback::call));
delete this;
@@ -68,7 +68,7 @@
ble_error_t DiscoveredCharacteristic::read(uint16_t offset, const GattClient::ReadCallback_t& onRead) const {
ble_error_t error = read(offset);
- if (error) {
+ if (error) {
return error;
}
@@ -105,29 +105,29 @@
return gattc->write(GattClient::GATT_OP_WRITE_CMD, connHandle, valueHandle, length, value);
}
-struct OneShotWriteCallback {
- static void launch(GattClient* client, Gap::Handle_t connHandle,
- GattAttribute::Handle_t handle, const GattClient::WriteCallback_t& cb) {
+struct OneShotWriteCallback {
+ static void launch(GattClient* client, Gap::Handle_t connHandle,
+ GattAttribute::Handle_t handle, const GattClient::WriteCallback_t& cb) {
OneShotWriteCallback* oneShot = new OneShotWriteCallback(client, connHandle, handle, cb);
oneShot->attach();
// delete will be made when this callback is called
}
private:
- OneShotWriteCallback(GattClient* client, Gap::Handle_t connHandle,
- GattAttribute::Handle_t handle, const GattClient::WriteCallback_t& cb) :
+ OneShotWriteCallback(GattClient* client, Gap::Handle_t connHandle,
+ GattAttribute::Handle_t handle, const GattClient::WriteCallback_t& cb) :
_client(client),
_connHandle(connHandle),
- _handle(handle),
- _callback(cb) { }
+ _handle(handle),
+ _callback(cb) { }
- void attach() {
+ void attach() {
_client->onDataWritten(makeFunctionPointer(this, &OneShotWriteCallback::call));
}
void call(const GattWriteCallbackParams* params) {
// verifiy that it is the right characteristic on the right connection
- if (params->connHandle == _connHandle && params->handle == _handle) {
+ if (params->connHandle == _connHandle && params->handle == _handle) {
_callback(params);
_client->onDataWritten().detach(makeFunctionPointer(this, &OneShotWriteCallback::call));
delete this;
@@ -142,7 +142,7 @@
ble_error_t DiscoveredCharacteristic::write(uint16_t length, const uint8_t *value, const GattClient::WriteCallback_t& onRead) const {
ble_error_t error = write(length, value);
- if (error) {
+ if (error) {
return error;
}
@@ -151,8 +151,17 @@
return error;
}
-ble_error_t
-DiscoveredCharacteristic::discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID) const
-{
- return BLE_ERROR_NOT_IMPLEMENTED; /* TODO: this needs to be filled in. */
+ble_error_t DiscoveredCharacteristic::discoverDescriptors(
+ const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onCharacteristicDiscovered,
+ const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const {
+
+ if(!gattc) {
+ return BLE_ERROR_INVALID_STATE;
+ }
+
+ ble_error_t err = gattc->discoverCharacteristicDescriptors(
+ *this, onCharacteristicDiscovered, onTermination
+ );
+
+ return err;
}
\ No newline at end of file