change async callback syntax to indicate new error reporting behavior

Make a breaking change in the order of params for async callbacks to make it clear that something fundamental has changed in the callback. This, along with documentation in Doxygen and CHANGELOG is meant to raise user attention to new behavior in the golioth_response status usage. Signed-off-by: Mike Szczys <[email protected]>
golioth · Nov 13, 2024 · f2e207f · f2e207f
1 parent cb85544
commit f2e207f
Show file tree

Hide file tree

Showing 23 changed files with 68 additions and 41 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   include `block_buffer_len` for the actual length of data and
   `negotiated_block_size` to indicate the maximum block size (may be
   used along with 'block_idx' to calculate a byte offset).
+- Asynchronous callbacks now return error information for both the
+  Golioth Firmware SDK and the CoAP response code. When response->status
+  is GOLIOTH_OK or GOLIOTH_ERR_COAP_REPONSE_CODE, read the
+  response->status_class and response->status_code for the CoAP response
+  code. All other response->status codes indicate an SDK error and the
+  CoAP response codes are invalid/undefined. The order of the path and
+  response has been reversed in all async callbacks to differentiate the
+  new error reporting behavior.
+
+### Fixed:
+
+- User callbacks now run when requests are cancelled.
 
 ### Removed:
 

diff --git a/examples/common/golioth_basics.c b/examples/common/golioth_basics.c
@@ -85,8 +85,8 @@ static enum golioth_rpc_status on_multiply(zcbor_state_t *request_params_array,
 
 // Callback function for asynchronous get request of LightDB path "my_int"
 static void on_get_my_int(struct golioth_client *client,
-                          const struct golioth_response *response,
                           const char *path,
+                          const struct golioth_response *response,
                           const uint8_t *payload,
                           size_t payload_size,
                           void *arg)
@@ -105,8 +105,8 @@ static void on_get_my_int(struct golioth_client *client,
 
 // Callback function for asynchronous observation of LightDB path "desired/my_config"
 static void on_my_config(struct golioth_client *client,
-                         const struct golioth_response *response,
                          const char *path,
+                         const struct golioth_response *response,
                          const uint8_t *payload,
                          size_t payload_size,
                          void *arg)

diff --git a/examples/esp_idf/lightdb/delete/main/app_main.c b/examples/esp_idf/lightdb/delete/main/app_main.c
@@ -33,8 +33,8 @@ static void on_client_event(struct golioth_client *client,
 }
 
 static void counter_handler(struct golioth_client *client,
-                            const struct golioth_response *response,
                             const char *path,
+                            const struct golioth_response *response,
                             void *arg)
 {
     if (response->status != GOLIOTH_OK)

diff --git a/examples/esp_idf/lightdb/get/main/app_main.c b/examples/esp_idf/lightdb/get/main/app_main.c
@@ -36,8 +36,8 @@ static void on_client_event(struct golioth_client *client,
 }
 
 static void counter_get_handler(struct golioth_client *client,
-                                const struct golioth_response *response,
                                 const char *path,
+                                const struct golioth_response *response,
                                 const uint8_t *payload,
                                 size_t payload_size,
                                 void *arg)
@@ -103,8 +103,8 @@ static void counter_get_json_sync(struct golioth_client *client)
 }
 
 static void counter_get_cbor_handler(struct golioth_client *client,
-                                     const struct golioth_response *response,
                                      const char *path,
+                                     const struct golioth_response *response,
                                      const uint8_t *payload,
                                      size_t payload_size,
                                      void *arg)

diff --git a/examples/esp_idf/lightdb/observe/main/app_main.c b/examples/esp_idf/lightdb/observe/main/app_main.c
@@ -31,8 +31,8 @@ static void on_client_event(struct golioth_client *client,
 }
 
 static void counter_observe_handler(struct golioth_client *client,
-                                    const struct golioth_response *response,
                                     const char *path,
+                                    const struct golioth_response *response,
                                     const uint8_t *payload,
                                     size_t payload_size,
                                     void *arg)

diff --git a/examples/esp_idf/lightdb/set/main/app_main.c b/examples/esp_idf/lightdb/set/main/app_main.c
@@ -34,8 +34,8 @@ static void on_client_event(struct golioth_client *client,
 }
 
 static void counter_set_handler(struct golioth_client *client,
-                                const struct golioth_response *response,
                                 const char *path,
+                                const struct golioth_response *response,
                                 void *arg)
 {
     if (response->status != GOLIOTH_OK)

diff --git a/examples/esp_idf/stream/main/app_main.c b/examples/esp_idf/stream/main/app_main.c
@@ -50,8 +50,8 @@ static float get_temperature()
 }
 
 static void temperature_push_handler(struct golioth_client *client,
-                                     const struct golioth_response *response,
                                      const char *path,
+                                     const struct golioth_response *response,
                                      void *arg)
 {
     if (response->status != GOLIOTH_OK)

diff --git a/examples/zephyr/lightdb/delete/src/main.c b/examples/zephyr/lightdb/delete/src/main.c
@@ -33,8 +33,8 @@ static void on_client_event(struct golioth_client *client,
 }
 
 static void counter_handler(struct golioth_client *client,
-                            const struct golioth_response *response,
                             const char *path,
+                            const struct golioth_response *response,
                             void *arg)
 {
     if (response->status != GOLIOTH_OK)

diff --git a/examples/zephyr/lightdb/get/src/main.c b/examples/zephyr/lightdb/get/src/main.c
@@ -36,8 +36,8 @@ static void on_client_event(struct golioth_client *client,
 }
 
 static void counter_get_handler(struct golioth_client *client,
-                                const struct golioth_response *response,
                                 const char *path,
+                                const struct golioth_response *response,
                                 const uint8_t *payload,
                                 size_t payload_size,
                                 void *arg)
@@ -103,8 +103,8 @@ static void counter_get_json_sync(struct golioth_client *client)
 }
 
 static void counter_get_cbor_handler(struct golioth_client *client,
-                                     const struct golioth_response *response,
                                      const char *path,
+                                     const struct golioth_response *response,
                                      const uint8_t *payload,
                                      size_t payload_size,
                                      void *arg)

diff --git a/examples/zephyr/lightdb/observe/src/main.c b/examples/zephyr/lightdb/observe/src/main.c
@@ -31,8 +31,8 @@ static void on_client_event(struct golioth_client *client,
 }
 
 static void counter_observe_handler(struct golioth_client *client,
-                                    const struct golioth_response *response,
                                     const char *path,
+                                    const struct golioth_response *response,
                                     const uint8_t *payload,
                                     size_t payload_size,
                                     void *arg)

diff --git a/examples/zephyr/lightdb/set/src/main.c b/examples/zephyr/lightdb/set/src/main.c
@@ -34,8 +34,8 @@ static void on_client_event(struct golioth_client *client,
 }
 
 static void counter_set_handler(struct golioth_client *client,
-                                const struct golioth_response *response,
                                 const char *path,
+                                const struct golioth_response *response,
                                 void *arg)
 {
     if (response->status != GOLIOTH_OK)

diff --git a/examples/zephyr/stream/src/main.c b/examples/zephyr/stream/src/main.c
@@ -91,8 +91,8 @@ static int get_temperature(struct sensor_value *val)
 #endif
 
 static void temperature_async_push_handler(struct golioth_client *client,
-                                           const struct golioth_response *response,
                                            const char *path,
+                                           const struct golioth_response *response,
                                            void *arg)
 {
     if (response->status != GOLIOTH_OK)

diff --git a/include/golioth/client.h b/include/golioth/client.h
@@ -146,15 +146,20 @@ typedef void (*golioth_client_event_cb_fn)(struct golioth_client *client,
 /// The callback function should check response->status to determine which case it is (response
 /// received or timeout).
 ///
+/// When response->status is GOLIOTH_OK or GOLIOTH_ERR_COAP_RESPONSE_CODE, the
+/// response->status_class and response->status_code may be read to determine the CoAP response code
+/// received. All other response->status codes indicate an SDK error code and the CoAP status
+/// members are invalid/undefined.
+///
 /// @param client The client handle from the original request.
-/// @param response Response status and class/code
 /// @param path The path from the original request
+/// @param response Response status and class/code
 /// @param payload The application layer payload in the response packet. Can be NULL.
 /// @param payload_size The size of payload, in bytes
 /// @param arg User argument, copied from the original request. Can be NULL.
 typedef void (*golioth_get_cb_fn)(struct golioth_client *client,
-                                  const struct golioth_response *response,
                                   const char *path,
+                                  const struct golioth_response *response,
                                   const uint8_t *payload,
                                   size_t payload_size,
                                   void *arg);
@@ -165,16 +170,21 @@ typedef void (*golioth_get_cb_fn)(struct golioth_client *client,
 /// response never received). The callback function should check response->status to determine which
 /// case it is (response received or timeout).
 ///
+/// When response->status is GOLIOTH_OK or GOLIOTH_ERR_COAP_RESPONSE_CODE, the
+/// response->status_class and response->status_code may be read to determine the CoAP response code
+/// received. All other response->status codes indicate an SDK error code and the CoAP status
+/// members are invalid/undefined.
+///
 /// @param client The client handle from the original request.
-/// @param response Response status and class/code
 /// @param path The path from the original request
+/// @param response Response status and class/code
 /// @param payload The application layer payload in the response packet. Can be NULL.
 /// @param payload_size The size of payload, in bytes
 /// @param is_last True if this is the final block of the get request
 /// @param arg User argument, copied from the original request. Can be NULL.
 typedef void (*golioth_get_block_cb_fn)(struct golioth_client *client,
-                                        const struct golioth_response *response,
                                         const char *path,
+                                        const struct golioth_response *response,
                                         const uint8_t *payload,
                                         size_t payload_size,
                                         bool is_last,
@@ -188,13 +198,18 @@ typedef void (*golioth_get_block_cb_fn)(struct golioth_client *client,
 /// received or timeout). If response->status is GOLIOTH_OK, then the set or delete request
 /// was successful.
 ///
+/// When response->status is GOLIOTH_OK or GOLIOTH_ERR_COAP_RESPONSE_CODE, the
+/// response->status_class and response->status_code may be read to determine the CoAP response code
+/// received. All other response->status codes indicate an SDK error code and the CoAP status
+/// members are invalid/undefined.
+///
 /// @param client The client handle from the original request.
-/// @param response Response status and class/code
 /// @param path The path from the original request
+/// @param response Response status and class/code
 /// @param arg User argument, copied from the original request. Can be NULL.
 typedef void (*golioth_set_cb_fn)(struct golioth_client *client,
-                                  const struct golioth_response *response,
                                   const char *path,
+                                  const struct golioth_response *response,
                                   void *arg);
 
 /// Create a Golioth client

diff --git a/src/coap_blockwise.c b/src/coap_blockwise.c
@@ -77,8 +77,8 @@ static void blockwise_upload_init(struct blockwise_transfer *ctx,
 
 // Blockwise upload's internal callback function that the COAP client calls
 static void on_block_sent(struct golioth_client *client,
-                          const struct golioth_response *response,
                           const char *path,
+                          const struct golioth_response *response,
                           size_t block_szx,
                           void *arg)
 {
@@ -251,7 +251,7 @@ enum golioth_status golioth_blockwise_post(struct golioth_client *client,
             ctx->response.status = status;
         }
 
-        set_cb(client, &ctx->response, path, callback_arg);
+        set_cb(client, path, &ctx->response, callback_arg);
     }
 
     /* Upload complete, clean up allocated resources */
@@ -314,8 +314,8 @@ static enum golioth_status call_write_block_callback(struct blockwise_transfer *
 
 // Blockwise download's internal callback function that the COAP client calls
 static void on_block_rcvd(struct golioth_client *client,
-                          const struct golioth_response *response,
                           const char *path,
+                          const struct golioth_response *response,
                           const uint8_t *payload,
                           size_t payload_size,
                           bool is_last,

diff --git a/src/coap_client.h b/src/coap_client.h
@@ -29,13 +29,13 @@
 /// Callback function type for blockwise uploads that also returns the blocksize in szx format
 ///
 /// @param client The client handle from the original request.
-/// @param response Response status and class/code
 /// @param path The path from the original request
+/// @param response Response status and class/code
 /// @param block_szx The block size from the server in coap SZX format
 /// @param arg User argument, copied from the original request. Can be NULL.
 typedef void (*golioth_set_block_cb_fn)(struct golioth_client *client,
-                                        const struct golioth_response *response,
                                         const char *path,
+                                        const struct golioth_response *response,
                                         size_t block_szx,
                                         void *arg);
 

diff --git a/src/coap_client_zephyr.c b/src/coap_client_zephyr.c
@@ -267,15 +267,15 @@ static int golioth_coap_cb(struct golioth_req_rsp *rsp)
             if (req->get.callback)
             {
                 req->get
-                    .callback(client, &rsp->codes, req->path, rsp->data, rsp->len, req->get.arg);
+                    .callback(client, req->path, &rsp->codes, rsp->data, rsp->len, req->get.arg);
             }
             break;
         case GOLIOTH_COAP_REQUEST_GET_BLOCK:
             if (req->get_block.callback)
             {
                 req->get_block.callback(client,
-                                        &rsp->codes,
                                         req->path,
+                                        &rsp->codes,
                                         rsp->data,
                                         rsp->len,
                                         rsp->is_last,
@@ -285,31 +285,31 @@ static int golioth_coap_cb(struct golioth_req_rsp *rsp)
         case GOLIOTH_COAP_REQUEST_POST:
             if (req->post.callback)
             {
-                req->post.callback(client, &rsp->codes, req->path, req->post.arg);
+                req->post.callback(client, req->path, &rsp->codes, req->post.arg);
             }
             break;
         case GOLIOTH_COAP_REQUEST_POST_BLOCK:
             if (req->post_block.callback)
             {
                 req->post_block.callback(client,
-                                         &rsp->codes,
                                          req->path,
+                                         &rsp->codes,
                                          req->post_block.block_szx,
                                          req->post_block.arg);
             }
             break;
         case GOLIOTH_COAP_REQUEST_DELETE:
             if (req->delete.callback)
             {
-                req->delete.callback(client, &rsp->codes, req->path, req->delete.arg);
+                req->delete.callback(client, req->path, &rsp->codes, req->delete.arg);
             }
             break;
         case GOLIOTH_COAP_REQUEST_OBSERVE:
             if (req->observe.callback)
             {
                 req->observe.callback(client,
-                                      &rsp->codes,
                                       req->path,
+                                      &rsp->codes,
                                       rsp->data,
                                       rsp->len,
                                       req->observe.arg);

diff --git a/src/fw_update.c b/src/fw_update.c
@@ -79,8 +79,8 @@ static enum golioth_status golioth_fw_update_report_state_sync(struct golioth_cl
 }
 
 static void on_ota_manifest(struct golioth_client *client,
-                            const struct golioth_response *response,
                             const char *path,
+                            const struct golioth_response *response,
                             const uint8_t *payload,
                             size_t payload_size,
                             void *arg)

diff --git a/src/lightdb_state.c b/src/lightdb_state.c
@@ -312,8 +312,8 @@ enum golioth_status golioth_lightdb_set_sync(struct golioth_client *client,
 }
 
 static void on_payload(struct golioth_client *client,
-                       const struct golioth_response *response,
                        const char *path,
+                       const struct golioth_response *response,
                        const uint8_t *payload,
                        size_t payload_size,
                        void *arg)

diff --git a/src/ota.c b/src/ota.c
@@ -299,8 +299,8 @@ enum golioth_status golioth_ota_payload_as_manifest(const uint8_t *payload,
 }
 
 static void on_block_rcvd(struct golioth_client *client,
-                          const struct golioth_response *response,
                           const char *path,
+                          const struct golioth_response *response,
                           const uint8_t *payload,
                           size_t payload_size,
                           bool is_last,

diff --git a/src/rpc.c b/src/rpc.c
@@ -87,8 +87,8 @@ static int params_decode(zcbor_state_t *zsd, void *value)
 }
 
 static void on_rpc(struct golioth_client *client,
-                   const struct golioth_response *response,
                    const char *path,
+                   const struct golioth_response *response,
                    const uint8_t *payload,
                    size_t payload_size,
                    void *arg)

diff --git a/src/settings.c b/src/settings.c
@@ -364,8 +364,8 @@ static int settings_decode(zcbor_state_t *zsd, void *value)
 }
 
 static void on_settings(struct golioth_client *client,
-                        const struct golioth_response *response,
                         const char *path,
+                        const struct golioth_response *response,
                         const uint8_t *payload,
                         size_t payload_size,
                         void *arg)