From 41ac44c30b9d165dd90255eec5b817fc21b8f7ff Mon Sep 17 00:00:00 2001 From: Trumeet Date: Wed, 20 Jul 2022 20:37:37 -0700 Subject: docs(libacron): add library docs Signed-off-by: Trumeet --- client/libacron/include/ids.h | 5 +++++ client/libacron/include/libac.h | 4 ++-- client/libacron/include/net.h | 19 +++++++++++++++++++ client/libacron/include/requests.h | 8 ++++++++ client/libacron/private/connection.h | 6 ++++++ client/libacron/private/helpers.h | 23 +++++++++++++++++++++++ client/libacron/private/serializer.h | 20 ++++++++++++++++++++ 7 files changed, 83 insertions(+), 2 deletions(-) diff --git a/client/libacron/include/ids.h b/client/libacron/include/ids.h index 86fde47..80e7448 100644 --- a/client/libacron/include/ids.h +++ b/client/libacron/include/ids.h @@ -21,6 +21,11 @@ typedef struct ac_obj { uint8_t type; } ac_obj_t; +/** + * Free the object. + * @param obj Object to free. Must be a valid object. + * @return AC_E_OK or an error code. When succeeds, obj is freed and no longer valid. + */ int ac_object_free(ac_obj_t *obj); #endif /* LIBAC_IDS_H */ diff --git a/client/libacron/include/libac.h b/client/libacron/include/libac.h index 80734dc..542adcb 100644 --- a/client/libacron/include/libac.h +++ b/client/libacron/include/libac.h @@ -21,13 +21,13 @@ typedef struct libac_config { /** * Initialize libac for the calling thread. - * @return 0 on success. + * @return AC_E_OK on success. */ int ac_init(const libac_config_t *config); /** * Destroy libac configuration for the calling thread. - * @return 0 on success. + * @return AC_E_OK on success. */ int ac_free(void); diff --git a/client/libacron/include/net.h b/client/libacron/include/net.h index 5b10470..8fb33f8 100644 --- a/client/libacron/include/net.h +++ b/client/libacron/include/net.h @@ -20,10 +20,29 @@ typedef struct ac_connection_parameters { char *url; } ac_connection_parameters_t; +/** + * Connect to the server. + * @param parameters Connection parameters. Untouched. + * @param out Output connection reference if succeeds. Not-NULL. + * @return AC_E_OK or an error code. When failed, *out will be untouched. + * MT-Safe + */ int ac_connect(ac_connection_parameters_t parameters, void **out); +/** + * Disconnect the connection. + * @param connection A non-NULL and connected connection passed as-is from ac_connect. + * @return AC_E_OK or an error code. When failed, connection is undefined. When succeeds, connection is freed and invalid. + * MT-Unsafe + */ int ac_disconnect(void *connection); +/** + * Blocks the current thread until a new response or event arrives. + * @param connection A non-NULL and connected connection passed as-is from ac_connect. + * @param response Output response of either an event or a response. May be NULL even if it succeeds. + * @return AC_E_OK or an error code. When failed, *response is NULL. + */ int ac_receive(void *connection, ac_obj_t **response); #endif /* LIBAC_NET_H */ diff --git a/client/libacron/include/requests.h b/client/libacron/include/requests.h index 40742e0..590bb2e 100644 --- a/client/libacron/include/requests.h +++ b/client/libacron/include/requests.h @@ -66,6 +66,14 @@ typedef struct ac_request_set_config { ac_config_t config; } ac_request_set_config_t; +/** + * Send a request to the connection. If this function succeeds, ac_receive() will return a response + * with the same ID later. + * @param connection Must be a non-NULL and connected connection, or it will return AC_E_INVALID_REQUEST. + * @param request A valid ac_request_t. It will left untouched. + * @return AC_E_OK or an error code. + * MT-Unsafe: Must be called on the same thread calling ac_receive(). + */ int ac_request(void *connection, const ac_request_t *request); #endif /* LIBAC_REQUESTS_H */ diff --git a/client/libacron/private/connection.h b/client/libacron/private/connection.h index 1c1567f..ad65b11 100644 --- a/client/libacron/private/connection.h +++ b/client/libacron/private/connection.h @@ -9,12 +9,18 @@ #include "libac.h" #include +/** + * Used to transfer deserialization result from receive handler to ac_receive(). + */ struct ac_result { bool has_result; int res; ac_obj_t *obj; }; +/** + * Internal representation of void *connection. + */ struct ac_connection { ac_connection_parameters_t parameters; struct wic_inst inst; diff --git a/client/libacron/private/helpers.h b/client/libacron/private/helpers.h index 20dfeec..f1635a6 100644 --- a/client/libacron/private/helpers.h +++ b/client/libacron/private/helpers.h @@ -9,14 +9,37 @@ #define SALLOC(s, out) alloc(NULL, 1, sizeof(s), true, (void **) out) +/** + * Allocate or reallocate a range of memory on heap. + * @param existing The existing range to extend. NULL-able. + * @param count The number of bytes. Final size = count * bytes. + * @param bytes The size. Final size = count * bytes. + * @param zero_out Whether to zero out the newly-allocated memory. Ignored when existing != NULL. + * @param out Output memory range. Not NULL if the return value is AC_E_OK. + * @return AC_E_OK or an error code. When failed, *out is untouched. + * MT-Safe + */ int alloc(void *existing, unsigned int count, unsigned int bytes, bool zero_out, void **out); +/** + * Duplicate a string. + * @param str String to duplicate. + * @param out Output string. Not NULL if the return value is AC_E_OK. + * @return AC_E_OK or an error code. When failed, *out is untouched. + * MT-Safe + */ int strdup2(const char *str, char **out); +/** + * Cross-platform thread-safe wrapper of strerror(3). + * @param errnum errno + * @return Always non-NULL error message. + * MT-Safe + */ char *strerror2(int errnum); #endif /* LIBAC_HELPERS_H */ diff --git a/client/libacron/private/serializer.h b/client/libacron/private/serializer.h index 1b9a38b..cbc9557 100644 --- a/client/libacron/private/serializer.h +++ b/client/libacron/private/serializer.h @@ -9,10 +9,30 @@ * Should not conflict with other error codes. */ #define AC_E_SERIALIZER_CONTINUE -1 +/** + * Deserialize an event or a response into ac_obj_t. + * @param string The partial or complete response. + * @param len The length to the string, excluding tailing NULL. + * @param out The final object. Not NULL if the return value is AC_E_OK. + * @return AC_E_OK or an error code. When failed, the *out is untouched. + * MT-Safe config + */ int deserialize(const char *string, unsigned int len, ac_obj_t **out); +/** + * Force a deserializer reset. + * @return AC_E_OK or an error code. + * MT-Safe + */ int serializer_finalize(void); +/** + * Serialize a request to a JSON object. + * @param req The request. Must be a valid ac_request. + * @param out The output json_object. Will not be NULL if the return value is AC_E_OK. + * @return AC_E_OK or an error code. When failed, the *out is untouched. + * MT-Safe + */ int serialize_request(const ac_request_t *req, json_object **out); #endif /* LIBAC_SERIALIZER_H */ -- cgit v1.2.3