[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

@@ -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.
 <br/>
 

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) {
+    void onStatus(NimBLECharacteristic* pCharacteristic, int code) {
-        printf("Notification/Indication status code: %d , return code: %d, %s\n",
+        printf("Notification/Indication return code: %d, %s\n",
-                            status,
+               code, NimBLEUtils::returnCodeToString(code));
-                            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());
     };
 

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 Status return code from the NimBLE stack.
- * @param [in] code Additional 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
 

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);
 };
 

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;
+                    return 0; // Indication sent but not yet acknowledged.
-                } else {
-                    statusRC = NimBLECharacteristicCallbacks::Status::ERROR_GATT;
                 }
+                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