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

Merge pull request #105 from pan-/descriptorDiscovery

Browse source 
Characteristic descriptor discovery
This commit is contained in:
Vincent Coubard 2015-12-23 12:24:57 +00:00
commit 0e70683f81
5 changed files with 465 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

99
ble/CharacteristicDescriptorDiscovery.h Normal file
View file

@ -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__

215
ble/DiscoveredCharacteristic.h
View file

@ -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 @@ public:
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 @@ public:
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 @@ public:
*/
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 @@ public:
/**
* 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 @@ public:
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 @@ protected:
Properties_t props;
GattAttribute::Handle_t declHandle;
GattAttribute::Handle_t valueHandle;
GattAttribute::Handle_t lastHandle;
Gap::Handle_t connHandle;
};

111
ble/DiscoveredCharacteristicDescriptor.h Normal file
View file

@ -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__*/

74
ble/GattClient.h
View file

@ -20,6 +20,7 @@
#include "Gap.h"
#include "GattAttribute.h"
#include "ServiceDiscovery.h"
#include "CharacteristicDescriptorDiscovery.h"
#include "GattCallbackParamTypes.h"
@ -219,8 +220,8 @@ public:
* 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.
@ -249,8 +250,8 @@ public:
/* 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) {
@ -260,7 +261,7 @@ public:
/**
* @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() {
@ -269,7 +270,7 @@ public:
/**
* 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.
*/
@ -280,10 +281,10 @@ public:
/**
* @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;
}
@ -307,6 +308,59 @@ public:
/* Requesting action from porters: override this API if this capability is supported. */
}
/**
* @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
@ -352,10 +406,10 @@ public:
/**
* @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;
}

19
source/DiscoveredCharacteristic.cpp
View file

@ -151,12 +151,17 @@ ble_error_t DiscoveredCharacteristic::write(uint16_t length, const uint8_t *valu
return error;
}
ble_error_t
DiscoveredCharacteristic::discoverDescriptors(DescriptorCallback_t callback, const UUID &matchingUUID) const
{
/* Avoid compiler warnings */
(void) callback;
(void) matchingUUID;
ble_error_t DiscoveredCharacteristic::discoverDescriptors(
const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& onCharacteristicDiscovered,
const CharacteristicDescriptorDiscovery::TerminationCallback_t& onTermination) const {
return BLE_ERROR_NOT_IMPLEMENTED; /* TODO: this needs to be filled in. */
if(!gattc) {
return BLE_ERROR_INVALID_STATE;
}
ble_error_t err = gattc->discoverCharacteristicDescriptors(
*this, onCharacteristicDiscovered, onTermination
);
return err;
}