From f2e207f161c067315e13acf5ab4df25cd0438b37 Mon Sep 17 00:00:00 2001 From: Mike Szczys Date: Tue, 12 Nov 2024 11:52:29 -0600 Subject: [PATCH] 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 --- CHANGELOG.md | 12 +++++++++ examples/common/golioth_basics.c | 4 +-- .../esp_idf/lightdb/delete/main/app_main.c | 2 +- examples/esp_idf/lightdb/get/main/app_main.c | 4 +-- .../esp_idf/lightdb/observe/main/app_main.c | 2 +- examples/esp_idf/lightdb/set/main/app_main.c | 2 +- examples/esp_idf/stream/main/app_main.c | 2 +- examples/zephyr/lightdb/delete/src/main.c | 2 +- examples/zephyr/lightdb/get/src/main.c | 4 +-- examples/zephyr/lightdb/observe/src/main.c | 2 +- examples/zephyr/lightdb/set/src/main.c | 2 +- examples/zephyr/stream/src/main.c | 2 +- include/golioth/client.h | 27 ++++++++++++++----- src/coap_blockwise.c | 6 ++--- src/coap_client.h | 4 +-- src/coap_client_zephyr.c | 12 ++++----- src/fw_update.c | 2 +- src/lightdb_state.c | 2 +- src/ota.c | 2 +- src/rpc.c | 2 +- src/settings.c | 2 +- tests/hil/tests/lightdb/test.c | 8 +++--- tests/hil/tests/ota/test.c | 2 +- 23 files changed, 68 insertions(+), 41 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 70f04f58b..327d79933 100644 --- 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 index 63d2cb539..42a2139f7 100644 --- 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 index d228a582c..01774d9f6 100644 --- 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 index 47253d3af..8adaae5ed 100644 --- 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 index 03b6c1cca..472d301b2 100644 --- 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 index cc9c8f1c6..a6fbba59f 100644 --- 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 index 3742b83db..bd514ddaa 100644 --- 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 index c4925fe85..d7227749a 100644 --- 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 index 3b91b3ba8..65a46e20c 100644 --- 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 index b6ec3aead..305444f61 100644 --- 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 index 2cdc73af4..f26464675 100644 --- 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 index 8235cdfb7..7a9bdae38 100644 --- 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 index 3d2f7f82b..a8f51483c 100644 --- 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 index 82ba5e845..e5c32a4e4 100644 --- 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 index 7818108a7..67674e558 100644 --- 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 index d07cbdb14..f2d274ff7 100644 --- 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,15 +285,15 @@ 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); } @@ -301,15 +301,15 @@ static int golioth_coap_cb(struct golioth_req_rsp *rsp) 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 index 09cd39119..100d353df 100644 --- 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 index 413ecc99e..cbea39b02 100644 --- 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 index 65f7a80ed..e5f2b572b 100644 --- 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 index 478bc415b..4c97579af 100644 --- 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 index 435278c67..31edd2673 100644 --- 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) diff --git a/tests/hil/tests/lightdb/test.c b/tests/hil/tests/lightdb/test.c index 3d982a175..91480ff68 100644 --- a/tests/hil/tests/lightdb/test.c +++ b/tests/hil/tests/lightdb/test.c @@ -29,8 +29,8 @@ struct obs_data static struct obs_data observed_data[MAX_OBSERVED_EVENTS]; static void int_cb(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) @@ -52,8 +52,8 @@ static void int_cb(struct golioth_client *client, } static void int_cbor_cb(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) @@ -185,8 +185,8 @@ struct lightdb_get_rsp }; static void get_cb(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) @@ -221,8 +221,8 @@ static void get_cb(struct golioth_client *client, } static void set_cb(struct golioth_client *client, - const struct golioth_response *response, const char *path, + const struct golioth_response *response, void *arg) { golioth_sys_sem_t sem = arg; diff --git a/tests/hil/tests/ota/test.c b/tests/hil/tests/ota/test.c index c4b02eb31..0042b2afc 100644 --- a/tests/hil/tests/ota/test.c +++ b/tests/hil/tests/ota/test.c @@ -169,8 +169,8 @@ static void test_block_ops(void) } static void on_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)