From ca8a7c56ac1c12cf6e3ea0d5ce71ad4589d61978 Mon Sep 17 00:00:00 2001 From: h2zero <32826625+h2zero@users.noreply.github.com> Date: Fri, 26 Aug 2022 20:40:21 -0600 Subject: [PATCH] [Breaking] Remove extra notification status from onStatus callback. (#80) Removes the unnecessary NimBLECharacteristicCallbacks::Status enum and callback parameter from NimBLECharacteristic::onStatus. This was maintained for compatibility with the Arduino BLE library and is not necessary as the return code from the stack is also provided. * Update examples/docs. --- docs/Migration_guide.md | 2 ++ examples/Advanced/NimBLE_Server/main/main.cpp | 32 +++++++++++++++---- src/NimBLECharacteristic.cpp | 7 ++-- src/NimBLECharacteristic.h | 19 +---------- src/NimBLEServer.cpp | 23 ++----------- 5 files changed, 35 insertions(+), 48 deletions(-) diff --git a/docs/Migration_guide.md b/docs/Migration_guide.md index abeaa13..50d640a 100644 --- a/docs/Migration_guide.md +++ b/docs/Migration_guide.md @@ -116,6 +116,8 @@ BLECharacteristic *pCharacteristic = pService->createCharacteristic( `BLECharacteristicCallbacks` (`NimBLECharacteristicCallbacks`) has a new method `NimBLECharacteristicCallbacks::onSubscribe` which is called when a client subscribes to notifications/indications. +`NimBLECharacteristicCallbacks::onStatus` (`NimBLECharacteristicCallbacks::onStatus`) has had the status parameter removed as it was unnecessary since the status code from the BLE stack was also provided. The status code for success is 0 for notifications and BLE_HS_EDONE for indications, any other value is an error. + **Note:** All callback methods have default implementations which allows the application to implement only the methods applicable.
diff --git a/examples/Advanced/NimBLE_Server/main/main.cpp b/examples/Advanced/NimBLE_Server/main/main.cpp index b8c4bb6..c123183 100644 --- a/examples/Advanced/NimBLE_Server/main/main.cpp +++ b/examples/Advanced/NimBLE_Server/main/main.cpp @@ -86,6 +86,7 @@ class CharacteristicCallbacks: public NimBLECharacteristicCallbacks { pCharacteristic->getUUID().toString().c_str(), pCharacteristic->getValue().c_str()); }; + /** Called before notification or indication is sent, * the value can be changed here before sending if desired. */ @@ -94,21 +95,38 @@ class CharacteristicCallbacks: public NimBLECharacteristicCallbacks { }; - /** The status returned in status is defined in NimBLECharacteristic.h. + /** * The value returned in code is the NimBLE host return code. */ - void onStatus(NimBLECharacteristic* pCharacteristic, Status status, int code) { - printf("Notification/Indication status code: %d , return code: %d, %s\n", - status, - code, - NimBLEUtils::returnCodeToString(code)); + void onStatus(NimBLECharacteristic* pCharacteristic, int code) { + printf("Notification/Indication return code: %d, %s\n", + code, NimBLEUtils::returnCodeToString(code)); + }; + + void onSubscribe(NimBLECharacteristic* pCharacteristic, NimBLEConnInfo& connInfo, uint16_t subValue) { + std::string str = "Client ID: "; + str += connInfo.getConnHandle(); + str += " Address: "; + str += connInfo.getAddress().toString(); + if(subValue == 0) { + str += " Unsubscribed to "; + }else if(subValue == 1) { + str += " Subscribed to notfications for "; + } else if(subValue == 2) { + str += " Subscribed to indications for "; + } else if(subValue == 3) { + str += " Subscribed to notifications and indications for "; + } + str += std::string(pCharacteristic->getUUID()); + + printf("%s\n", str.c_str()); }; }; /** Handler class for descriptor actions */ class DescriptorCallbacks : public NimBLEDescriptorCallbacks { void onWrite(NimBLEDescriptor* pDescriptor) { - std::string dscVal((char*)pDescriptor->getValue(), pDescriptor->getLength()); + std::string dscVal = pDescriptor->getValue(); printf("Descriptor witten value: %s\n", dscVal.c_str()); }; diff --git a/src/NimBLECharacteristic.cpp b/src/NimBLECharacteristic.cpp index 03d8c55..2aa8080 100644 --- a/src/NimBLECharacteristic.cpp +++ b/src/NimBLECharacteristic.cpp @@ -633,10 +633,11 @@ void NimBLECharacteristicCallbacks::onNotify(NimBLECharacteristic* pCharacterist /** * @brief Callback function to support a Notify/Indicate Status report. * @param [in] pCharacteristic The characteristic that is the source of the event. - * @param [in] s Status of the notification/indication. - * @param [in] code Additional return code from the NimBLE stack. + * @param [in] code Status return code from the NimBLE stack. + * @details The status code for success is 0 for notifications and BLE_HS_EDONE for indications, + * any other value is an error. */ -void NimBLECharacteristicCallbacks::onStatus(NimBLECharacteristic* pCharacteristic, Status s, int code) { +void NimBLECharacteristicCallbacks::onStatus(NimBLECharacteristic* pCharacteristic, int code) { NIMBLE_LOGD("NimBLECharacteristicCallbacks", "onStatus: default"); } // onStatus diff --git a/src/NimBLECharacteristic.h b/src/NimBLECharacteristic.h index 0f84e2d..c5baedc 100644 --- a/src/NimBLECharacteristic.h +++ b/src/NimBLECharacteristic.h @@ -200,30 +200,13 @@ private: */ class NimBLECharacteristicCallbacks { public: - -/** - * @brief An enum to provide the callback the status of the - * notification/indication, implemented for backward compatibility. - * @deprecated To be removed in the future as the NimBLE stack return code is also provided. - */ - typedef enum { - SUCCESS_INDICATE, - SUCCESS_NOTIFY, - ERROR_INDICATE_DISABLED, - ERROR_NOTIFY_DISABLED, - ERROR_GATT, - ERROR_NO_CLIENT, - ERROR_INDICATE_TIMEOUT, - ERROR_INDICATE_FAILURE - }Status; - virtual ~NimBLECharacteristicCallbacks(); virtual void onRead(NimBLECharacteristic* pCharacteristic); virtual void onRead(NimBLECharacteristic* pCharacteristic, ble_gap_conn_desc* desc); virtual void onWrite(NimBLECharacteristic* pCharacteristic); virtual void onWrite(NimBLECharacteristic* pCharacteristic, ble_gap_conn_desc* desc); virtual void onNotify(NimBLECharacteristic* pCharacteristic); - virtual void onStatus(NimBLECharacteristic* pCharacteristic, Status s, int code); + virtual void onStatus(NimBLECharacteristic* pCharacteristic, int code); virtual void onSubscribe(NimBLECharacteristic* pCharacteristic, ble_gap_conn_desc* desc, uint16_t subValue); }; diff --git a/src/NimBLEServer.cpp b/src/NimBLEServer.cpp index 607cc94..4552143 100644 --- a/src/NimBLEServer.cpp +++ b/src/NimBLEServer.cpp @@ -461,31 +461,14 @@ int NimBLEServer::handleGapEvent(struct ble_gap_event *event, void *arg) { return 0; } - NimBLECharacteristicCallbacks::Status statusRC; - if(event->notify_tx.indication) { - if(event->notify_tx.status != 0) { - if(event->notify_tx.status == BLE_HS_EDONE) { - statusRC = NimBLECharacteristicCallbacks::Status::SUCCESS_INDICATE; - } else if(rc == BLE_HS_ETIMEOUT) { - statusRC = NimBLECharacteristicCallbacks::Status::ERROR_INDICATE_TIMEOUT; - } else { - statusRC = NimBLECharacteristicCallbacks::Status::ERROR_INDICATE_FAILURE; - } - } else { - return 0; - } - - server->clearIndicateWait(event->notify_tx.conn_handle); - } else { if(event->notify_tx.status == 0) { - statusRC = NimBLECharacteristicCallbacks::Status::SUCCESS_NOTIFY; - } else { - statusRC = NimBLECharacteristicCallbacks::Status::ERROR_GATT; + return 0; // Indication sent but not yet acknowledged. } + server->clearIndicateWait(event->notify_tx.conn_handle); } - pChar->m_pCallbacks->onStatus(pChar, statusRC, event->notify_tx.status); + pChar->m_pCallbacks->onStatus(pChar, event->notify_tx.status); return 0; } // BLE_GAP_EVENT_NOTIFY_TX