diff --git a/include/nnstreamer-edge-data.h b/include/nnstreamer-edge-data.h index da0de33..579ee48 100644 --- a/include/nnstreamer-edge-data.h +++ b/include/nnstreamer-edge-data.h @@ -27,15 +27,15 @@ typedef int64_t nns_ssize_t; * @brief The maximum number of data instances that nnstreamer-edge data may have. */ #define NNS_EDGE_DATA_LIMIT (256) + /** * @brief Callback called when nnstreamer-edge data is released. */ typedef void (*nns_edge_data_destroy_cb) (void *data); - /** * @brief Create a handle used for data transmission. - * @note Caller should release returned edge data using nns_edge_data_destroy(). + * @remarks If the function succeeds, @a data_h should be released using nns_edge_data_destroy(). * @param[out] data_h Handle of edge data. * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. @@ -55,9 +55,19 @@ int nns_edge_data_create (nns_edge_data_h *data_h); */ int nns_edge_data_destroy (nns_edge_data_h data_h); +/** + * @brief Destroy nnstreamer edge data handle. + * @details This is wrapper function of nns_edge_data_destroy() to avoid build warning of the incompatibe type casting. + * @param[in] data The pointer to the edge data handle to be released. + * @retval #NNS_EDGE_ERROR_NONE Successful. + * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported. + * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. + */ +void nns_edge_data_release_handle (void *data); + /** * @brief Copy edge data and return new handle. - * @note Caller should release returned new edge data using nns_edge_data_destroy(). + * @remarks If the function succeeds, @a new_data_h should be released using nns_edge_data_destroy(). * @param[in] data_h The edge data to be copied. * @param[out] new_data_h A destination handle of edge data. * @return 0 on success. Otherwise a negative error value. @@ -132,7 +142,8 @@ int nns_edge_data_set_info (nns_edge_data_h data_h, const char *key, const char /** * @brief Get the information of edge data. - * @note The param key is case-insensitive. Caller should release the returned value using free(). + * @remarks If the function succeeds, @a value should be released using free(). + * @note The param key is case-insensitive. * @param[in] data_h The edge data handle. * @param[in] key A key of the information. * @param[in] value The information to get. @@ -153,15 +164,6 @@ int nns_edge_data_get_info (nns_edge_data_h data_h, const char *key, char **valu */ int nns_edge_data_clear_info (nns_edge_data_h data_h); -/** - * @brief Release the edge data handle. This function releases the memory allocated for the edge data handle. - * @param[in] data The pointer to the edge data handle to be released. - * @retval #NNS_EDGE_ERROR_NONE Successful. - * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported. - * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. - */ -void nns_edge_data_release_handle (void *data); - /** * @brief Validate edge data handle. * @param[in] data_h The edge data handle. @@ -173,6 +175,7 @@ int nns_edge_data_is_valid (nns_edge_data_h data_h); /** * @brief Serialize metadata in edge data. + * @remarks If the function succeeds, @a data should be released using free(). * @param[in] data_h The handle to the edge data. * @param[out] data A pointer to store the serialized meta data. * @param[out] data_len A pointer to store the length of the serialized meta data. @@ -198,6 +201,7 @@ int nns_edge_data_deserialize_meta (nns_edge_data_h data_h, const void *data, co /** * @brief Serialize entire edge data (meta data + raw data). + * @remarks If the function succeeds, @a data should be released using free(). * @param[in] data_h The handle to the edge data. * @param[out] data A pointer to store the serialized edge data. * @param[out] data_len A pointer to store the length of the serialized edge data. @@ -228,7 +232,8 @@ int nns_edge_data_deserialize (nns_edge_data_h data_h, const void *data, const n * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported. - * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. */ + * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. + */ int nns_edge_data_is_serialized (const void *data, const nns_size_t data_len); #ifdef __cplusplus diff --git a/include/nnstreamer-edge-event.h b/include/nnstreamer-edge-event.h index 5c719d6..36793c0 100644 --- a/include/nnstreamer-edge-event.h +++ b/include/nnstreamer-edge-event.h @@ -21,6 +21,9 @@ extern "C" { typedef void *nns_edge_event_h; +/** + * @brief Enumeration for the event type of nnstreamer-edge. + */ typedef enum { NNS_EDGE_EVENT_UNKNOWN = 0, NNS_EDGE_EVENT_CAPABILITY, @@ -33,13 +36,11 @@ typedef enum { /** * @brief Callback for the nnstreamer edge event. + * @note This callback will suspend data stream. Do not spend too much time in the callback. * @param[in] event_h The edge event handle. * @param[in] user_data The user's custom data given to callbacks. - * @note This callback will suspend data stream. Do not spend too much time in the callback. * @return 0 on success. Otherwise a negative error value. - * @retval #NNS_EDGE_ERROR_NONE Successful. - * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported. - * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. */ + */ typedef int (*nns_edge_event_cb) (nns_edge_event_h event_h, void *user_data); /** @@ -55,7 +56,7 @@ int nns_edge_event_get_type (nns_edge_event_h event_h, nns_edge_event_e *event); /** * @brief Parse edge event (NNS_EDGE_EVENT_NEW_DATA_RECEIVED) and get received data. - * @note Caller should release returned edge data using nns_edge_data_destroy(). + * @remarks If the function succeeds, @a data_h should be released using nns_edge_data_destroy(). * @param[in] event_h The edge event handle. * @param[out] data_h Handle of received data. * @return 0 on success. Otherwise a negative error value. @@ -67,7 +68,7 @@ int nns_edge_event_parse_new_data (nns_edge_event_h event_h, nns_edge_data_h *da /** * @brief Parse edge event (NNS_EDGE_EVENT_CAPABILITY) and get capability string. - * @note Caller should release returned string using free(). + * @remarks If the function succeeds, @a capability should be released using free(). * @param[in] event_h The edge event handle. * @param[out] capability Capability string. * @return 0 on success. Otherwise a negative error value. @@ -94,8 +95,9 @@ int nns_edge_event_invoke_callback (nns_edge_event_cb event_cb, void *user_data, /** * @brief Create nnstreamer edge event. + * @remarks If the function succeeds, @a event_h should be released using nns_edge_event_destroy(). * @param[in] event Edge event type. - * @param[out] event_h The handle of the created edge event. It should be released using nns_edge_event_destroy(). + * @param[out] event_h The handle of the created edge event. * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported. @@ -110,7 +112,8 @@ int nns_edge_event_create (nns_edge_event_e event, nns_edge_event_h *event_h); * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported. - * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. */ + * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. + */ int nns_edge_event_destroy (nns_edge_event_h event_h); /** @@ -122,7 +125,8 @@ int nns_edge_event_destroy (nns_edge_event_h event_h); * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported. - * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. */ + * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. + */ int nns_edge_event_set_data (nns_edge_event_h event_h, void *data, nns_size_t data_len, nns_edge_data_destroy_cb destroy_cb); #ifdef __cplusplus diff --git a/include/nnstreamer-edge.h b/include/nnstreamer-edge.h index 3983ce6..21d11a8 100644 --- a/include/nnstreamer-edge.h +++ b/include/nnstreamer-edge.h @@ -16,6 +16,7 @@ #include #include #include + #include "nnstreamer-edge-data.h" #include "nnstreamer-edge-event.h" @@ -38,6 +39,9 @@ typedef enum { NNS_EDGE_ERROR_NOT_SUPPORTED = (NNS_EDGE_ERROR_UNKNOWN + 2), } nns_edge_error_e; +/** + * @brief Enumeration for the connection type of nnstreamer-edge. + */ typedef enum { NNS_EDGE_CONNECT_TYPE_TCP = 0, NNS_EDGE_CONNECT_TYPE_MQTT, @@ -48,6 +52,9 @@ typedef enum { NNS_EDGE_CONNECT_TYPE_UNKNOWN } nns_edge_connect_type_e; +/** + * @brief Enumeration for the node type of nnstreamer-edge. + */ typedef enum { NNS_EDGE_NODE_TYPE_QUERY_CLIENT = 0, NNS_EDGE_NODE_TYPE_QUERY_SERVER, @@ -59,10 +66,11 @@ typedef enum { /** * @brief Create a handle representing an instance of edge-AI connection between a server and client (query) or a data publisher and scriber. + * @remarks If the function succeeds, @a edge_h should be released using nns_edge_release_handle(). * @param[in] id Unique id in local network * @param[in] connect_type Value of @a nns_edge_connect_type_e. Connection type between edge nodes. * @param[in] node_type Value of @a nns_edge_node_type_e. The node type of edge connection. - * @param[out] edge_h The edge handle. If the function succeeds, @a edge_h should be released using nns_edge_release_handle(). + * @param[out] edge_h The edge handle. * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported. @@ -150,10 +158,11 @@ int nns_edge_create_handle (const char *id, nns_edge_connect_type_e connect_type /** * @brief Create edge custom handle. + * @remarks If the function succeeds, @a edge_h should be released using nns_edge_release_handle(). * @param[in] id Unique id in local network * @param[in] lib_path The library path implementing the custom connection. * @param[in] node_type Value of @a nns_edge_node_type_e. The node type of edge connection. - * @param[out] edge_h The edge handle. If the function succeeds, @a edge_h should be released using nns_edge_release_handle(). + * @param[out] edge_h The edge handle. * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. * @retval #NNS_EDGE_ERROR_NOT_SUPPORTED Not supported. @@ -303,7 +312,8 @@ int nns_edge_set_info (nns_edge_h edge_h, const char *key, const char *value); /** * @brief Get nnstreamer edge info. - * @note The param key is case-insensitive. Caller should release returned string using free(). + * @remarks If the function succeeds, @a value should be released using free(). + * @note The param key is case-insensitive. * @param[in] edge_h The edge handle. * @param[in] key Identifiers to determine which value to get. * @param[out] value The values that match the key. diff --git a/src/libnnstreamer-edge/nnstreamer-edge-queue.h b/src/libnnstreamer-edge/nnstreamer-edge-queue.h index 4354f31..a332f59 100644 --- a/src/libnnstreamer-edge/nnstreamer-edge-queue.h +++ b/src/libnnstreamer-edge/nnstreamer-edge-queue.h @@ -14,8 +14,7 @@ #ifndef __NNSTREAMER_EDGE_QUEUE_H__ #define __NNSTREAMER_EDGE_QUEUE_H__ -#include -#include "nnstreamer-edge.h" +#include "nnstreamer-edge-data.h" #ifdef __cplusplus extern "C" { @@ -32,7 +31,8 @@ typedef enum { } nns_edge_queue_leak_e; /** - * @brief Create queue. + * @brief Create queue. Default length limit is 0 (unlimited). + * @remarks If the function succeeds, @a handle should be released using nns_edge_queue_destroy(). * @param[out] handle Newly created handle. * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. @@ -92,7 +92,7 @@ int nns_edge_queue_push (nns_edge_queue_h handle, void *data, nns_size_t size, n * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. - * @retval #NNS_EDGE_ERROR_IO + * @retval #NNS_EDGE_ERROR_IO Failed to get data. */ int nns_edge_queue_pop (nns_edge_queue_h handle, void **data, nns_size_t *size); @@ -105,17 +105,17 @@ int nns_edge_queue_pop (nns_edge_queue_h handle, void **data, nns_size_t *size); * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. - * @retval #NNS_EDGE_ERROR_IO + * @retval #NNS_EDGE_ERROR_IO Failed to get data. */ int nns_edge_queue_wait_pop (nns_edge_queue_h handle, unsigned int timeout, void **data, nns_size_t *size); /** * @brief Stop waiting for new data and clear all data in the queue. + * @details When this function is called, nns_edge_queue_wait_pop() will stop the waiting. * @param[in] handle The queue handle. * @return 0 on success. Otherwise a negative error value. * @retval #NNS_EDGE_ERROR_NONE Successful. * @retval #NNS_EDGE_ERROR_INVALID_PARAMETER Given parameter is invalid. - * @note When this function is called, nns_edge_queue_wait_pop will stop the waiting. */ int nns_edge_queue_clear (nns_edge_queue_h handle);