ScStw/esp-nimble-cpp
2
0
Fork 0
mirror of https://github.com/h2zero/esp-nimble-cpp.git synced 2024-12-22 19:10:46 +01:00
Code Issues Projects Releases Packages Wiki Activity

[Breaking] Remove deprecated functions/response parameter from un/sub (#76)

Browse source 
Removes the response parameter from remote characterisitc subscrible/unsubscribe functions
as a response is always required for this operation as per BLE specs.

Removes the deprecated functions from remote characteristic/desriptor.

* Update examples/docs.
This commit is contained in:
h2zero 2022-08-26 20:15:25 -06:00 committed by GitHub
parent 2b758e05c7
commit 03b22e53a0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 24 additions and 129 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
docs/Improvements_and_updates.md
View file

@ -96,12 +96,13 @@ struct my_struct{
```
<br/>
`NimBLERemoteCharacteristic::registerForNotify`
Has been **deprecated** as now the internally stored characteristic value is updated when notification/indication is received.
`NimBLERemoteCharacteristic::registerForNotify`
Has been removed.
`NimBLERemoteCharacteristic::subscribe` and `NimBLERemoteCharacteristic::unsubscribe` have been implemented to replace it.
A callback is no longer required to get the most recent value unless timing is important. Instead, the application can call `NimBLERemoteCharacteristic::getValue` to get the last updated value any time.
<br/>
`NimBLERemoteCharacteristic::subscribe` and `NimBLERemoteCharacteristic::unsubscribe` have been implemented to replace it.
The internally stored characteristic value is now updated when notification/indication is recieved. Making a callback no longer required to get the most recent value unless timing is important. Instead, the application can call `NimBLERemoteCharacteristic::getValue` to get the most recent value any time.
<br/>
The `notify_callback` function is now defined as a `std::function` to take advantage of using `std::bind` to specify a class member function for the callback.

12
docs/Migration_guide.md
View file

@ -272,16 +272,16 @@ Also now returns a pointer to `std::vector` instead of `std::map`.
There have been a few changes to the methods in this class:
> `BLERemoteCharacteristic::writeValue` (`NimBLERemoteCharacteristic::writeValue`)
> `BLERemoteCharacteristic::registerForNotify` (`NimBLERemoteCharacteristic::registerForNotify`)
Now return true or false to indicate success or failure so you can choose to disconnect or try again.
Now returns true or false to indicate success or failure so you can choose to disconnect or try again.
<br/>
> `BLERemoteCharacteristic::registerForNotify` (`NimBLERemoteCharacteristic::registerForNotify`)
> `BLERemoteCharacteristic::registerForNotify`
Is now **deprecated**.
> `NimBLERemoteCharacteristic::subscribe`
> `NimBLERemoteCharacteristic::unsubscribe`
Has been removed.
> `NimBLERemoteCharacteristic::subscribe`
> `NimBLERemoteCharacteristic::unsubscribe`
Are the new methods added to replace it.
<br/>

79
src/NimBLERemoteCharacteristic.cpp
View file

@ -440,46 +440,7 @@ NimBLEAttValue NimBLERemoteCharacteristic::getValue(time_t *timestamp) {
}
return m_value;
}
/**
* @brief Read an unsigned 16 bit value
* @return The unsigned 16 bit value.
* @deprecated Use readValue<uint16_t>().
*/
uint16_t NimBLERemoteCharacteristic::readUInt16() {
return readValue<uint16_t>();
} // readUInt16
/**
* @brief Read an unsigned 32 bit value.
* @return the unsigned 32 bit value.
* @deprecated Use readValue<uint32_t>().
*/
uint32_t NimBLERemoteCharacteristic::readUInt32() {
return readValue<uint32_t>();
} // readUInt32
/**
* @brief Read a byte value
* @return The value as a byte
* @deprecated Use readValue<uint8_t>().
*/
uint8_t NimBLERemoteCharacteristic::readUInt8() {
return readValue<uint8_t>();
} // readUInt8
/**
* @brief Read a float value.
* @return the float value.
*/
float NimBLERemoteCharacteristic::readFloat() {
return readValue<float>();
} // readFloat
} // getValue
/**
@ -592,7 +553,7 @@ int NimBLERemoteCharacteristic::onReadCB(uint16_t conn_handle,
xTaskNotifyGive(pTaskData->task);
return rc;
}
} // onReadCB
/**
@ -603,7 +564,7 @@ int NimBLERemoteCharacteristic::onReadCB(uint16_t conn_handle,
* If NULL is provided then no callback is performed.
* @return false if writing to the descriptor failed.
*/
bool NimBLERemoteCharacteristic::setNotify(uint16_t val, notify_callback notifyCallback, bool response) {
bool NimBLERemoteCharacteristic::setNotify(uint16_t val, notify_callback notifyCallback) {
NIMBLE_LOGD(LOG_TAG, ">> setNotify(): %s, %02x", toString().c_str(), val);
m_notifyCallback = notifyCallback;
@ -615,9 +576,7 @@ bool NimBLERemoteCharacteristic::setNotify(uint16_t val, notify_callback notifyC
}
NIMBLE_LOGD(LOG_TAG, "<< setNotify()");
response = true; // Always write with response as per Bluetooth core specification.
return desc->writeValue((uint8_t *)&val, 2, response);
return desc->writeValue((uint8_t *)&val, 2, true);
} // setNotify
@ -629,11 +588,11 @@ bool NimBLERemoteCharacteristic::setNotify(uint16_t val, notify_callback notifyC
* If NULL is provided then no callback is performed.
* @return false if writing to the descriptor failed.
*/
bool NimBLERemoteCharacteristic::subscribe(bool notifications, notify_callback notifyCallback, bool response) {
bool NimBLERemoteCharacteristic::subscribe(bool notifications, notify_callback notifyCallback) {
if(notifications) {
return setNotify(0x01, notifyCallback, response);
return setNotify(0x01, notifyCallback);
} else {
return setNotify(0x02, notifyCallback, response);
return setNotify(0x02, notifyCallback);
}
} // subscribe
@ -643,31 +602,11 @@ bool NimBLERemoteCharacteristic::subscribe(bool notifications, notify_callback n
* @param [in] response bool if true, require a write response from the descriptor write operation.
* @return false if writing to the descriptor failed.
*/
bool NimBLERemoteCharacteristic::unsubscribe(bool response) {
return setNotify(0x00, nullptr, response);
bool NimBLERemoteCharacteristic::unsubscribe() {
return setNotify(0x00, nullptr);
} // unsubscribe
/**
* @brief backward-compatibility method for subscribe/unsubscribe notifications/indications
* @param [in] notifyCallback A callback to be invoked for a notification. If NULL is provided then we
* will unregister for notifications.
* @param [in] notifications If true, register for notifications, false register for indications.
* @param [in] response If true, require a write response from the descriptor write operation.
* @return true if successful.
* @deprecated Use subscribe() / unsubscribe() instead.
*/
bool NimBLERemoteCharacteristic::registerForNotify(notify_callback notifyCallback, bool notifications, bool response) {
bool success;
if(notifyCallback != nullptr) {
success = subscribe(notifications, notifyCallback, response);
} else {
success = unsubscribe(response);
}
return success;
} // registerForNotify
/**
* @brief Delete the descriptors in the descriptor vector.
* @details We maintain a vector called m_descriptorVector that contains pointers to NimBLERemoteDescriptors

17
src/NimBLERemoteCharacteristic.h
View file

@ -64,21 +64,10 @@ public:
NimBLEAttValue readValue(time_t *timestamp = nullptr);
std::string toString();
NimBLERemoteService* getRemoteService();
uint8_t readUInt8() __attribute__ ((deprecated("Use template readValue<uint8_t>()")));
uint16_t readUInt16() __attribute__ ((deprecated("Use template readValue<uint16_t>()")));
uint32_t readUInt32() __attribute__ ((deprecated("Use template readValue<uint32_t>()")));
float readFloat() __attribute__ ((deprecated("Use template readValue<float>()")));
NimBLEAttValue getValue(time_t *timestamp = nullptr);
bool subscribe(bool notifications = true,
notify_callback notifyCallback = nullptr,
bool response = true);
bool unsubscribe(bool response = true);
bool registerForNotify(notify_callback notifyCallback,
bool notifications = true,
bool response = true)
__attribute__ ((deprecated("Use subscribe()/unsubscribe()")));
notify_callback notifyCallback = nullptr);
bool unsubscribe();
bool writeValue(const uint8_t* data,
size_t length,
bool response = false);
@ -160,7 +149,7 @@ private:
friend class NimBLERemoteDescriptor;
// Private member functions
bool setNotify(uint16_t val, notify_callback notifyCallback = nullptr, bool response = true);
bool setNotify(uint16_t val, notify_callback notifyCallback = nullptr);
bool retrieveDescriptors(const NimBLEUUID *uuid_filter = nullptr);
static int onReadCB(uint16_t conn_handle, const struct ble_gatt_error *error,
struct ble_gatt_attr *attr, void *arg);

30
src/NimBLERemoteDescriptor.cpp
View file

@ -80,36 +80,6 @@ NimBLEUUID NimBLERemoteDescriptor::getUUID() {
} // getUUID
/**
* @brief Read a byte value
* @return The value as a byte
* @deprecated Use readValue<uint8_t>().
*/
uint8_t NimBLERemoteDescriptor::readUInt8() {
return readValue<uint8_t>();
} // readUInt8
/**
* @brief Read an unsigned 16 bit value
* @return The unsigned 16 bit value.
* @deprecated Use readValue<uint16_t>().
*/
uint16_t NimBLERemoteDescriptor::readUInt16() {
return readValue<uint16_t>();
} // readUInt16
/**
* @brief Read an unsigned 32 bit value.
* @return the unsigned 32 bit value.
* @deprecated Use readValue<uint32_t>().
*/
uint32_t NimBLERemoteDescriptor::readUInt32() {
return readValue<uint32_t>();
} // readUInt32
/**
* @brief Read the value of the remote descriptor.
* @return The value of the remote descriptor.

4
src/NimBLERemoteDescriptor.h
View file

@ -30,10 +30,6 @@ public:
NimBLERemoteCharacteristic* getRemoteCharacteristic();
NimBLEUUID getUUID();
NimBLEAttValue readValue();
uint8_t readUInt8() __attribute__ ((deprecated("Use template readValue<uint8_t>()")));
uint16_t readUInt16() __attribute__ ((deprecated("Use template readValue<uint16_t>()")));
uint32_t readUInt32() __attribute__ ((deprecated("Use template readValue<uint32_t>()")));
std::string toString(void);
bool writeValue(const uint8_t* data, size_t length, bool response = false);
bool writeValue(const std::vector<uint8_t>& v, bool response = false);