diff options
author | Trumeet <yuuta@yuuta.moe> | 2022-07-20 20:37:37 -0700 |
---|---|---|
committer | Trumeet <yuuta@yuuta.moe> | 2022-07-20 20:37:37 -0700 |
commit | 41ac44c30b9d165dd90255eec5b817fc21b8f7ff (patch) | |
tree | cf4fb9a61eef24a96365f54409f47e373ff2e3da /client/libacron/private | |
parent | e2452adee6ba683cbfe093301650503a936a1a94 (diff) | |
download | acron-41ac44c30b9d165dd90255eec5b817fc21b8f7ff.tar acron-41ac44c30b9d165dd90255eec5b817fc21b8f7ff.tar.gz acron-41ac44c30b9d165dd90255eec5b817fc21b8f7ff.tar.bz2 acron-41ac44c30b9d165dd90255eec5b817fc21b8f7ff.zip |
docs(libacron): add library docs
Signed-off-by: Trumeet <yuuta@yuuta.moe>
Diffstat (limited to 'client/libacron/private')
-rw-r--r-- | client/libacron/private/connection.h | 6 | ||||
-rw-r--r-- | client/libacron/private/helpers.h | 23 | ||||
-rw-r--r-- | client/libacron/private/serializer.h | 20 |
3 files changed, 49 insertions, 0 deletions
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 <stdbool.h> +/** + * 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 */ |