diff --git a/include/neuron/metrics.h b/include/neuron/metrics.h index 0136f483e..ae99379c2 100644 --- a/include/neuron/metrics.h +++ b/include/neuron/metrics.h @@ -204,31 +204,92 @@ typedef struct { neu_metric_entry_t *registered_metrics; } neu_metrics_t; +/** + * 初始化指标系统 + */ void neu_metrics_init(); + +/** + * 添加节点指标 + * + * @param adapter 适配器指针 + */ void neu_metrics_add_node(const neu_adapter_t *adapter); + +/** + * 删除节点指标 + * + * @param adapter 适配器指针 + */ void neu_metrics_del_node(const neu_adapter_t *adapter); -int neu_metrics_register_entry(const char *name, const char *help, - neu_metric_type_e type); + +/** + * 注册指标项 + * + * @param name 指标名称 + * @param help 帮助信息 + * @param type 指标类型 + * @return 成功返回0，失败返回负值 + */ +int neu_metrics_register_entry(const char *name, const char *help, + neu_metric_type_e type); + +/** + * 注销指标项 + * + * @param name 指标名称 + */ void neu_metrics_unregister_entry(const char *name); typedef void (*neu_metrics_cb_t)(const neu_metrics_t *metrics, void *data); + +/** + * 访问指标数据 + * + * @param cb 回调函数 + * @param data 用户数据 + */ void neu_metrics_visist(neu_metrics_cb_t cb, void *data); +/** + * 判断指标类型是否为计数器 + * + * @param type 指标类型 + * @return 是计数器返回true，否则返回false + */ static inline bool neu_metric_type_is_counter(neu_metric_type_e type) { return NEU_METRIC_TYPE_COUNTER == (type & NEU_METRIC_TYPE_MASK); } +/** + * 判断指标类型是否为滚动计数器 + * + * @param type 指标类型 + * @return 是滚动计数器返回true，否则返回false + */ static inline bool neu_metric_type_is_rolling_counter(neu_metric_type_e type) { return NEU_METRIC_TYPE_ROLLING_COUNTER == (type & NEU_METRIC_TYPE_MASK); } +/** + * 判断指标类型是否不重置 + * + * @param type 指标类型 + * @return 不重置返回true，否则返回false + */ static inline bool neu_metric_type_no_reset(neu_metric_type_e type) { return NEU_METRIC_TYPE_FLAG_NO_RESET & type; } +/** + * 获取指标类型的字符串表示 + * + * @param type 指标类型 + * @return 返回类型的字符串表示 + */ static inline const char *neu_metric_type_str(neu_metric_type_e type) { if (neu_metric_type_is_counter(type)) { @@ -238,10 +299,25 @@ static inline const char *neu_metric_type_str(neu_metric_type_e type) } } +/** + * 添加指标项 + * + * @param entries 指标项哈希表指针 + * @param name 指标名称 + * @param help 帮助信息 + * @param type 指标类型 + * @param init 初始值 + * @return 成功返回0，失败返回负值 + */ int neu_metric_entries_add(neu_metric_entry_t **entries, const char *name, const char *help, neu_metric_type_e type, uint64_t init); +/** + * 释放指标项资源 + * + * @param entry 指标项指针 + */ static inline void neu_metric_entry_free(neu_metric_entry_t *entry) { if (neu_metric_type_is_rolling_counter(entry->type)) { @@ -250,6 +326,11 @@ static inline void neu_metric_entry_free(neu_metric_entry_t *entry) free(entry); } +/** + * 释放组指标资源 + * + * @param group_metrics 组指标指针 + */ static inline void neu_group_metrics_free(neu_group_metrics_t *group_metrics) { if (NULL == group_metrics) { @@ -267,6 +348,14 @@ static inline void neu_group_metrics_free(neu_group_metrics_t *group_metrics) free(group_metrics); } +/** + * 创建新的节点指标 + * + * @param adapter 适配器指针 + * @param type 节点类型 + * @param name 节点名称 + * @return 返回新创建的节点指标指针，失败返回NULL + */ static inline neu_node_metrics_t * neu_node_metrics_new(neu_adapter_t *adapter, neu_node_type_e type, char *name) { @@ -282,6 +371,11 @@ neu_node_metrics_new(neu_adapter_t *adapter, neu_node_type_e type, char *name) return node_metrics; } +/** + * 释放节点指标资源 + * + * @param node_metrics 节点指标指针 + */ static inline void neu_node_metrics_free(neu_node_metrics_t *node_metrics) { if (NULL == node_metrics) { @@ -308,6 +402,17 @@ static inline void neu_node_metrics_free(neu_node_metrics_t *node_metrics) free(node_metrics); } +/** + * 添加节点指标项 + * + * @param node_metrics 节点指标指针 + * @param group_name 组名称，为NULL表示添加到节点级别 + * @param name 指标名称 + * @param help 帮助信息 + * @param type 指标类型 + * @param init 初始值 + * @return 成功返回0，失败返回负值 + */ static inline int neu_node_metrics_add(neu_node_metrics_t *node_metrics, const char *group_name, const char *name, const char *help, neu_metric_type_e type, @@ -351,6 +456,15 @@ static inline int neu_node_metrics_add(neu_node_metrics_t *node_metrics, return rv; } +/** + * 更新节点指标值 + * + * @param node_metrics 节点指标指针 + * @param group 组名称，为NULL表示更新节点级别指标 + * @param metric_name 指标名称 + * @param n 更新值 + * @return 成功返回0，失败返回负值 + */ static inline int neu_node_metrics_update(neu_node_metrics_t *node_metrics, const char * group, const char *metric_name, uint64_t n) @@ -386,6 +500,11 @@ static inline int neu_node_metrics_update(neu_node_metrics_t *node_metrics, return 0; } +/** + * 重置节点指标值 + * + * @param node_metrics 节点指标指针 + */ static inline void neu_node_metrics_reset(neu_node_metrics_t *node_metrics) { neu_metric_entry_t *entry = NULL; @@ -417,6 +536,14 @@ static inline void neu_node_metrics_reset(neu_node_metrics_t *node_metrics) pthread_mutex_unlock(&node_metrics->lock); } +/** + * 更新节点组指标名称 + * + * @param node_metrics 节点指标指针 + * @param group_name 原组名称 + * @param new_group_name 新组名称 + * @return 成功返回0，失败返回负值 + */ static inline int neu_node_metrics_update_group(neu_node_metrics_t *node_metrics, const char * group_name, @@ -442,6 +569,12 @@ neu_node_metrics_update_group(neu_node_metrics_t *node_metrics, return rv; } +/** + * 删除节点组指标 + * + * @param node_metrics 节点指标指针 + * @param group_name 组名称 + */ static inline void neu_node_metrics_del_group(neu_node_metrics_t *node_metrics, const char * group_name) { diff --git a/include/neuron/msg.h b/include/neuron/msg.h index 581e2572a..aaa27bf6f 100644 --- a/include/neuron/msg.h +++ b/include/neuron/msg.h @@ -395,6 +395,11 @@ typedef struct { neu_datatag_t *tags; } neu_req_add_tag_t, neu_req_update_tag_t; +/** + * 初始化添加标签请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_add_tag_fini(neu_req_add_tag_t *req) { for (uint16_t i = 0; i < req->n_tag; i++) { @@ -403,6 +408,13 @@ static inline void neu_req_add_tag_fini(neu_req_add_tag_t *req) free(req->tags); } +/** + * 复制添加标签请求结构 + * + * @param dst 目标请求结构指针 + * @param src 源请求结构指针 + * @return 成功返回0，失败返回-1 + */ static inline int neu_req_add_tag_copy(neu_req_add_tag_t *dst, neu_req_add_tag_t *src) { @@ -431,6 +443,11 @@ typedef struct neu_req_del_tag { char ** tags; } neu_req_del_tag_t; +/** + * 初始化删除标签请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_del_tag_fini(neu_req_del_tag_t *req) { for (uint16_t i = 0; i < req->n_tag; i++) { @@ -439,6 +456,13 @@ static inline void neu_req_del_tag_fini(neu_req_del_tag_t *req) free(req->tags); } +/** + * 复制删除标签请求结构 + * + * @param dst 目标请求结构指针 + * @param src 源请求结构指针 + * @return 成功返回0，失败返回-1 + */ static inline int neu_req_del_tag_copy(neu_req_del_tag_t *dst, neu_req_del_tag_t *src) { @@ -498,6 +522,11 @@ typedef struct { neu_req_subscribe_group_info_t *groups; } neu_req_subscribe_groups_t; +/** + * 初始化订阅组请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_subscribe_groups_fini(neu_req_subscribe_groups_t *req) { @@ -521,6 +550,11 @@ typedef struct neu_resp_subscribe_info { char *params; } neu_resp_subscribe_info_t; +/** + * 初始化订阅信息结构 + * + * @param info 订阅信息结构指针 + */ static inline void neu_resp_subscribe_info_fini(neu_resp_subscribe_info_t *info) { free(info->params); @@ -531,6 +565,12 @@ typedef struct { char group[NEU_GROUP_NAME_LEN]; UT_array *tags; } neu_resp_get_sub_driver_tags_info_t; + +/** + * 获取订阅驱动标签信息ICD(内部元数据描述符) + * + * @return 返回ICD指针 + */ inline static UT_icd *neu_resp_get_sub_driver_tags_info_icd() { static UT_icd icd = { sizeof(neu_resp_get_sub_driver_tags_info_t), NULL, @@ -551,11 +591,23 @@ typedef struct neu_req_node_setting { char *setting; } neu_req_node_setting_t; +/** + * 初始化节点设置请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_node_setting_fini(neu_req_node_setting_t *req) { free(req->setting); } +/** + * 复制节点设置请求结构 + * + * @param dst 目标请求结构指针 + * @param src 源请求结构指针 + * @return 成功返回0，失败返回-1 + */ static inline int neu_req_node_setting_copy(neu_req_node_setting_t *dst, neu_req_node_setting_t *src) { @@ -613,6 +665,11 @@ typedef struct { uint16_t rtt; // round trip time in milliseconds } neu_nodes_state_t; +/** + * 获取节点状态ICD(内部元数据描述符) + * + * @return 返回ICD结构 + */ inline static UT_icd neu_nodes_state_t_icd() { UT_icd icd = { sizeof(neu_nodes_state_t), NULL, NULL, NULL }; @@ -631,6 +688,11 @@ typedef struct { neu_datatag_t *tags; } neu_reqresp_template_group_t; +/** + * 初始化模板组结构 + * + * @param grp 模板组结构指针 + */ static inline void neu_reqresp_template_group_fini(neu_reqresp_template_group_t *grp) { @@ -647,6 +709,11 @@ typedef struct { neu_reqresp_template_group_t *groups; } neu_reqresp_template_t; +/** + * 初始化模板结构 + * + * @param tmpl 模板结构指针 + */ static inline void neu_reqresp_template_fini(neu_reqresp_template_t *tmpl) { for (uint16_t i = 0; i < tmpl->n_group; ++i) { @@ -678,6 +745,11 @@ typedef struct { neu_resp_template_info_t *templates; } neu_resp_get_templates_t; +/** + * 初始化获取模板响应结构 + * + * @param resp 响应结构指针 + */ static inline void neu_resp_get_templates_fini(neu_resp_get_templates_t *resp) { free(resp->templates); @@ -712,6 +784,11 @@ typedef struct { neu_datatag_t *tags; } neu_req_add_template_tag_t, neu_req_update_template_tag_t; +/** + * 初始化添加模板标签请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_add_template_tag_fini(neu_req_add_template_tag_t *req) { @@ -730,6 +807,11 @@ typedef struct { char ** tags; } neu_req_del_template_tag_t; +/** + * 初始化删除模板标签请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_del_template_tag_fini(neu_req_del_template_tag_t *req) { @@ -760,6 +842,11 @@ typedef struct { neu_req_inst_templates_info_t *insts; } neu_req_inst_templates_t; +/** + * 初始化安装模板请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_inst_templates_fini(neu_req_inst_templates_t *req) { for (uint16_t i = 0; i < req->n_inst; ++i) { @@ -775,6 +862,11 @@ typedef struct neu_req_read_group { bool sync; } neu_req_read_group_t; +/** + * 初始化读取组请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_read_group_fini(neu_req_read_group_t *req) { free(req->driver); @@ -788,6 +880,11 @@ typedef struct neu_req_write_tag { neu_dvalue_t value; } neu_req_write_tag_t; +/** + * 初始化写入标签请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_write_tag_fini(neu_req_write_tag_t *req) { free(req->driver); @@ -806,6 +903,11 @@ typedef struct neu_resp_tag_value_meta { neu_tag_meta_t metas[NEU_TAG_META_SIZE]; } neu_resp_tag_value_meta_t; +/** + * 获取标签值元数据ICD(内部元数据描述符) + * + * @return 返回ICD指针 + */ static inline UT_icd *neu_resp_tag_value_meta_icd() { static UT_icd icd = { sizeof(neu_resp_tag_value_meta_t), NULL, NULL, NULL }; @@ -820,6 +922,11 @@ typedef struct neu_req_write_tags { neu_resp_tag_value_t *tags; } neu_req_write_tags_t; +/** + * 初始化写入多个标签请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_write_tags_fini(neu_req_write_tags_t *req) { free(req->driver); @@ -834,6 +941,11 @@ typedef struct { neu_resp_tag_value_t *tags; } neu_req_gtag_group_t; +/** + * 初始化组标签组请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_gtag_group_fini(neu_req_gtag_group_t *req) { free(req->group); @@ -847,6 +959,11 @@ typedef struct { neu_req_gtag_group_t *groups; } neu_req_write_gtags_t; +/** + * 初始化写入组标签请求结构 + * + * @param req 请求结构指针 + */ static inline void neu_req_write_gtags_fini(neu_req_write_gtags_t *req) { free(req->driver); @@ -863,6 +980,11 @@ typedef struct { UT_array *tags; // neu_resp_tag_value_meta_t } neu_resp_read_group_t; +/** + * 释放读取组响应资源 + * + * @param resp 响应结构指针 + */ static inline void neu_resp_read_free(neu_resp_read_group_t *resp) { utarray_foreach(resp->tags, neu_resp_tag_value_meta_t *, tag_value) @@ -889,6 +1011,11 @@ typedef struct { UT_array * tags; // neu_resp_tag_value_meta_t } neu_reqresp_trans_data_t; +/** + * 释放传输数据资源 + * + * @param data 传输数据结构指针 + */ static inline void neu_trans_data_free(neu_reqresp_trans_data_t *data) { pthread_mutex_lock(&data->ctx->mtx); @@ -914,6 +1041,12 @@ static inline void neu_trans_data_free(neu_reqresp_trans_data_t *data) } } +/** + * 将标签值转换为JSON格式 + * + * @param tag_value 标签值结构指针 + * @param tag_json JSON标签结构指针 + */ static inline void neu_tag_value_to_json(neu_resp_tag_value_meta_t *tag_value, neu_json_read_resp_tag_t * tag_json) { @@ -1038,6 +1171,11 @@ typedef struct { char *params; } neu_req_ndriver_tag_param_t; +/** + * 初始化设备驱动标签参数结构 + * + * @param p 参数结构指针 + */ static inline void neu_req_ndriver_tag_param_fini(neu_req_ndriver_tag_param_t *p) { @@ -1053,6 +1191,11 @@ typedef struct { neu_req_ndriver_tag_param_t *tags; } neu_req_update_ndriver_tag_param_t; +/** + * 初始化更新设备驱动标签参数请求结构 + * + * @param p 请求结构指针 + */ static inline void neu_req_update_ndriver_tag_param_fini(neu_req_update_ndriver_tag_param_t *p) { @@ -1067,6 +1210,11 @@ typedef struct { char *address; } neu_req_ndriver_tag_info_t; +/** + * 初始化设备驱动标签信息结构 + * + * @param p 信息结构指针 + */ static inline void neu_req_ndriver_tag_info_fini(neu_req_ndriver_tag_info_t *p) { free(p->name); @@ -1081,6 +1229,11 @@ typedef struct { neu_req_ndriver_tag_info_t *tags; } neu_req_update_ndriver_tag_info_t; +/** + * 初始化更新设备驱动标签信息请求结构 + * + * @param p 请求结构指针 + */ static inline void neu_req_update_ndriver_tag_info_fini(neu_req_update_ndriver_tag_info_t *p) { @@ -1106,9 +1259,27 @@ typedef struct neu_req_update_log_level { bool core; } neu_req_update_log_level_t; -void neu_msg_gen(neu_reqresp_head_t *header, void *data); +/** + * 生成一个消息 + * + * @param header 消息头指针 + * @param data 消息数据指针 + */ +void neu_msg_gen(neu_reqresp_head_t *header, void *data); + +/** + * 复制一个消息 + * + * @param header 要复制的消息头指针 + * @return 返回复制后的消息头指针 + */ neu_reqresp_head_t *neu_msg_dup(neu_reqresp_head_t *header); +/** + * 交换消息的发送者和接收者 + * + * @param header 消息头指针 + */ inline static void neu_msg_exchange(neu_reqresp_head_t *header) { char tmp[NEU_NODE_NAME_LEN] = { 0 }; diff --git a/include/neuron/tag.h b/include/neuron/tag.h index 0cce43344..79205838a 100644 --- a/include/neuron/tag.h +++ b/include/neuron/tag.h @@ -107,6 +107,13 @@ void neu_tag_copy(neu_datatag_t *tag, const neu_datatag_t *other); void neu_tag_fini(neu_datatag_t *tag); void neu_tag_free(neu_datatag_t *tag); +/** + * @brief 检查数据标签是否具有指定的属性。 + * + * @param[in] tag 数据标签 + * @param[in] attribute 要检查的属性 + * @return 如果标签具有指定的属性，则返回 true，否则返回 false。 + */ inline static bool neu_tag_attribute_test(const neu_datatag_t *tag, neu_attribute_e attribute) { diff --git a/include/neuron/type.h b/include/neuron/type.h index ef7f6ac2a..df5ff0273 100644 --- a/include/neuron/type.h +++ b/include/neuron/type.h @@ -52,6 +52,12 @@ typedef enum { NEU_TYPE_PTR = 19, } neu_type_e; +/** + * 将数据类型枚举转换为字符串表示 + * + * @param type 数据类型枚举值 + * @return 返回对应的字符串表示 + */ inline static const char *neu_type_string(neu_type_e type) { switch (type) { @@ -128,6 +134,13 @@ typedef union { neu_value_ptr_t ptr; } neu_value_u; +/** + * 根据数据类型和值生成字符串描述 + * + * @param type 数据类型枚举值 + * @param value 数据值 + * @return 返回描述该值的字符串 + */ static inline char *neu_value_str(neu_type_e type, neu_value_u value) { static __thread char str[32] = { 0 }; @@ -256,6 +269,12 @@ typedef union neu_value64 { double vdouble; } neu_value64_u; +/** + * 设置24位整数值 + * + * @param v24 指向24位值的指针 + * @param v 要设置的32位值(只使用低24位) + */ static inline void neu_value24_set(union neu_value24 *v24, uint32_t v) { assert((v & 0xff000000) == 0); @@ -265,6 +284,12 @@ static inline void neu_value24_set(union neu_value24 *v24, uint32_t v) v24->value[2] = (v >> 16) & 0xff; } +/** + * 获取24位整数值 + * + * @param v24 24位值 + * @return 返回转换为32位的值 + */ static inline uint32_t neu_value24_get(union neu_value24 v24) { uint32_t ret = 0; @@ -276,6 +301,13 @@ static inline uint32_t neu_value24_get(union neu_value24 v24) return ret; } +/** + * 获取8位值中的指定位 + * + * @param value 8位值 + * @param index 位索引(0-7) + * @return 返回指定位的值(0或1) + */ static inline uint8_t neu_value8_get_bit(neu_value8_u value, uint8_t index) { uint8_t ret = 0; @@ -313,6 +345,13 @@ static inline uint8_t neu_value8_get_bit(neu_value8_u value, uint8_t index) return ret; } +/** + * 设置8位值中的指定位 + * + * @param value 指向8位值的指针 + * @param index 位索引(0-7) + * @param v 要设置的位值(0或1) + */ static inline void neu_value8_set_bit(neu_value8_u *value, uint8_t index, uint8_t v) { @@ -347,6 +386,13 @@ static inline void neu_value8_set_bit(neu_value8_u *value, uint8_t index, } } +/** + * 获取16位值中的指定位 + * + * @param value 16位值 + * @param index 位索引(0-15) + * @return 返回指定位的值(0或1) + */ static inline uint8_t neu_value16_get_bit(neu_value16_u value, uint8_t index) { uint8_t ret = 0; @@ -408,6 +454,13 @@ static inline uint8_t neu_value16_get_bit(neu_value16_u value, uint8_t index) return ret; } +/** + * 设置16位值中的指定位 + * + * @param value 指向16位值的指针 + * @param index 位索引(0-15) + * @param v 要设置的位值(0或1) + */ static inline void neu_value16_set_bit(neu_value16_u *value, uint8_t index, uint8_t v) { @@ -466,6 +519,11 @@ static inline void neu_value16_set_bit(neu_value16_u *value, uint8_t index, } } +/** + * 将24位值从网络字节序转换为主机字节序 + * + * @param value 指向24位值的指针 + */ static inline void neu_ntohs24_p(uint8_t *value) { uint8_t t = 0; @@ -475,11 +533,22 @@ static inline void neu_ntohs24_p(uint8_t *value) value[2] = t; } +/** + * 将24位值从主机字节序转换为网络字节序 + * + * @param value 指向24位值的指针 + */ static inline void neu_htons24_p(uint8_t *value) { neu_ntohs24_p(value); } +/** + * 将64位值从主机字节序转换为网络字节序 + * + * @param u 64位值 + * @return 返回网络字节序的64位值 + */ static inline uint64_t neu_htonll(uint64_t u) { uint8_t *bytes = (uint8_t *) &u; @@ -498,6 +567,12 @@ static inline uint64_t neu_htonll(uint64_t u) return ret; } +/** + * 将64位值从主机字节序转换为特定字节序(低字节在前，高字节在后) + * + * @param u 64位值 + * @return 返回转换后的64位值 + */ static inline uint64_t neu_htonlb(uint64_t u) { uint8_t *in = (uint8_t *) &u; @@ -516,6 +591,12 @@ static inline uint64_t neu_htonlb(uint64_t u) return out; } +/** + * 将64位值从主机字节序转换为特定字节序(低字节在后，高字节在前) + * + * @param u 64位值 + * @return 返回转换后的64位值 + */ static inline uint64_t neu_htonbl(uint64_t u) { uint8_t *in = (uint8_t *) &u; @@ -534,41 +615,83 @@ static inline uint64_t neu_htonbl(uint64_t u) return out; } +/** + * 将64位值从网络字节序转换为主机字节序 + * + * @param u 64位值 + * @return 返回主机字节序的64位值 + */ static inline uint64_t neu_ntohll(uint64_t u) { return neu_htonll(u); } +/** + * 将指向64位值的指针从网络字节序转换为主机字节序 + * + * @param pu 指向64位值的指针 + */ static inline void neu_ntonll_p(uint64_t *pu) { *pu = neu_htonll(*pu); } +/** + * 将指向64位值的指针从主机字节序转换为网络字节序 + * + * @param pu 指向64位值的指针 + */ static inline void neu_htonll_p(uint64_t *pu) { neu_ntonll_p(pu); } +/** + * 将指向32位值的指针从网络字节序转换为主机字节序 + * + * @param pu 指向32位值的指针 + */ static inline void neu_ntohl_p(uint32_t *pu) { *pu = ntohl(*pu); } +/** + * 将指向32位值的指针从主机字节序转换为网络字节序 + * + * @param pu 指向32位值的指针 + */ static inline void neu_htonl_p(uint32_t *pu) { neu_ntohl_p(pu); } +/** + * 将指向16位值的指针从网络字节序转换为主机字节序 + * + * @param pu 指向16位值的指针 + */ static inline void neu_ntohs_p(uint16_t *pu) { *pu = ntohs(*pu); } +/** + * 将指向16位值的指针从主机字节序转换为网络字节序 + * + * @param pu 指向16位值的指针 + */ static inline void neu_htons_p(uint16_t *pu) { neu_ntohs_p(pu); } +/** + * 从字节数组获取无符号16位整数 + * + * @param bytes 字节数组 + * @return 返回组合后的16位无符号整数 + */ static inline uint16_t neu_get_u16(uint8_t *bytes) { uint16_t ret = 0; @@ -582,6 +705,12 @@ static inline uint16_t neu_get_u16(uint8_t *bytes) return ret; } +/** + * 从字节数组获取有符号16位整数 + * + * @param bytes 字节数组 + * @return 返回组合后的16位有符号整数 + */ static inline int16_t neu_get_i16(uint8_t *bytes) { int16_t ret = 0; @@ -595,6 +724,12 @@ static inline int16_t neu_get_i16(uint8_t *bytes) return ret; } +/** + * 从字节数组获取无符号32位整数 + * + * @param bytes 字节数组 + * @return 返回组合后的32位无符号整数 + */ static inline uint32_t neu_get_u32(uint8_t *bytes) { uint32_t ret = 0; @@ -610,6 +745,12 @@ static inline uint32_t neu_get_u32(uint8_t *bytes) return ret; } +/** + * 从字节数组获取有符号32位整数 + * + * @param bytes 字节数组 + * @return 返回组合后的32位有符号整数 + */ static inline int32_t neu_get_i32(uint8_t *bytes) { int32_t ret = 0; @@ -625,6 +766,12 @@ static inline int32_t neu_get_i32(uint8_t *bytes) return ret; } +/** + * 从字节数组获取32位浮点数 + * + * @param bytes 字节数组 + * @return 返回组合后的32位浮点数 + */ static inline float neu_get_f32(uint8_t *bytes) { float ret = 0; @@ -640,6 +787,12 @@ static inline float neu_get_f32(uint8_t *bytes) return ret; } +/** + * 从字节数组获取无符号64位整数 + * + * @param bytes 字节数组 + * @return 返回组合后的64位无符号整数 + */ static inline uint64_t neu_get_u64(uint8_t *bytes) { uint64_t ret = 0; @@ -659,6 +812,12 @@ static inline uint64_t neu_get_u64(uint8_t *bytes) return ret; } +/** + * 从字节数组获取有符号64位整数 + * + * @param bytes 字节数组 + * @return 返回组合后的64位有符号整数 + */ static inline int64_t neu_get_i64(uint8_t *bytes) { int64_t ret = 0; @@ -678,6 +837,12 @@ static inline int64_t neu_get_i64(uint8_t *bytes) return ret; } +/** + * 从字节数组获取64位浮点数 + * + * @param bytes 字节数组 + * @return 返回组合后的64位浮点数 + */ static inline double neu_get_f64(uint8_t *bytes) { double ret = 0; diff --git a/include/neuron/utils/protocol_buf.h b/include/neuron/utils/protocol_buf.h index 69db0aa86..b61839a10 100644 --- a/include/neuron/utils/protocol_buf.h +++ b/include/neuron/utils/protocol_buf.h @@ -36,11 +36,11 @@ typedef struct { } neu_protocol_buf_t, neu_protocol_pack_buf_t, neu_protocol_unpack_buf_t; /** - * @brief Initialization of protocol_pack_buf. + * @brief 初始化协议打包缓冲区 * - * @param[in] buf neu_protocol_pack_buf_t to be initialized. - * @param[in] base Memory used in protocol_pack_buf. - * @param[in] size Size of base memory. + * @param[in] buf 需要初始化的协议打包缓冲区 + * @param[in] base 协议打包缓冲区使用的内存 + * @param[in] size 内存大小 */ inline static void neu_protocol_pack_buf_init(neu_protocol_pack_buf_t *buf, uint8_t *base, uint16_t size) @@ -51,11 +51,11 @@ inline static void neu_protocol_pack_buf_init(neu_protocol_pack_buf_t *buf, } /** - * @brief Initialization of protocol_unpack_buf. + * @brief 初始化协议解包缓冲区 * - * @param[in] buf neu_protocol_unpack_buf_t to be initialized. - * @param[in] base Memory used in protocol_unpack_buf. - * @param[in] size Size of base memory. + * @param[in] buf 需要初始化的协议解包缓冲区 + * @param[in] base 协议解包缓冲区使用的内存 + * @param[in] size 内存大小 */ inline static void neu_protocol_unpack_buf_init(neu_protocol_unpack_buf_t *buf, uint8_t *base, uint16_t size) @@ -65,11 +65,23 @@ inline static void neu_protocol_unpack_buf_init(neu_protocol_unpack_buf_t *buf, buf->offset = 0; } +/** + * @brief 获取协议缓冲区的大小 + * + * @param[in] buf 协议缓冲区 + * @return 缓冲区大小 + */ inline static uint16_t neu_protocol_buf_size(neu_protocol_buf_t *buf) { return buf->size; } +/** + * @brief 创建新的协议解包缓冲区 + * + * @param[in] size 缓冲区大小 + * @return 新创建的协议解包缓冲区指针 + */ inline static neu_protocol_unpack_buf_t * neu_protocol_unpack_buf_new(uint16_t size) { @@ -83,6 +95,12 @@ neu_protocol_unpack_buf_new(uint16_t size) return buf; } +/** + * @brief 创建新的协议打包缓冲区 + * + * @param[in] size 缓冲区大小 + * @return 新创建的协议打包缓冲区指针 + */ inline static neu_protocol_pack_buf_t *neu_protocol_pack_buf_new(uint16_t size) { neu_protocol_pack_buf_t *buf = @@ -95,24 +113,46 @@ inline static neu_protocol_pack_buf_t *neu_protocol_pack_buf_new(uint16_t size) return buf; } +/** + * @brief 释放协议缓冲区内存 + * + * @param[in] buf 需要释放的协议缓冲区 + */ inline static void neu_protocol_buf_free(neu_protocol_buf_t *buf) { free(buf->base); free(buf); } +/** + * @brief 重置协议解包缓冲区 + * + * @param[in] buf 需要重置的协议解包缓冲区 + */ inline static void neu_protocol_unpack_buf_reset(neu_protocol_buf_t *buf) { buf->offset = 0; memset(buf->base, 0, buf->size); } +/** + * @brief 重置协议打包缓冲区 + * + * @param[in] buf 需要重置的协议打包缓冲区 + */ inline static void neu_protocol_pack_buf_reset(neu_protocol_buf_t *buf) { buf->offset = buf->size; memset(buf->base, 0, buf->size); } +/** + * @brief 从协议解包缓冲区读取数据并移动偏移量 + * + * @param[in] buf 协议解包缓冲区 + * @param[in] size 需要读取的数据大小 + * @return 数据指针，如果剩余空间不足则返回NULL + */ inline static uint8_t *neu_protocol_unpack_buf(neu_protocol_unpack_buf_t *buf, uint16_t size) { @@ -125,12 +165,25 @@ inline static uint8_t *neu_protocol_unpack_buf(neu_protocol_unpack_buf_t *buf, return buf->base + buf->offset - size; } +/** + * @brief 恢复协议解包缓冲区的偏移量 + * + * @param[in] buf 协议解包缓冲区 + * @param[in] size 需要回退的偏移量大小 + */ inline static void neu_protocol_unpack_buf_revert(neu_protocol_unpack_buf_t *buf, uint16_t size) { buf->offset -= size; } +/** + * @brief 获取协议解包缓冲区当前位置的数据，但不移动偏移量 + * + * @param[in] buf 协议解包缓冲区 + * @param[in] size 需要获取的数据大小 + * @return 数据指针，如果剩余空间不足则返回NULL + */ inline static uint8_t * neu_protocol_unpack_buf_get(neu_protocol_unpack_buf_t *buf, uint16_t size) { @@ -141,6 +194,13 @@ neu_protocol_unpack_buf_get(neu_protocol_unpack_buf_t *buf, uint16_t size) return buf->base + buf->offset; } +/** + * @brief 在协议打包缓冲区分配空间并移动偏移量 + * + * @param[in] buf 协议打包缓冲区 + * @param[in] size 需要分配的空间大小 + * @return 分配空间的指针，如果空间不足则返回NULL + */ inline static uint8_t *neu_protocol_pack_buf(neu_protocol_pack_buf_t *buf, uint16_t size) { @@ -153,6 +213,14 @@ inline static uint8_t *neu_protocol_pack_buf(neu_protocol_pack_buf_t *buf, return buf->base + buf->offset; } +/** + * @brief 在协议打包缓冲区指定偏移位置设置数据 + * + * @param[in] buf 协议打包缓冲区 + * @param[in] offset 相对当前位置的偏移量 + * @param[in] size 数据大小 + * @return 设置位置的指针，如果超出边界则返回NULL + */ inline static uint8_t *neu_protocol_pack_buf_set(neu_protocol_pack_buf_t *buf, uint16_t offset, uint16_t size) { @@ -163,41 +231,82 @@ inline static uint8_t *neu_protocol_pack_buf_set(neu_protocol_pack_buf_t *buf, return buf->base + buf->offset + offset; } +/** + * @brief 获取协议打包缓冲区当前位置的指针 + * + * @param[in] buf 协议打包缓冲区 + * @return 当前位置的指针 + */ inline static uint8_t *neu_protocol_pack_buf_get(neu_protocol_pack_buf_t *buf) { return buf->base + buf->offset; } +/** + * @brief 获取协议打包缓冲区未使用的空间大小 + * + * @param[in] buf 协议打包缓冲区 + * @return 未使用的空间大小（字节） + */ inline static uint16_t neu_protocol_pack_buf_unused_size(neu_protocol_pack_buf_t *buf) { return buf->offset; } +/** + * @brief 获取协议打包缓冲区已使用的空间大小 + * + * @param[in] buf 协议打包缓冲区 + * @return 已使用的空间大小（字节） + */ inline static uint16_t neu_protocol_pack_buf_used_size(neu_protocol_pack_buf_t *buf) { return buf->size - buf->offset; } +/** + * @brief 获取协议解包缓冲区未使用的空间大小 + * + * @param[in] buf 协议解包缓冲区 + * @return 未使用的空间大小（字节） + */ inline static uint16_t neu_protocol_unpack_buf_unused_size(neu_protocol_unpack_buf_t *buf) { return buf->size - buf->offset; } +/** + * @brief 获取协议解包缓冲区已使用的空间大小 + * + * @param[in] buf 协议解包缓冲区 + * @return 已使用的空间大小（字节） + */ inline static uint16_t neu_protocol_unpack_buf_used_size(neu_protocol_unpack_buf_t *buf) { return buf->offset; } +/** + * @brief 将协议解包缓冲区标记为全部已使用 + * + * @param[in] buf 协议解包缓冲区 + */ inline static void neu_protocol_unpack_buf_use_all(neu_protocol_unpack_buf_t *buf) { buf->offset = buf->size; } +/** + * @brief 获取协议解包缓冲区的总大小 + * + * @param[in] buf 协议解包缓冲区 + * @return 缓冲区总大小（字节） + */ inline static uint16_t neu_protocol_unpack_buf_size(neu_protocol_unpack_buf_t *buf) { diff --git a/include/neuron/utils/rolling_counter.h b/include/neuron/utils/rolling_counter.h index ed43e0528..53e05cba4 100644 --- a/include/neuron/utils/rolling_counter.h +++ b/include/neuron/utils/rolling_counter.h @@ -43,14 +43,14 @@ typedef struct { uint32_t counts[]; // bins of counters } neu_rolling_counter_t; -/** Create rolling counter. +/** 创建滚动计数器。 * - * @param span time span in milliseconds + * @param span 时间跨度（毫秒） */ static inline neu_rolling_counter_t *neu_rolling_counter_new(unsigned span) { unsigned n = span <= 6000 ? 4 : span <= 32000 ? 8 : span <= 64000 ? 16 : 32; - assert(span / n < (1 << 22)); // should not overflow ti + assert(span / n < (1 << 22)); // 不应溢出 neu_rolling_counter_t *counter = (neu_rolling_counter_t *) calloc( 1, sizeof(*counter) + sizeof(counter->counts[0]) * n); @@ -61,7 +61,7 @@ static inline neu_rolling_counter_t *neu_rolling_counter_new(unsigned span) return counter; } -/** Destructs the rolling counter. +/** 销毁滚动计数器。 */ static inline void neu_rolling_counter_free(neu_rolling_counter_t *counter) { @@ -70,10 +70,10 @@ static inline void neu_rolling_counter_free(neu_rolling_counter_t *counter) } } -/** Increment the rolling counter and return the value; +/** 增加滚动计数器并返回值； * - * @param ts time stamp in milliseconds, should be monotonic - * @param dt delta value to increment by + * @param ts 时间戳（毫秒），应该是单调递增的 + * @param dt 增加的增量值 */ static inline uint64_t neu_rolling_counter_inc(neu_rolling_counter_t *counter, uint64_t ts, unsigned dt) @@ -90,7 +90,7 @@ static inline uint64_t neu_rolling_counter_inc(neu_rolling_counter_t *counter, return counter->val; } -/** Reset the counter. +/** 重置计数器。 */ static inline void neu_rolling_counter_reset(neu_rolling_counter_t *counter) { @@ -99,9 +99,9 @@ static inline void neu_rolling_counter_reset(neu_rolling_counter_t *counter) memset(counter->counts, 0, counter->n * sizeof(counter->counts[0])); } -/** Return the counter value. +/** 返回计数器值。 * - * NOTE: may return stale value if the counter is not updated frequent enough. + * 注意：如果计数器更新不够频繁，可能会返回过期的值。 */ static inline uint64_t neu_rolling_counter_value(neu_rolling_counter_t *counter) { diff --git a/include/neuron/utils/time.h b/include/neuron/utils/time.h index b9ee978cd..6e9c2f1d3 100644 --- a/include/neuron/utils/time.h +++ b/include/neuron/utils/time.h @@ -28,6 +28,11 @@ extern "C" { #include #include +/** + * @brief 获取当前系统时间的毫秒时间戳 + * + * @return int64_t 返回自Unix纪元（1970-01-01 00:00:00 UTC）以来的毫秒数 + */ static inline int64_t neu_time_ms() { struct timeval tv = { 0 }; @@ -35,6 +40,11 @@ static inline int64_t neu_time_ms() return (int64_t) tv.tv_sec * 1000 + (int64_t) tv.tv_usec / 1000; } +/** + * @brief 使当前线程休眠指定的毫秒数 + * + * @param msec 休眠时间，单位为毫秒 + */ static inline void neu_msleep(unsigned msec) { struct timespec tv = { diff --git a/plugins/ekuiper/json_rw.c b/plugins/ekuiper/json_rw.c index e160f7f71..53a16a15f 100644 --- a/plugins/ekuiper/json_rw.c +++ b/plugins/ekuiper/json_rw.c @@ -25,6 +25,14 @@ #include "json_rw.h" #include "plugin_ekuiper.h" +/** + * @brief 编码读响应头部到JSON对象 + * @param json_object JSON对象指针 + * @param param 包含头部信息的结构体指针(json_read_resp_header_t) + * @return 成功返回0，失败返回错误码 + * + * 此函数将读响应头部信息(节点名、组名、时间戳)编码到JSON对象中。 + */ int json_encode_read_resp_header(void *json_object, void *param) { int ret = 0; @@ -51,6 +59,14 @@ int json_encode_read_resp_header(void *json_object, void *param) return ret; } +/** + * @brief 编码读响应标签数据到JSON对象 + * @param json_object JSON对象指针 + * @param param 包含响应信息的结构体指针(json_read_resp_t) + * @return 成功返回0，失败返回错误码 + * + * 此函数将标签值、错误和元数据编码到JSON对象中，分为values、errors和metas三个部分。 + */ int json_encode_read_resp_tags(void *json_object, void *param) { int ret = 0; @@ -150,6 +166,14 @@ int json_encode_read_resp_tags(void *json_object, void *param) return ret; } +/** + * @brief 编码完整读响应到JSON对象 + * @param json_object JSON对象指针 + * @param param 包含响应信息的结构体指针(json_read_resp_t) + * @return 成功返回0，失败返回错误码 + * + * 此函数编码完整的读响应，包括头部和标签数据。 + */ int json_encode_read_resp(void *json_object, void *param) { int ret = 0; @@ -174,6 +198,15 @@ int json_encode_read_resp(void *json_object, void *param) return ret; } +/** + * @brief 解码JSON写请求 + * @param buf JSON字符串缓冲区 + * @param len 缓冲区长度 + * @param result 解码结果存储指针的指针 + * @return 成功返回0，失败返回-1 + * + * 此函数解析JSON格式的写请求，提取节点名、组名、标签名和值信息。 + */ int json_decode_write_req(char *buf, size_t len, json_write_req_t **result) { int ret = 0; @@ -226,6 +259,13 @@ int json_decode_write_req(char *buf, size_t len, json_write_req_t **result) return ret; } +/** + * @brief 释放JSON写请求对象 + * @param req 写请求结构体指针 + * @return 无返回值 + * + * 此函数释放写请求结构体及其内部分配的内存。 + */ void json_decode_write_req_free(json_write_req_t *req) { if (NULL == req) { diff --git a/plugins/ekuiper/plugin_ekuiper.c b/plugins/ekuiper/plugin_ekuiper.c index 583a7e656..d8a8e7929 100644 --- a/plugins/ekuiper/plugin_ekuiper.c +++ b/plugins/ekuiper/plugin_ekuiper.c @@ -32,6 +32,12 @@ const neu_plugin_module_t neu_plugin_module; +/** + * @brief 打开eKuiper插件 + * @return 返回新创建的插件对象指针 + * + * 此函数分配并初始化eKuiper插件对象。 + */ static neu_plugin_t *ekuiper_plugin_open(void) { neu_plugin_t *plugin = calloc(1, sizeof(neu_plugin_t)); @@ -43,6 +49,13 @@ static neu_plugin_t *ekuiper_plugin_open(void) return plugin; } +/** + * @brief 关闭eKuiper插件 + * @param plugin 插件对象指针 + * @return 成功返回0 + * + * 此函数释放插件对象占用的资源。 + */ static int ekuiper_plugin_close(neu_plugin_t *plugin) { int rv = 0; @@ -53,6 +66,15 @@ static int ekuiper_plugin_close(neu_plugin_t *plugin) return rv; } +/** + * @brief NNG管道添加回调函数 + * @param p NNG管道对象 + * @param ev NNG管道事件 + * @param arg 回调参数，指向neu_plugin_t对象 + * @return 无返回值 + * + * 当NNG建立新连接时，更新插件连接状态为已连接。 + */ static void pipe_add_cb(nng_pipe p, nng_pipe_ev ev, void *arg) { (void) p; @@ -63,6 +85,15 @@ static void pipe_add_cb(nng_pipe p, nng_pipe_ev ev, void *arg) nng_mtx_unlock(plugin->mtx); } +/** + * @brief NNG管道移除回调函数 + * @param p NNG管道对象 + * @param ev NNG管道事件 + * @param arg 回调参数，指向neu_plugin_t对象 + * @return 无返回值 + * + * 当NNG连接断开时，更新插件连接状态为已断开。 + */ static void pipe_rm_cb(nng_pipe p, nng_pipe_ev ev, void *arg) { (void) p; @@ -73,6 +104,14 @@ static void pipe_rm_cb(nng_pipe p, nng_pipe_ev ev, void *arg) nng_mtx_unlock(plugin->mtx); } +/** + * @brief 初始化eKuiper插件 + * @param plugin 插件对象指针 + * @param load 是否为加载操作 + * @return 成功返回0，失败返回错误码 + * + * 此函数初始化插件所需的资源，包括互斥锁和异步I/O对象。 + */ static int ekuiper_plugin_init(neu_plugin_t *plugin, bool load) { (void) load; @@ -100,6 +139,13 @@ static int ekuiper_plugin_init(neu_plugin_t *plugin, bool load) return rv; } +/** + * @brief 反初始化eKuiper插件 + * @param plugin 插件对象指针 + * @return 成功返回0 + * + * 此函数释放插件初始化时分配的资源。 + */ static int ekuiper_plugin_uninit(neu_plugin_t *plugin) { int rv = 0; @@ -114,6 +160,14 @@ static int ekuiper_plugin_uninit(neu_plugin_t *plugin) return rv; } +/** + * @brief 启动NNG通信 + * @param plugin 插件对象指针 + * @param url NNG监听URL + * @return 成功返回0，失败返回错误码 + * + * 此函数创建NNG套接字并开始监听指定URL，用于与eKuiper通信。 + */ static inline int start(neu_plugin_t *plugin, const char *url) { int rv = 0; @@ -155,6 +209,13 @@ static inline int start(neu_plugin_t *plugin, const char *url) return NEU_ERR_SUCCESS; } +/** + * @brief 启动eKuiper插件 + * @param plugin 插件对象指针 + * @return 成功返回NEU_ERR_SUCCESS，失败返回错误码 + * + * 此函数启动插件并开始监听eKuiper连接。 + */ static int ekuiper_plugin_start(neu_plugin_t *plugin) { int rv = 0; @@ -171,11 +232,25 @@ static int ekuiper_plugin_start(neu_plugin_t *plugin) return NEU_ERR_SUCCESS; } +/** + * @brief 停止NNG通信 + * @param plugin 插件对象指针 + * @return 无返回值 + * + * 此函数关闭NNG套接字，停止与eKuiper的通信。 + */ static inline void stop(neu_plugin_t *plugin) { nng_close(plugin->sock); } +/** + * @brief 停止eKuiper插件 + * @param plugin 插件对象指针 + * @return 成功返回NEU_ERR_SUCCESS + * + * 此函数停止插件运行。 + */ static int ekuiper_plugin_stop(neu_plugin_t *plugin) { stop(plugin); @@ -184,6 +259,16 @@ static int ekuiper_plugin_stop(neu_plugin_t *plugin) return NEU_ERR_SUCCESS; } +/** + * @brief 解析配置参数 + * @param plugin 插件对象指针 + * @param setting 配置字符串 + * @param host_p 主机地址指针的指针 + * @param port_p 端口号指针 + * @return 成功返回0，失败返回-1 + * + * 此函数解析JSON格式的配置字符串，提取主机地址和端口号。 + */ static int parse_config(neu_plugin_t *plugin, const char *setting, char **host_p, uint16_t *port_p) { @@ -227,6 +312,15 @@ static int parse_config(neu_plugin_t *plugin, const char *setting, return -1; } +/** + * @brief 配置eKuiper插件 + * @param plugin 插件对象指针 + * @param setting 配置字符串 + * @return 成功返回0，失败返回错误码 + * + * 此函数应用新的配置参数，更新插件的主机地址和端口号设置。 + * 如果插件已启动，会先停止再重启以应用新配置。 + */ static int ekuiper_plugin_config(neu_plugin_t *plugin, const char *setting) { int rv = 0; @@ -281,6 +375,16 @@ static int ekuiper_plugin_config(neu_plugin_t *plugin, const char *setting) return rv; } +/** + * @brief 处理插件请求 + * @param plugin 插件对象指针 + * @param header 请求头指针 + * @param data 请求数据指针 + * @return 成功返回0 + * + * 此函数处理从Neuron核心发送到插件的各种请求， + * 包括数据传输、节点删除、组更新等操作。 + */ static int ekuiper_plugin_request(neu_plugin_t * plugin, neu_reqresp_head_t *header, void *data) { diff --git a/plugins/ekuiper/read_write.c b/plugins/ekuiper/read_write.c index 6609804b2..3e1b5f7dd 100644 --- a/plugins/ekuiper/read_write.c +++ b/plugins/ekuiper/read_write.c @@ -26,6 +26,14 @@ #include "json_rw.h" #include "read_write.h" +/** + * @brief 将数据发送到eKuiper + * @param plugin 插件对象指针 + * @param trans_data 传输数据指针 + * @return 无返回值 + * + * 此函数将传输数据编码为JSON格式并通过NNG发送到eKuiper服务器 + */ void send_data(neu_plugin_t *plugin, neu_reqresp_trans_data_t *trans_data) { int rv = 0; @@ -71,6 +79,14 @@ void send_data(neu_plugin_t *plugin, neu_reqresp_trans_data_t *trans_data) } } +/** + * @brief 接收数据的回调函数 + * @param arg 回调参数，指向neu_plugin_t对象 + * @return 无返回值 + * + * 此函数是异步接收eKuiper发送数据的回调函数。 + * 接收到数据后，解析JSON格式的写请求并执行写操作。 + */ void recv_data_callback(void *arg) { int rv = 0; @@ -117,6 +133,15 @@ void recv_data_callback(void *arg) nng_recv_aio(plugin->sock, plugin->recv_aio); } +/** + * @brief 执行数据写入操作 + * @param plugin 插件对象指针 + * @param write_req 写请求结构体指针 + * @return 成功返回0，失败返回错误码 + * + * 此函数根据写请求中的信息构造写标签命令，并调用插件操作函数执行写入。 + * 写入成功后，将所有权转移给Neuron系统。 + */ int write_data(neu_plugin_t *plugin, json_write_req_t *write_req) { int ret = 0; diff --git a/plugins/restful/adapter_handle.c b/plugins/restful/adapter_handle.c index 605525076..0ee0cc542 100644 --- a/plugins/restful/adapter_handle.c +++ b/plugins/restful/adapter_handle.c @@ -5,7 +5,7 @@ * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either - * version 3 of the License, or (at your option) any later version. + * version 3 of the License, or (at your) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of @@ -31,6 +31,11 @@ #include "adapter_handle.h" +/** + * 处理添加适配器的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_add_adapter(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -62,6 +67,13 @@ void handle_add_adapter(nng_aio *aio) }) } +/** + * 发送节点更新请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param req 更新节点的请求数据 + * @return 错误码，0表示成功，其他表示错误 + */ static inline int send_node_update_req(nng_aio * aio, neu_json_update_node_req_t *req) { @@ -95,6 +107,11 @@ static inline int send_node_update_req(nng_aio * aio, return 0; } +/** + * 处理更新适配器的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_update_adapter(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -107,6 +124,11 @@ void handle_update_adapter(nng_aio *aio) }) } +/** + * 处理删除适配器的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_del_adapter(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -129,6 +151,11 @@ void handle_del_adapter(nng_aio *aio) }) } +/** + * 处理获取适配器的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_get_adapter(nng_aio *aio) { int ret = 0; @@ -170,6 +197,12 @@ void handle_get_adapter(nng_aio *aio) } } +/** + * 处理获取适配器的响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param nodes 节点信息的数组 + */ void handle_get_adapter_resp(nng_aio *aio, neu_resp_get_node_t *nodes) { neu_json_get_nodes_resp_t nodes_res = { 0 }; @@ -196,6 +229,11 @@ void handle_get_adapter_resp(nng_aio *aio, neu_resp_get_node_t *nodes) utarray_free(nodes->nodes); } +/** + * 处理设置节点配置的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_set_node_setting(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -220,6 +258,11 @@ void handle_set_node_setting(nng_aio *aio) }) } +/** + * 处理获取节点配置的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_get_node_setting(nng_aio *aio) { neu_plugin_t * plugin = neu_rest_get_plugin(); @@ -250,6 +293,12 @@ void handle_get_node_setting(nng_aio *aio) } } +/** + * 处理获取节点配置的响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param setting 节点配置信息 + */ void handle_get_node_setting_resp(nng_aio * aio, neu_resp_get_node_setting_t *setting) { @@ -273,6 +322,11 @@ void handle_get_node_setting_resp(nng_aio * aio, free(json_str); } +/** + * 处理节点控制的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_node_ctl(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -297,6 +351,11 @@ void handle_node_ctl(nng_aio *aio) }) } +/** + * 处理获取节点状态的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_get_node_state(nng_aio *aio) { neu_plugin_t * plugin = neu_rest_get_plugin(); @@ -325,6 +384,12 @@ void handle_get_node_state(nng_aio *aio) } } +/** + * 处理获取单个节点状态的响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param state 节点状态信息 + */ void handle_get_node_state_resp(nng_aio *aio, neu_resp_get_node_state_t *state) { neu_json_get_node_state_resp_t res = { 0 }; @@ -342,6 +407,12 @@ void handle_get_node_state_resp(nng_aio *aio, neu_resp_get_node_state_t *state) free(result); } +/** + * 处理获取多个节点状态的响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param states 多个节点状态信息 + */ void handle_get_nodes_state_resp(nng_aio * aio, neu_resp_get_nodes_state_t *states) { diff --git a/plugins/restful/datatag_handle.c b/plugins/restful/datatag_handle.c index 7f83d74f1..1f4de8201 100644 --- a/plugins/restful/datatag_handle.c +++ b/plugins/restful/datatag_handle.c @@ -30,6 +30,11 @@ #include "datatag_handle.h" +/** + * 处理添加标签的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_add_tags(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -82,6 +87,12 @@ void handle_add_tags(nng_aio *aio) }) } +/** + * 处理添加标签的响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param resp 添加标签的响应数据 + */ void handle_add_tags_resp(nng_aio *aio, neu_resp_add_tag_t *resp) { neu_json_add_tag_res_t res = { 0 }; @@ -96,6 +107,11 @@ void handle_add_tags_resp(nng_aio *aio, neu_resp_add_tag_t *resp) free(result); } +/** + * 处理删除标签的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_del_tags(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -126,6 +142,11 @@ void handle_del_tags(nng_aio *aio) }) } +/** + * 处理更新标签的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_update_tags(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -170,11 +191,22 @@ void handle_update_tags(nng_aio *aio) }) } +/** + * 处理更新标签的响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param resp 更新标签的响应数据 + */ void handle_update_tags_resp(nng_aio *aio, neu_resp_update_tag_t *resp) { handle_add_tags_resp(aio, resp); } +/** + * 处理获取标签的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_get_tags(nng_aio *aio) { neu_plugin_t * plugin = neu_rest_get_plugin(); @@ -218,6 +250,12 @@ void handle_get_tags(nng_aio *aio) } } +/** + * 处理获取标签的响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param tags 标签信息的数组 + */ void handle_get_tags_resp(nng_aio *aio, neu_resp_get_tag_t *tags) { neu_json_get_tags_resp_t tags_res = { 0 }; diff --git a/plugins/restful/global_config_handle.c b/plugins/restful/global_config_handle.c index d41ce0d16..c348b88b1 100644 --- a/plugins/restful/global_config_handle.c +++ b/plugins/restful/global_config_handle.c @@ -80,27 +80,160 @@ typedef struct { }; } context_t; +/** + * 获取节点列表 + * + * @param ctx 上下文结构指针 + * @param type 节点类型 + * @return 成功返回0，失败返回错误码 + */ static int get_nodes(context_t *ctx, neu_node_type_e type); + +/** + * 处理获取节点列表的响应 + * + * @param ctx 上下文结构指针 + * @param nodes 节点列表响应结构 + * @return 成功返回0，失败返回错误码 + */ static int get_nodes_resp(context_t *ctx, neu_resp_get_node_t *nodes); + +/** + * 获取所有驱动的组配置 + * + * @param ctx 上下文结构指针 + * @param unused 未使用的参数 + * @return 成功返回0，失败返回错误码 + */ static int get_groups(context_t *ctx, int unused); + +/** + * 处理获取组配置的响应 + * + * @param ctx 上下文结构指针 + * @param groups 组配置响应结构 + * @return 成功返回0，失败返回错误码 + */ static int get_groups_resp(context_t *ctx, neu_resp_get_driver_group_t *groups); + +/** + * 获取驱动组内的标签列表 + * + * @param ctx 上下文结构指针 + * @param info 驱动组信息结构 + * @return 成功返回0，失败返回错误码 + */ static int get_tags(context_t *ctx, neu_resp_driver_group_info_t *info); + +/** + * 处理获取标签列表的响应 + * + * @param ctx 上下文结构指针 + * @param tags 标签列表响应结构 + * @return 成功返回0，失败返回错误码 + */ static int get_tags_resp(context_t *ctx, neu_resp_get_tag_t *tags); + +/** + * 获取应用的订阅组列表 + * + * @param ctx 上下文结构指针 + * @param info 节点信息结构 + * @return 成功返回0，失败返回错误码 + */ static int get_subscriptions(context_t *ctx, neu_resp_node_info_t *info); + +/** + * 处理获取订阅组列表的响应 + * + * @param ctx 上下文结构指针 + * @param groups 订阅组列表响应结构 + * @return 成功返回0，失败返回错误码 + */ static int get_subscriptions_resp(context_t * ctx, neu_resp_get_subscribe_group_t *groups); + +/** + * 获取节点配置 + * + * @param ctx 上下文结构指针 + * @param info 节点信息结构 + * @return 成功返回0，失败返回错误码 + */ static int get_setting(context_t *ctx, neu_resp_node_info_t *info); + +/** + * 处理获取节点配置的响应 + * + * @param ctx 上下文结构指针 + * @param setting 节点配置响应结构 + * @return 成功返回0，失败返回错误码 + */ static int get_setting_resp(context_t * ctx, neu_resp_get_node_setting_t *setting); +/** + * 删除节点 + * + * @param ctx 上下文结构指针 + * @param info 节点信息结构 + * @return 成功返回0，失败返回错误码 + */ static int del_node(context_t *ctx, neu_resp_node_info_t *info); + +/** + * 添加节点 + * + * @param ctx 上下文结构指针 + * @param req 添加节点请求结构 + * @return 成功返回0，失败返回错误码 + */ static int add_node(context_t *ctx, neu_json_get_nodes_resp_node_t *req); + +/** + * 添加组 + * + * @param ctx 上下文结构指针 + * @param data 添加组请求数据 + * @return 成功返回0，失败返回错误码 + */ static int add_group(context_t * ctx, neu_json_get_driver_group_resp_group_t *data); + +/** + * 添加标签 + * + * @param ctx 上下文结构指针 + * @param data 添加标签请求数据 + * @return 成功返回0，失败返回错误码 + */ static int add_tag(context_t *ctx, neu_json_add_tags_req_t *data); + +/** + * 添加订阅 + * + * @param ctx 上下文结构指针 + * @param data 添加订阅请求数据 + * @return 成功返回0，失败返回错误码 + */ static int add_subscription(context_t *ctx, neu_json_subscribe_req_t *data); + +/** + * 添加节点配置 + * + * @param ctx 上下文结构指针 + * @param data 添加节点配置请求数据 + * @return 成功返回0，失败返回错误码 + */ static int add_setting(context_t *ctx, neu_json_node_setting_req_t *data); +/** + * 判断节点是否为静态节点 + * + * @param name 节点名称 + * @param plugin 插件名称 + * @return 是静态节点返回true，否则返回false + */ static inline bool is_static_node(const char *name, const char *plugin) { (void) name; @@ -109,6 +242,13 @@ static inline bool is_static_node(const char *name, const char *plugin) // return 0 == strcmp("monitor", name) && 0 == strcmp("Monitor", plugin); } +/** + * 创建上下文结构 + * + * @param aio NNG异步I/O对象 + * @param get 是否为获取操作 + * @return 创建的上下文结构指针，失败返回NULL + */ static context_t *context_new(nng_aio *aio, bool get) { context_t *ctx = calloc(1, sizeof(*ctx)); @@ -128,6 +268,11 @@ static context_t *context_new(nng_aio *aio, bool get) return ctx; } +/** + * 释放上下文结构及其资源 + * + * @param ctx 上下文结构指针 + */ static void context_free(context_t *ctx) { if (NULL == ctx) { @@ -165,6 +310,13 @@ static void context_free(context_t *ctx) } \ } +/** + * 处理GET请求的状态机推进 + * + * @param ctx 上下文结构指针 + * @param type 请求响应类型 + * @param data 响应数据 + */ static void get_context_next(context_t *ctx, neu_reqresp_type_e type, void *data) { @@ -264,6 +416,13 @@ static void get_context_next(context_t *ctx, neu_reqresp_type_e type, } } +/** + * 处理PUT请求的状态机推进 + * + * @param ctx 上下文结构指针 + * @param type 请求响应类型 + * @param data 响应数据 + */ static void put_context_next(context_t *ctx, neu_reqresp_type_e type, void *data) { @@ -455,6 +614,13 @@ static void put_context_next(context_t *ctx, neu_reqresp_type_e type, } } +/** + * 根据请求类型选择合适的状态机推进函数 + * + * @param ctx 上下文结构指针 + * @param type 请求响应类型 + * @param data 响应数据 + */ static void context_next(context_t *ctx, neu_reqresp_type_e type, void *data) { if (ctx->get) { @@ -976,6 +1142,11 @@ static int add_setting(context_t *ctx, neu_json_node_setting_req_t *data) return 0; } +/** + * 处理获取全局配置的HTTP GET请求 + * + * @param aio NNG异步I/O对象 + */ void handle_get_global_config(nng_aio *aio) { NEU_VALIDATE_JWT(aio); @@ -992,6 +1163,11 @@ void handle_get_global_config(nng_aio *aio) context_next(ctx, NEU_REQ_GET_NODE, NULL); } +/** + * 处理更新全局配置的HTTP PUT请求 + * + * @param aio NNG异步I/O对象 + */ void handle_put_global_config(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -1010,9 +1186,16 @@ void handle_put_global_config(nng_aio *aio) }); } +/** + * 处理全局配置请求的响应 + * + * @param aio NNG异步I/O对象 + * @param type 请求响应类型 + * @param data 响应数据 + */ void handle_global_config_resp(nng_aio *aio, neu_reqresp_type_e type, void *data) { context_t *ctx = nng_aio_get_input(aio, 3); context_next(ctx, type, data); -} +} \ No newline at end of file diff --git a/plugins/restful/group_config_handle.c b/plugins/restful/group_config_handle.c index 052b481f2..65dcb78ab 100644 --- a/plugins/restful/group_config_handle.c +++ b/plugins/restful/group_config_handle.c @@ -29,6 +29,11 @@ #include "group_config_handle.h" +/** + * 处理添加组配置的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_add_group_config(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -61,6 +66,13 @@ void handle_add_group_config(nng_aio *aio) }) } +/** + * 发送更新组配置请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param req 更新组配置的请求数据 + * @return 错误码，0表示成功，其他表示错误 + */ static inline int send_update_group(nng_aio * aio, neu_json_update_group_config_req_t *req) { @@ -114,6 +126,11 @@ static inline int send_update_group(nng_aio * aio, return 0; } +/** + * 处理更新组配置的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_update_group(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -127,6 +144,11 @@ void handle_update_group(nng_aio *aio) }) } +/** + * 处理删除组配置的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_del_group_config(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -151,6 +173,11 @@ void handle_del_group_config(nng_aio *aio) }) } +/** + * 处理获取组配置的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_get_group_config(nng_aio *aio) { neu_plugin_t * plugin = neu_rest_get_plugin(); @@ -178,6 +205,12 @@ void handle_get_group_config(nng_aio *aio) } } +/** + * 处理获取组配置的响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param groups 组配置信息的数组 + */ void handle_get_group_resp(nng_aio *aio, neu_resp_get_group_t *groups) { neu_json_get_group_config_resp_t gconfig_res = { 0 }; @@ -206,6 +239,12 @@ void handle_get_group_resp(nng_aio *aio, neu_resp_get_group_t *groups) utarray_free(groups->groups); } +/** + * 处理获取驱动组配置的响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param groups 驱动组配置信息的数组 + */ void handle_get_driver_group_resp(nng_aio * aio, neu_resp_get_driver_group_t *groups) { @@ -235,6 +274,14 @@ void handle_get_driver_group_resp(nng_aio * aio, utarray_free(groups->groups); } +/** + * 发送订阅请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param type 请求类型 + * @param req 订阅请求数据 + * @return 错误码，0表示成功，其他表示错误 + */ static inline int send_subscribe(nng_aio *aio, neu_reqresp_type_e type, neu_json_subscribe_req_t *req) { @@ -259,6 +306,11 @@ static inline int send_subscribe(nng_aio *aio, neu_reqresp_type_e type, return 0; } +/** + * 处理组订阅的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_grp_subscribe(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -271,6 +323,11 @@ void handle_grp_subscribe(nng_aio *aio) }) } +/** + * 处理更新组订阅的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_grp_update_subscribe(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -283,6 +340,11 @@ void handle_grp_update_subscribe(nng_aio *aio) }) } +/** + * 处理取消组订阅的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_grp_unsubscribe(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -306,6 +368,13 @@ void handle_grp_unsubscribe(nng_aio *aio) }) } +/** + * 发送批量订阅组的请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param req 批量订阅组的请求数据 + * @return 错误码，0表示成功，其他表示错误 + */ static inline int send_subscribe_groups(nng_aio * aio, neu_json_subscribe_groups_req_t *req) { @@ -334,6 +403,11 @@ static inline int send_subscribe_groups(nng_aio * aio, return 0; } +/** + * 处理批量订阅组的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_grp_subscribes(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -347,6 +421,11 @@ void handle_grp_subscribes(nng_aio *aio) }) } +/** + * 处理获取组订阅信息的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_grp_get_subscribe(nng_aio *aio) { int ret = 0; @@ -376,6 +455,12 @@ void handle_grp_get_subscribe(nng_aio *aio) } } +/** + * 处理获取组订阅信息的响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param groups 订阅组信息的数组 + */ void handle_grp_get_subscribe_resp(nng_aio * aio, neu_resp_get_subscribe_group_t *groups) { diff --git a/plugins/restful/handle.c b/plugins/restful/handle.c index fb2e16842..16585752a 100644 --- a/plugins/restful/handle.c +++ b/plugins/restful/handle.c @@ -504,12 +504,30 @@ static struct neu_http_handler rest_handlers[] = { }, }; +/** + * @brief 获取 REST API 处理器列表 + * + * 该函数提供所有 REST API 的处理器列表和数量 + * + * @param handlers 指向处理器数组指针的指针，用于返回处理器列表 + * @param size 指向整数的指针，用于返回处理器数量 + * @return 无返回值 + */ void neu_rest_handler(const struct neu_http_handler **handlers, uint32_t *size) { *handlers = rest_handlers; *size = sizeof(rest_handlers) / sizeof(struct neu_http_handler); } +/** + * @brief 获取 CORS 处理器列表 + * + * 该函数提供用于处理 CORS 预检请求的处理器列表和数量 + * + * @param handlers 指向处理器数组指针的指针，用于返回 CORS 处理器列表 + * @param size 指向整数的指针，用于返回处理器数量 + * @return 无返回值 + */ void neu_rest_api_cors_handler(const struct neu_http_handler **handlers, uint32_t * size) { @@ -523,6 +541,14 @@ void neu_rest_api_cors_handler(const struct neu_http_handler **handlers, } } +/** + * @brief 初始化 REST 处理上下文 + * + * 该函数创建并初始化 REST 处理上下文，存储插件指针 + * + * @param plugin 插件对象指针 + * @return 返回初始化的上下文指针 + */ neu_rest_handle_ctx_t *neu_rest_init_ctx(void *plugin) { rest_ctx = calloc(1, sizeof(neu_rest_handle_ctx_t)); @@ -531,11 +557,26 @@ neu_rest_handle_ctx_t *neu_rest_init_ctx(void *plugin) return rest_ctx; } +/** + * @brief 释放 REST 处理上下文 + * + * 该函数释放 REST 处理上下文占用的内存资源 + * + * @param ctx 要释放的上下文指针 + * @return 无返回值 + */ void neu_rest_free_ctx(neu_rest_handle_ctx_t *ctx) { free(ctx); } +/** + * @brief 获取 REST 插件对象 + * + * 该函数返回初始化时存储的插件对象指针 + * + * @return 返回插件对象指针 + */ void *neu_rest_get_plugin() { return rest_ctx->plugin; diff --git a/plugins/restful/log_handle.c b/plugins/restful/log_handle.c index 91fbd5626..4e5235a56 100644 --- a/plugins/restful/log_handle.c +++ b/plugins/restful/log_handle.c @@ -42,6 +42,15 @@ #include "log_handle.h" #include "utils/utarray.h" +/** + * @brief 处理日志文件的下载请求 + * + * 此函数处理日志文件打包和下载请求，将所有日志打包成 tar.gz 并通过 HTTP + * 响应返回 + * + * @param aio NNG 异步 I/O 对象，用于处理 HTTP 请求和响应 + * @return 无返回值 + */ void handle_logs_files(nng_aio *aio) { void * data = NULL; @@ -106,6 +115,14 @@ void handle_logs_files(nng_aio *aio) nlog_notice("download neuron_debug.tar.gz, ret: %d", rv); } +/** + * @brief 处理日志级别的修改请求 + * + * 该函数用于修改系统或指定节点的日志级别 + * + * @param aio NNG 异步 I/O 对象，用于处理 HTTP 请求和响应 + * @return 无返回值 + */ void handle_log_level(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -158,6 +175,16 @@ void handle_log_level(nng_aio *aio) }) } +/** + * @brief 读取文件内容到内存中 + * + * 该函数将指定文件的内容读取到动态分配的内存中 + * + * @param file_name 要读取的文件路径 + * @param datap 指向指针的指针，用于存储读取内容的内存地址 + * @param lenp 指向大小变量的指针，用于存储读取内容的长度 + * @return 成功返回 0，失败返回错误码 + */ int read_file(const char *file_name, void **datap, size_t *lenp) { int rv = 0; diff --git a/plugins/restful/metric_handle.c b/plugins/restful/metric_handle.c index 3908dc49b..d3950e7df 100644 --- a/plugins/restful/metric_handle.c +++ b/plugins/restful/metric_handle.c @@ -90,6 +90,14 @@ "south_disconnected_nodes_total %zu\n" // clang-format on +/** + * 发送HTTP响应 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + * @param content 响应内容 + * @param status HTTP状态码 + * @return 0表示成功 + */ static int response(nng_aio *aio, char *content, enum nng_http_status status) { nng_http_res *res = NULL; @@ -120,6 +128,14 @@ static int response(nng_aio *aio, char *content, enum nng_http_status status) return 0; } +/** + * 解析指标类别字符串为枚举值 + * + * @param s 指标类别字符串 + * @param len 字符串长度 + * @param cat 输出参数，解析得到的指标类别枚举值 + * @return true表示解析成功，false表示解析失败 + */ static inline bool parse_metrics_catgory(const char *s, size_t len, neu_metrics_category_e *cat) { @@ -144,6 +160,12 @@ static inline bool parse_metrics_catgory(const char *s, size_t len, return false; } +/** + * 生成全局指标的Prometheus格式文本 + * + * @param metrics 全局指标数据 + * @param stream 输出流 + */ static inline void gen_global_metrics(const neu_metrics_t *metrics, FILE * stream) { @@ -158,6 +180,12 @@ static inline void gen_global_metrics(const neu_metrics_t *metrics, metrics->south_disconnected_nodes); } +/** + * 生成单个节点指标的Prometheus格式文本 + * + * @param node_metrics 节点指标数据 + * @param stream 输出流 + */ static inline void gen_single_node_metrics(neu_node_metrics_t *node_metrics, FILE * stream) { @@ -202,6 +230,13 @@ static inline void gen_single_node_metrics(neu_node_metrics_t *node_metrics, pthread_mutex_unlock(&node_metrics->lock); } +/** + * 检查节点指标中是否包含指定名称的条目 + * + * @param node_metrics 节点指标数据 + * @param name 条目名称 + * @return true表示存在，false表示不存在 + */ static inline bool has_entry(neu_node_metrics_t *node_metrics, const char *name) { neu_metric_entry_t * e = NULL; @@ -221,6 +256,13 @@ static inline bool has_entry(neu_node_metrics_t *node_metrics, const char *name) return false; } +/** + * 生成所有节点指标的Prometheus格式文本 + * + * @param metrics 指标数据 + * @param type_filter 节点类型过滤器 + * @param stream 输出流 + */ static void gen_all_node_metrics(neu_metrics_t *metrics, int type_filter, FILE *stream) { @@ -307,6 +349,12 @@ struct context { const char *node; }; +/** + * 生成节点指标的Prometheus格式文本 + * + * @param metrics 指标数据 + * @param ctx 上下文，包含过滤器、状态、输出流和节点名称 + */ static void gen_node_metrics(neu_metrics_t *metrics, struct context *ctx) { if (ctx->node[0]) { @@ -322,6 +370,11 @@ static void gen_node_metrics(neu_metrics_t *metrics, struct context *ctx) } } +/** + * 处理获取指标的HTTP请求，并以Prometheus格式返回指标数据 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + */ void handle_get_metric(nng_aio *aio) { int status = NNG_HTTP_STATUS_OK; diff --git a/plugins/restful/ndriver_handle.c b/plugins/restful/ndriver_handle.c index 6823e7467..8df99ab2b 100644 --- a/plugins/restful/ndriver_handle.c +++ b/plugins/restful/ndriver_handle.c @@ -31,6 +31,14 @@ #include "parser/neu_json_ndriver.h" +/** + * 发送北向驱动映射请求 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + * @param req 北向驱动映射请求数据 + * @param type 请求类型，如添加映射或删除映射 + * @return 0表示成功，其他值表示错误码 + */ static int send_ndriver_map_req(nng_aio *aio, neu_json_ndriver_map_t *req, neu_reqresp_type_e type) { @@ -61,6 +69,11 @@ static int send_ndriver_map_req(nng_aio *aio, neu_json_ndriver_map_t *req, return 0; } +/** + * 处理添加北向驱动映射的HTTP请求 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + */ void handle_add_ndriver_map(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -73,6 +86,11 @@ void handle_add_ndriver_map(nng_aio *aio) }) } +/** + * 处理删除北向驱动映射的HTTP请求 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + */ void handle_del_ndriver_map(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -85,6 +103,11 @@ void handle_del_ndriver_map(nng_aio *aio) }) } +/** + * 处理获取北向驱动映射列表的HTTP请求 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + */ void handle_get_ndriver_maps(nng_aio *aio) { int ret = 0; @@ -115,6 +138,12 @@ void handle_get_ndriver_maps(nng_aio *aio) } } +/** + * 处理获取北向驱动映射响应，并将结果格式化为JSON返回给客户端 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + * @param groups 北向驱动映射组信息 + */ void handle_get_ndriver_maps_resp(nng_aio * aio, neu_resp_get_ndriver_maps_t *groups) { @@ -147,6 +176,13 @@ void handle_get_ndriver_maps_resp(nng_aio * aio, utarray_free(groups->groups); } +/** + * 发送更新北向驱动标签参数的请求 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + * @param req 更新标签参数请求数据 + * @return 0表示成功，其他值表示错误码 + */ static inline int send_update_ndriver_tag_param_req(nng_aio * aio, neu_json_update_ndriver_tag_param_req_t *req) @@ -185,6 +221,11 @@ send_update_ndriver_tag_param_req(nng_aio * aio, return ret; } +/** + * 处理更新北向驱动标签参数的HTTP请求 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + */ void handle_put_ndriver_tag_param(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -198,6 +239,13 @@ void handle_put_ndriver_tag_param(nng_aio *aio) }) } +/** + * 发送更新北向驱动标签信息的请求 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + * @param req 更新标签信息请求数据 + * @return 0表示成功，其他值表示错误码 + */ static inline int send_update_ndriver_tag_info_req(nng_aio * aio, neu_json_update_ndriver_tag_info_req_t *req) @@ -236,6 +284,11 @@ send_update_ndriver_tag_info_req(nng_aio * aio, return ret; } +/** + * 处理更新北向驱动标签信息的HTTP请求 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + */ void handle_put_ndriver_tag_info(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -249,6 +302,11 @@ void handle_put_ndriver_tag_info(nng_aio *aio) }) } +/** + * 处理获取北向驱动标签列表的HTTP请求 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + */ void handle_get_ndriver_tags(nng_aio *aio) { int ret = 0; @@ -293,6 +351,12 @@ void handle_get_ndriver_tags(nng_aio *aio) } } +/** + * 处理获取北向驱动标签响应，并将结果格式化为JSON返回给客户端 + * + * @param aio 异步I/O对象，用于处理HTTP请求和响应 + * @param tags 北向驱动标签信息 + */ void handle_get_ndriver_tags_resp(nng_aio * aio, neu_resp_get_ndriver_tags_t *tags) { diff --git a/plugins/restful/normal_handle.c b/plugins/restful/normal_handle.c index 52fb800a6..f75816347 100644 --- a/plugins/restful/normal_handle.c +++ b/plugins/restful/normal_handle.c @@ -43,11 +43,23 @@ #include "normal_handle.h" +/** + * 处理ping请求，用于检查服务是否在线 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @return 无返回值，通过aio对象返回空JSON对象响应 + */ void handle_ping(nng_aio *aio) { neu_http_ok(aio, "{}"); } +/** + * 处理用户登录请求，验证用户名和密码，成功则返回JWT令牌 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @return 无返回值，通过aio对象返回HTTP响应，包含JWT令牌或错误信息 + */ void handle_login(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST( @@ -99,6 +111,12 @@ void handle_login(nng_aio *aio) }) } +/** + * 处理修改密码请求，验证用户旧密码后更新为新密码 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @return 无返回值，通过aio对象返回HTTP响应，表示操作成功或失败 + */ void handle_password(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -133,6 +151,13 @@ void handle_password(nng_aio *aio) }) } +/** + * 从文件中读取字符串内容 + * + * @param length 输出参数，返回读取的字符串长度 + * @param path 要读取的文件路径 + * @return 读取的字符串内容，失败则返回NULL + */ static char *file_string_read(size_t *length, const char *const path) { FILE *fp = fopen(path, "rb"); @@ -278,6 +303,12 @@ static struct { }, }; +/** + * 将插件名称转换为对应的schema名称 + * + * @param name 插件名称 + * @return 对应的schema名称，如果找不到对应关系则返回原名称 + */ static inline const char *plugin_name_to_schema_name(const char *name) { for (size_t i = 0; i < @@ -291,6 +322,12 @@ static inline const char *plugin_name_to_schema_name(const char *name) return name; } +/** + * 处理获取插件schema请求，返回指定插件的schema JSON配置 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @return 无返回值，通过aio对象返回HTTP响应，包含schema内容或错误信息 + */ void handle_get_plugin_schema(nng_aio *aio) { size_t len = 0; diff --git a/plugins/restful/plugin_handle.c b/plugins/restful/plugin_handle.c index e8eb183b7..9730ed111 100644 --- a/plugins/restful/plugin_handle.c +++ b/plugins/restful/plugin_handle.c @@ -28,6 +28,12 @@ #include "plugin_handle.h" +/** + * 处理添加插件的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @return 无返回值，通过aio对象返回HTTP响应 + */ void handle_add_plugin(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -50,6 +56,12 @@ void handle_add_plugin(nng_aio *aio) }) } +/** + * 处理删除插件的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @return 无返回值，通过aio对象返回HTTP响应 + */ void handle_del_plugin(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -77,6 +89,12 @@ void handle_del_plugin(nng_aio *aio) }) } +/** + * 处理获取插件列表的HTTP请求 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @return 无返回值，通过aio对象返回HTTP响应 + */ void handle_get_plugin(nng_aio *aio) { neu_plugin_t * plugin = neu_rest_get_plugin(); @@ -96,6 +114,13 @@ void handle_get_plugin(nng_aio *aio) } } +/** + * 处理获取插件列表的响应，将插件信息转换为JSON格式并发送HTTP响应 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + * @param plugins 插件列表信息结构体指针 + * @return 无返回值，通过aio对象返回HTTP响应 + */ void handle_get_plugin_resp(nng_aio *aio, neu_resp_get_plugin_t *plugins) { neu_json_get_plugin_resp_t plugin_res = { 0 }; diff --git a/plugins/restful/rest.c b/plugins/restful/rest.c index 17e1faf7e..7873e0186 100644 --- a/plugins/restful/rest.c +++ b/plugins/restful/rest.c @@ -49,6 +49,13 @@ struct neu_plugin { neu_rest_handle_ctx_t *handle_ctx; }; +/** + * @brief 初始化HTTP服务器 + * + * 此函数创建并初始化NNG HTTP服务器，绑定到指定的URL地址和端口。 + * + * @return 成功返回服务器指针，失败返回NULL + */ static nng_http_server *server_init() { nng_url * url; @@ -72,6 +79,14 @@ static nng_http_server *server_init() return server; } +/** + * @brief 打开仪表板插件 + * + * 此函数创建并初始化仪表板插件实例，设置HTTP处理器和CORS处理器， + * 启动HTTP服务器。 + * + * @return 成功返回插件实例指针，失败返回NULL + */ static neu_plugin_t *dashb_plugin_open(void) { int rv; @@ -116,6 +131,14 @@ static neu_plugin_t *dashb_plugin_open(void) return NULL; } +/** + * @brief 关闭仪表板插件 + * + * 此函数停止并释放HTTP服务器，清理插件资源。 + * + * @param plugin 插件实例指针 + * @return 成功返回0，失败返回错误码 + */ static int dashb_plugin_close(neu_plugin_t *plugin) { int rv = 0; @@ -128,6 +151,15 @@ static int dashb_plugin_close(neu_plugin_t *plugin) return rv; } +/** + * @brief 初始化仪表板插件 + * + * 此函数执行插件的初始化操作，包括JWT系统初始化。 + * + * @param plugin 插件实例指针 + * @param load 是否为加载时调用 + * @return 成功返回0，失败返回错误码 + */ static int dashb_plugin_init(neu_plugin_t *plugin, bool load) { (void) load; @@ -141,6 +173,14 @@ static int dashb_plugin_init(neu_plugin_t *plugin, bool load) return rv; } +/** + * @brief 卸载仪表板插件 + * + * 此函数执行插件的卸载操作，清理插件资源。 + * + * @param plugin 插件实例指针 + * @return 成功返回0，失败返回错误码 + */ static int dashb_plugin_uninit(neu_plugin_t *plugin) { int rv = 0; @@ -151,6 +191,15 @@ static int dashb_plugin_uninit(neu_plugin_t *plugin) return rv; } +/** + * @brief 配置仪表板插件 + * + * 此函数应用新的插件配置。 + * + * @param plugin 插件实例指针 + * @param configs 配置字符串 + * @return 成功返回0，失败返回错误码 + */ static int dashb_plugin_config(neu_plugin_t *plugin, const char *configs) { int rv = 0; @@ -162,6 +211,16 @@ static int dashb_plugin_config(neu_plugin_t *plugin, const char *configs) return rv; } +/** + * @brief 处理插件请求 + * + * 此函数处理各种插件请求类型，并调用相应的处理函数生成HTTP响应。 + * + * @param plugin 插件实例指针 + * @param header 请求头信息 + * @param data 请求数据 + * @return 成功返回0，失败返回错误码 + */ static int dashb_plugin_request(neu_plugin_t * plugin, neu_reqresp_head_t *header, void *data) { @@ -249,12 +308,28 @@ static int dashb_plugin_request(neu_plugin_t * plugin, return 0; } +/** + * @brief 启动仪表板插件 + * + * 此函数启动插件的运行状态。 + * + * @param plugin 插件实例指针 + * @return 成功返回0，失败返回错误码 + */ static int dashb_plugin_start(neu_plugin_t *plugin) { (void) plugin; return 0; } +/** + * @brief 停止仪表板插件 + * + * 此函数停止插件的运行状态。 + * + * @param plugin 插件实例指针 + * @return 成功返回0，失败返回错误码 + */ static int dashb_plugin_stop(neu_plugin_t *plugin) { (void) plugin; diff --git a/plugins/restful/rw_handle.c b/plugins/restful/rw_handle.c index 11e1947ef..ef9e6d1f3 100644 --- a/plugins/restful/rw_handle.c +++ b/plugins/restful/rw_handle.c @@ -28,6 +28,14 @@ #include "rw_handle.h" +/** + * @brief 处理读取请求的HTTP处理函数 + * + * 此函数处理来自客户端的读取请求，验证JWT令牌，解析读取命令， + * 并将命令发送给插件进行处理。 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_read(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -56,6 +64,14 @@ void handle_read(nng_aio *aio) }) } +/** + * @brief 处理写入请求的HTTP处理函数 + * + * 此函数处理来自客户端的标签写入请求，验证JWT令牌，解析写入命令， + * 检查值的大小是否合法，并将命令发送给插件进行处理。 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_write(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -135,6 +151,14 @@ void handle_write(nng_aio *aio) }) } +/** + * @brief 处理多标签写入请求的HTTP处理函数 + * + * 此函数处理来自客户端的多标签写入请求，验证JWT令牌，解析写入命令， + * 检查字符串值的大小是否合法，并将命令发送给插件进行处理。 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_write_tags(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -214,6 +238,14 @@ void handle_write_tags(nng_aio *aio) }) } +/** + * @brief 将JSON请求转换为内部命令结构 + * + * 此函数将解析后的JSON请求转换为内部命令结构，处理内存分配和值类型转换。 + * + * @param req 解析后的JSON请求结构 + * @param cmd 输出的内部命令结构 + */ static void trans(neu_json_write_gtags_req_t *req, neu_req_write_gtags_t *cmd) { cmd->driver = req->node; @@ -267,6 +299,14 @@ static void trans(neu_json_write_gtags_req_t *req, neu_req_write_gtags_t *cmd) } } +/** + * @brief 处理多组标签写入请求的HTTP处理函数 + * + * 此函数处理来自客户端的多组标签写入请求，验证JWT令牌，解析写入命令， + * 并将命令发送给插件进行处理。 + * + * @param aio NNG异步I/O对象，包含HTTP请求和响应信息 + */ void handle_write_gtags(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -294,6 +334,15 @@ void handle_write_gtags(nng_aio *aio) }) } +/** + * @brief 处理读取响应的函数 + * + * 此函数处理读取操作的响应，将内部响应结构转换为JSON格式， + * 并发送HTTP响应给客户端。 + * + * @param aio NNG异步I/O对象，用于发送HTTP响应 + * @param resp 内部读取响应结构，包含读取到的标签值 + */ void handle_read_resp(nng_aio *aio, neu_resp_read_group_t *resp) { neu_json_read_resp_t api_res = { 0 }; diff --git a/plugins/restful/template_handle.c b/plugins/restful/template_handle.c index 69673f08e..138175680 100644 --- a/plugins/restful/template_handle.c +++ b/plugins/restful/template_handle.c @@ -30,6 +30,15 @@ #include "handle.h" +/** + * @brief 根据JSON数据设置标签属性 + * + * 将JSON解析得到的标签信息应用到neu_datatag_t结构体 + * + * @param tag 目标标签结构体 + * @param json_tag 源JSON标签数据 + * @return int 成功返回0，失败返回错误码 + */ static int set_tag_by_json(neu_datatag_t *tag, neu_json_tag_t *json_tag) { if (strlen(json_tag->name) >= NEU_TAG_NAME_LEN) { @@ -66,6 +75,15 @@ static int set_tag_by_json(neu_datatag_t *tag, neu_json_tag_t *json_tag) return 0; } +/** + * @brief 将JSON模板数据转移到命令结构体 + * + * 解析JSON模板数据并将其移动到命令结构体中 + * + * @param cmd 目标命令结构体 + * @param req 源JSON模板数据 + * @return int 成功返回0，失败返回错误码 + */ static int move_template_json(neu_req_add_template_t *cmd, neu_json_template_t * req) { @@ -136,6 +154,13 @@ static int move_template_json(neu_req_add_template_t *cmd, return ret; } +/** + * @brief 处理添加模板的HTTP请求 + * + * 解析请求并添加一个新的模板 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_add_template(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -164,6 +189,13 @@ void handle_add_template(nng_aio *aio) }) } +/** + * @brief 处理删除模板的HTTP请求 + * + * 解析请求并删除指定名称的模板 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_del_template(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -193,6 +225,13 @@ void handle_del_template(nng_aio *aio) } } +/** + * @brief 处理获取模板的HTTP请求 + * + * 解析请求并获取指定名称的模板或所有模板 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_get_template(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -226,6 +265,14 @@ void handle_get_template(nng_aio *aio) } } +/** + * @brief 处理获取单个模板的响应 + * + * 将获取的模板数据格式化为JSON并发送HTTP响应 + * + * @param aio NNG异步I/O对象，用于处理HTTP响应 + * @param resp 获取的模板响应数据 + */ void handle_get_template_resp(nng_aio *aio, neu_resp_get_template_t *resp) { int rv = 0; @@ -306,6 +353,14 @@ void handle_get_template_resp(nng_aio *aio, neu_resp_get_template_t *resp) return; } +/** + * @brief 处理获取多个模板的响应 + * + * 将获取的多个模板数据格式化为JSON并发送HTTP响应 + * + * @param aio NNG异步I/O对象，用于处理HTTP响应 + * @param resp 获取的多个模板响应数据 + */ void handle_get_templates_resp(nng_aio *aio, neu_resp_get_templates_t *resp) { @@ -337,6 +392,15 @@ void handle_get_templates_resp(nng_aio *aio, neu_resp_get_templates_t *resp) return; } +/** + * @brief 发送添加模板组请求 + * + * 解析并验证添加模板组请求参数，然后发送请求 + * + * @param aio NNG异步I/O对象，用于处理HTTP响应 + * @param req 添加模板组请求数据 + * @return int 成功返回0，失败返回错误码 + */ static inline int send_template_add_group_req(nng_aio * aio, neu_json_template_add_group_req_t *req) @@ -368,6 +432,13 @@ send_template_add_group_req(nng_aio * aio, return 0; } +/** + * @brief 处理添加模板组的HTTP请求 + * + * 解析请求并添加一个新的模板组 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_add_template_group(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -381,6 +452,15 @@ void handle_add_template_group(nng_aio *aio) }) } +/** + * @brief 发送更新模板组请求 + * + * 解析并验证更新模板组请求参数，然后发送请求 + * + * @param aio NNG异步I/O对象，用于处理HTTP响应 + * @param req 更新模板组请求数据 + * @return int 成功返回0，失败返回错误码 + */ static inline int send_template_update_group_req(nng_aio * aio, neu_json_template_update_group_req_t *req) @@ -435,6 +515,13 @@ send_template_update_group_req(nng_aio * aio, return 0; } +/** + * @brief 处理更新模板组的HTTP请求 + * + * 解析请求并更新指定的模板组 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_update_template_group(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -448,6 +535,15 @@ void handle_update_template_group(nng_aio *aio) }) } +/** + * @brief 发送删除模板组请求 + * + * 解析并验证删除模板组请求参数，然后发送请求 + * + * @param aio NNG异步I/O对象，用于处理HTTP响应 + * @param req 删除模板组请求数据 + * @return int 成功返回0，失败返回错误码 + */ static inline int send_template_del_group_req(nng_aio * aio, neu_json_template_del_group_req_t *req) @@ -478,6 +574,13 @@ send_template_del_group_req(nng_aio * aio, return 0; } +/** + * @brief 处理删除模板组的HTTP请求 + * + * 解析请求并删除指定的模板组 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_del_template_group(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -491,6 +594,16 @@ void handle_del_template_group(nng_aio *aio) }) } +/** + * @brief 发送模板修改标签请求 + * + * 解析并验证模板修改标签请求参数，然后发送请求 + * + * @param aio NNG异步I/O对象，用于处理HTTP响应 + * @param type 请求类型，如添加或更新标签 + * @param req 模板修改标签请求数据 + * @return int 成功返回0，失败返回错误码 + */ static int send_template_mod_tags_req(nng_aio *aio, neu_reqresp_type_e type, neu_json_template_mod_tags_req_t *req) { @@ -535,6 +648,15 @@ static int send_template_mod_tags_req(nng_aio *aio, neu_reqresp_type_e type, return ret; } +/** + * @brief 发送删除模板标签请求 + * + * 解析并验证删除模板标签请求参数，然后发送请求 + * + * @param aio NNG异步I/O对象，用于处理HTTP响应 + * @param req 删除模板标签请求数据 + * @return int 成功返回0，失败返回错误码 + */ static int send_template_del_tags_req(nng_aio * aio, neu_json_template_del_tags_req_t *req) { @@ -581,6 +703,13 @@ static int send_template_del_tags_req(nng_aio * aio, return ret; } +/** + * @brief 处理添加模板标签的HTTP请求 + * + * 解析请求并添加模板标签 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_add_template_tags(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -595,6 +724,13 @@ void handle_add_template_tags(nng_aio *aio) }) } +/** + * @brief 处理更新模板标签的HTTP请求 + * + * 解析请求并更新模板标签 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_update_template_tags(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -609,6 +745,13 @@ void handle_update_template_tags(nng_aio *aio) }) } +/** + * @brief 处理删除模板标签的HTTP请求 + * + * 解析请求并删除模板标签 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_del_template_tags(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -622,6 +765,13 @@ void handle_del_template_tags(nng_aio *aio) }) } +/** + * @brief 处理获取模板标签的HTTP请求 + * + * 解析请求并获取模板标签信息 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_get_template_tags(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); @@ -669,6 +819,15 @@ void handle_get_template_tags(nng_aio *aio) } } +/** + * @brief 发送模板实例化请求 + * + * 解析并验证模板实例化请求参数，然后发送请求 + * + * @param aio NNG异步I/O对象，用于处理HTTP响应 + * @param req 模板实例化请求数据 + * @return int 成功返回0，失败返回错误码 + */ static inline int send_template_inst_req(nng_aio * aio, neu_json_template_inst_req_t *req) { @@ -698,6 +857,13 @@ static inline int send_template_inst_req(nng_aio * aio, return 0; } +/** + * @brief 处理实例化模板的HTTP请求 + * + * 解析请求并实例化指定模板 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_instantiate_template(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -710,6 +876,15 @@ void handle_instantiate_template(nng_aio *aio) }) } +/** + * @brief 发送批量模板实例化请求 + * + * 解析并验证批量模板实例化请求参数，然后发送请求 + * + * @param aio NNG异步I/O对象，用于处理HTTP响应 + * @param req 批量模板实例化请求数据 + * @return int 成功返回0，失败返回错误码 + */ static inline int send_template_insts_req(nng_aio * aio, neu_json_template_insts_req_t *req) { @@ -744,6 +919,13 @@ static inline int send_template_insts_req(nng_aio * aio, return 0; } +/** + * @brief 处理批量实例化模板的HTTP请求 + * + * 解析请求并批量实例化指定模板 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_instantiate_templates(nng_aio *aio) { NEU_PROCESS_HTTP_REQUEST_VALIDATE_JWT( @@ -757,6 +939,13 @@ void handle_instantiate_templates(nng_aio *aio) }) } +/** + * @brief 处理获取模板组信息的HTTP请求 + * + * 解析请求并获取指定模板的组信息 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + */ void handle_get_template_group(nng_aio *aio) { neu_plugin_t *plugin = neu_rest_get_plugin(); diff --git a/plugins/restful/user.c b/plugins/restful/user.c index ed1c9f3c0..31e1458cd 100644 --- a/plugins/restful/user.c +++ b/plugins/restful/user.c @@ -23,11 +23,15 @@ static const unsigned char cov_2char[64] = { static const char ascii_dollar[] = { 0x24, 0x00 }; -/* - * SHA based password algorithm, describe by Ulrich Drepper here: - * https://www.akkadia.org/drepper/SHA-crypt.txt - * (note that it's in the public domain) - * See: https://github.com/openssl/openssl/blob/master/apps/passwd.c +/** + * @brief 使用SHA算法对密码进行加密 + * + * 基于Ulrich Drepper描述的SHA密码算法实现，该算法用于密码存储 + * + * @param passwd 需要加密的密码明文 + * @param magic 加密算法标识，目前支持'5'(SHA256)和'6'(SHA512) + * @param salt 加密盐值，用于增强安全性 + * @return char* 返回加密后的密码字符串，失败时返回NULL */ static char *shacrypt(const char *passwd, const char *magic, const char *salt) { @@ -313,6 +317,15 @@ static char *shacrypt(const char *passwd, const char *magic, const char *salt) return NULL; } +/** + * @brief 对密码进行哈希处理 + * + * 使用SHA算法对密码进行哈希处理，如果未提供盐值则生成随机盐值 + * + * @param passwd 需要哈希的密码明文 + * @param salt 可选的盐值，如果为NULL则生成新的随机盐值 + * @return char* 返回哈希后的密码字符串，失败时返回NULL + */ // NOTE: if provided, require salt length of 16 static char *hash_password(const char *passwd, const char *salt) { @@ -343,6 +356,15 @@ static char *hash_password(const char *passwd, const char *salt) return hash; } +/** + * @brief 创建新用户 + * + * 创建一个新用户并对密码进行哈希处理 + * + * @param name 用户名 + * @param password 用户密码明文 + * @return neu_user_t* 返回创建的用户对象，失败时返回NULL + */ neu_user_t *neu_user_new(const char *name, const char *password) { neu_user_t *user = malloc(sizeof(*user)); @@ -363,6 +385,13 @@ neu_user_t *neu_user_new(const char *name, const char *password) return user; } +/** + * @brief 释放用户对象 + * + * 释放用户对象及其关联的内存资源 + * + * @param user 需要释放的用户对象 + */ void neu_user_free(neu_user_t *user) { if (NULL != user) { @@ -372,6 +401,15 @@ void neu_user_free(neu_user_t *user) } } +/** + * @brief 检查用户密码是否正确 + * + * 验证提供的密码是否与用户存储的哈希值匹配 + * + * @param user 用户对象 + * @param password 需要验证的密码明文 + * @return bool 密码正确返回true，错误返回false + */ bool neu_user_check_password(neu_user_t *user, const char *password) { char *salt = user->hash + 3; @@ -383,6 +421,14 @@ bool neu_user_check_password(neu_user_t *user, const char *password) return pass; } +/** + * @brief 从持久化存储加载用户信息 + * + * 根据用户名从持久化存储中加载用户信息 + * + * @param name 要加载的用户名 + * @return neu_user_t* 返回加载的用户对象，失败时返回NULL + */ neu_user_t *neu_load_user(const char *name) { neu_user_t *user = malloc(sizeof(*user)); @@ -403,6 +449,14 @@ neu_user_t *neu_load_user(const char *name) return user; } +/** + * @brief 保存用户信息到持久化存储 + * + * 将用户信息保存到持久化存储中 + * + * @param user 要保存的用户对象 + * @return int 成功返回0，失败返回错误码 + */ int neu_save_user(neu_user_t *user) { neu_persist_user_info_t info = { @@ -413,6 +467,15 @@ int neu_save_user(neu_user_t *user) return neu_persister_update_user(&info); } +/** + * @brief 更新用户密码 + * + * 使用新密码更新用户的密码哈希 + * + * @param user 用户对象 + * @param new_password 新密码明文 + * @return int 成功返回0，失败返回错误码 + */ int neu_user_update_password(neu_user_t *user, const char *new_password) { char *salt = user->hash + 3; diff --git a/plugins/restful/version_handle.c b/plugins/restful/version_handle.c index 477b814ef..6b8a13d69 100644 --- a/plugins/restful/version_handle.c +++ b/plugins/restful/version_handle.c @@ -26,6 +26,14 @@ #include "handle.h" #include "utils/http.h" +/** + * @brief 处理获取版本信息的HTTP请求 + * + * 获取当前Neuron的版本信息并以JSON格式返回，包括版本号、Git修订号和构建日期 + * + * @param aio NNG异步I/O对象，用于处理HTTP请求和响应 + * @return 无返回值，通过aio对象发送响应 + */ void handle_get_version(nng_aio *aio) { char *result = NULL; diff --git a/src/adapter/adapter.c b/src/adapter/adapter.c index 02ed31601..7e72ff301 100644 --- a/src/adapter/adapter.c +++ b/src/adapter/adapter.c @@ -38,25 +38,114 @@ #include "plugin.h" #include "storage.h" +/** + * 适配器消费者线程函数，从消息队列中获取消息并处理 + * + * @param arg 适配器指针(neu_adapter_t *) + * @return 线程返回值(void *) + */ static void *adapter_consumer(void *arg); -static int adapter_trans_data(enum neu_event_io_type type, int fd, - void *usr_data); -static int adapter_loop(enum neu_event_io_type type, int fd, void *usr_data); -static int adapter_command(neu_adapter_t *adapter, neu_reqresp_head_t header, - void *data); + +/** + * 适配器传输数据回调函数，处理来自数据传输套接字的消息 + * + * @param type 事件IO类型 + * @param fd 文件描述符 + * @param usr_data 用户数据(适配器指针) + * @return 执行结果(int)，0表示成功 + */ +static int adapter_trans_data(enum neu_event_io_type type, int fd, + void *usr_data); + +/** + * 适配器主循环回调函数，处理来自控制套接字的消息 + * + * @param type 事件IO类型 + * @param fd 文件描述符 + * @param usr_data 用户数据(适配器指针) + * @return 执行结果(int)，0表示成功 + */ +static int adapter_loop(enum neu_event_io_type type, int fd, void *usr_data); + +/** + * 适配器命令处理函数，向指定目标发送命令消息 + * + * @param adapter 适配器指针 + * @param header 请求/响应头 + * @param data 消息数据 + * @return 执行结果(int)，0表示成功 + */ +static int adapter_command(neu_adapter_t *adapter, neu_reqresp_head_t header, + void *data); + +/** + * 适配器响应处理函数，向请求发送者发送响应消息 + * + * @param adapter 适配器指针 + * @param header 请求/响应头指针 + * @param data 响应数据 + * @return 执行结果(int)，0表示成功 + */ static int adapter_response(neu_adapter_t *adapter, neu_reqresp_head_t *header, void *data); + +/** + * 适配器定向响应函数，向指定地址发送响应消息 + * + * @param adapter 适配器指针 + * @param header 请求/响应头指针 + * @param data 响应数据 + * @param dst 目标地址 + * @return 执行结果(int)，0表示成功 + */ static int adapter_responseto(neu_adapter_t * adapter, neu_reqresp_head_t *header, void *data, struct sockaddr_in dst); + +/** + * 注册适配器指标函数 + * + * @param adapter 适配器指针 + * @param name 指标名称 + * @param help 指标帮助信息 + * @param type 指标类型 + * @param init 初始值 + * @return 执行结果(int)，0表示成功 + */ static int adapter_register_metric(neu_adapter_t *adapter, const char *name, const char *help, neu_metric_type_e type, uint64_t init); + +/** + * 更新适配器指标函数 + * + * @param adapter 适配器指针 + * @param metric_name 指标名称 + * @param n 指标新值 + * @param group 组名(可选) + * @return 执行结果(int)，0表示成功 + */ static int adapter_update_metric(neu_adapter_t *adapter, const char *metric_name, uint64_t n, const char *group); + +/** + * 发送响应消息的内联函数 + * + * @param adapter 适配器指针 + * @param header 请求/响应头指针 + * @param data 响应数据 + */ inline static void reply(neu_adapter_t *adapter, neu_reqresp_head_t *header, void *data); + +/** + * 向监控模块发送通知的内联函数 + * + * @param adapter 适配器指针 + * @param event 事件类型 + * @param data 事件数据 + */ inline static void notify_monitor(neu_adapter_t * adapter, neu_reqresp_type_e event, void *data); @@ -95,11 +184,21 @@ static __thread int create_adapter_error = 0; REGISTER_METRIC(adapter, NEU_METRIC_SEND_MSG_ERRORS_TOTAL, 0); \ REGISTER_METRIC(adapter, NEU_METRIC_RECV_MSGS_TOTAL, 0); +/** + * 获取适配器创建过程中的错误码 + * + * @return 错误码 + */ int neu_adapter_error() { return create_adapter_error; } +/** + * 设置适配器创建过程中的错误码 + * + * @param error 错误码 + */ void neu_adapter_set_error(int error) { create_adapter_error = error; @@ -125,6 +224,12 @@ static void *adapter_consumer(void *arg) return NULL; } +/** + * 获取节点对应的日志类别 + * + * @param node 节点名称 + * @return 日志类别指针 + */ static inline zlog_category_t *get_log_category(const char *node) { char name[NEU_NODE_NAME_LEN] = { 0 }; @@ -135,6 +240,13 @@ static inline zlog_category_t *get_log_category(const char *node) return zlog_get_category(name); } +/** + * 创建适配器 + * + * @param info 适配器信息 + * @param load 是否加载现有配置 + * @return 适配器指针，失败时返回NULL + */ neu_adapter_t *neu_adapter_create(neu_adapter_info_t *info, bool load) { int rv = 0; @@ -284,11 +396,24 @@ neu_adapter_t *neu_adapter_create(neu_adapter_info_t *info, bool load) } } +/** + * 获取适配器传输数据端口 + * + * @param adapter 适配器指针 + * @return 端口号 + */ uint16_t neu_adapter_trans_data_port(neu_adapter_t *adapter) { return adapter->trans_data_port; } +/** + * 重命名适配器 + * + * @param adapter 适配器指针 + * @param new_name 新名称 + * @return 执行结果，0表示成功，非0表示错误码 + */ int neu_adapter_rename(neu_adapter_t *adapter, const char *new_name) { char *name = strdup(new_name); @@ -335,6 +460,12 @@ int neu_adapter_rename(neu_adapter_t *adapter, const char *new_name) return 0; } +/** + * 初始化适配器并通知管理器 + * + * @param adapter 适配器指针 + * @param state 初始运行状态 + */ void neu_adapter_init(neu_adapter_t *adapter, neu_node_running_state_e state) { neu_req_node_init_t init = { 0 }; @@ -358,11 +489,23 @@ void neu_adapter_init(neu_adapter_t *adapter, neu_node_running_state_e state) } } +/** + * 获取适配器类型 + * + * @param adapter 适配器指针 + * @return 适配器类型 + */ neu_node_type_e neu_adapter_get_type(neu_adapter_t *adapter) { return adapter->module->type; } +/** + * 获取适配器标签缓存类型 + * + * @param adapter 适配器指针 + * @return 标签缓存类型 + */ neu_tag_cache_type_e neu_adapter_get_tag_cache_type(neu_adapter_t *adapter) { return adapter->module->cache_type; @@ -1199,6 +1342,11 @@ static int adapter_loop(enum neu_event_io_type type, int fd, void *usr_data) return 0; } +/** + * 销毁适配器 + * + * @param adapter 适配器指针 + */ void neu_adapter_destroy(neu_adapter_t *adapter) { nlog_notice("adapter %s destroy", adapter->name); @@ -1237,6 +1385,12 @@ void neu_adapter_destroy(neu_adapter_t *adapter) free(adapter); } +/** + * 反初始化适配器 + * + * @param adapter 适配器指针 + * @return 执行结果(int)，0表示成功 + */ int neu_adapter_uninit(neu_adapter_t *adapter) { if (adapter->module->type == NEU_NA_TYPE_DRIVER) { @@ -1254,6 +1408,12 @@ int neu_adapter_uninit(neu_adapter_t *adapter) return 0; } +/** + * 启动适配器 + * + * @param adapter 适配器指针 + * @return 执行结果(int)，0表示成功 + */ int neu_adapter_start(neu_adapter_t *adapter) { const neu_plugin_intf_funs_t *intf_funs = adapter->module->intf_funs; @@ -1288,6 +1448,12 @@ int neu_adapter_start(neu_adapter_t *adapter) return error; } +/** + * 启动单个适配器 + * + * @param adapter 适配器指针 + * @return 执行结果(int)，0表示成功 + */ int neu_adapter_start_single(neu_adapter_t *adapter) { const neu_plugin_intf_funs_t *intf_funs = adapter->module->intf_funs; @@ -1296,6 +1462,12 @@ int neu_adapter_start_single(neu_adapter_t *adapter) return intf_funs->start(adapter->plugin); } +/** + * 停止适配器 + * + * @param adapter 适配器指针 + * @return 执行结果(int)，0表示成功 + */ int neu_adapter_stop(neu_adapter_t *adapter) { const neu_plugin_intf_funs_t *intf_funs = adapter->module->intf_funs; @@ -1331,6 +1503,13 @@ int neu_adapter_stop(neu_adapter_t *adapter) return error; } +/** + * 设置适配器配置 + * + * @param adapter 适配器指针 + * @param setting 配置字符串 + * @return 执行结果(int)，0表示成功 + */ int neu_adapter_set_setting(neu_adapter_t *adapter, const char *setting) { int rv = -1; @@ -1356,6 +1535,13 @@ int neu_adapter_set_setting(neu_adapter_t *adapter, const char *setting) return rv; } +/** + * 获取适配器配置 + * + * @param adapter 适配器指针 + * @param config 配置字符串指针 + * @return 执行结果(int)，0表示成功 + */ int neu_adapter_get_setting(neu_adapter_t *adapter, char **config) { if (adapter->setting != NULL) { @@ -1366,6 +1552,12 @@ int neu_adapter_get_setting(neu_adapter_t *adapter, char **config) return NEU_ERR_NODE_SETTING_NOT_FOUND; } +/** + * 获取适配器状态 + * + * @param adapter 适配器指针 + * @return 节点状态 + */ neu_node_state_t neu_adapter_get_state(neu_adapter_t *adapter) { neu_node_state_t state = { 0 }; @@ -1378,6 +1570,13 @@ neu_node_state_t neu_adapter_get_state(neu_adapter_t *adapter) return state; } +/** + * 验证适配器标签 + * + * @param adapter 适配器指针 + * @param tag 数据标签指针 + * @return 执行结果(int)，0表示成功 + */ int neu_adapter_validate_tag(neu_adapter_t *adapter, neu_datatag_t *tag) { const neu_plugin_intf_funs_t *intf_funs = adapter->module->intf_funs; @@ -1388,17 +1587,41 @@ int neu_adapter_validate_tag(neu_adapter_t *adapter, neu_datatag_t *tag) return error; } +/** + * 添加定时器 + * + * @param adapter 适配器指针 + * @param param 定时器参数 + * @return 定时器指针 + */ neu_event_timer_t *neu_adapter_add_timer(neu_adapter_t * adapter, neu_event_timer_param_t param) { return neu_event_add_timer(adapter->events, param); } +/** + * 删除定时器 + * + * @param adapter 适配器指针 + * @param timer 定时器指针 + */ void neu_adapter_del_timer(neu_adapter_t *adapter, neu_event_timer_t *timer) { neu_event_del_timer(adapter->events, timer); } +/** + * 注册组指标 + * + * @param adapter 适配器指针 + * @param group_name 组名 + * @param name 指标名称 + * @param help 指标帮助信息 + * @param type 指标类型 + * @param init 初始值 + * @return 执行结果(int)，0表示成功 + */ int neu_adapter_register_group_metric(neu_adapter_t *adapter, const char *group_name, const char *name, const char *help, neu_metric_type_e type, @@ -1412,6 +1635,15 @@ int neu_adapter_register_group_metric(neu_adapter_t *adapter, init); } +/** + * 更新组指标 + * + * @param adapter 适配器指针 + * @param group_name 组名 + * @param metric_name 指标名称 + * @param n 指标新值 + * @return 执行结果(int)，0表示成功 + */ int neu_adapter_update_group_metric(neu_adapter_t *adapter, const char * group_name, const char *metric_name, uint64_t n) @@ -1424,6 +1656,14 @@ int neu_adapter_update_group_metric(neu_adapter_t *adapter, n); } +/** + * 更新组名 + * + * @param adapter 适配器指针 + * @param group_name 旧组名 + * @param new_group_name 新组名 + * @return 执行结果(int)，0表示成功 + */ int neu_adapter_metric_update_group_name(neu_adapter_t *adapter, const char * group_name, const char * new_group_name) @@ -1436,6 +1676,12 @@ int neu_adapter_metric_update_group_name(neu_adapter_t *adapter, new_group_name); } +/** + * 删除组指标 + * + * @param adapter 适配器指针 + * @param group_name 组名 + */ void neu_adapter_del_group_metrics(neu_adapter_t *adapter, const char * group_name) { @@ -1444,6 +1690,13 @@ void neu_adapter_del_group_metrics(neu_adapter_t *adapter, } } +/** + * 发送响应消息的内联函数 + * + * @param adapter 适配器指针 + * @param header 请求/响应头指针 + * @param data 响应数据 + */ inline static void reply(neu_adapter_t *adapter, neu_reqresp_head_t *header, void *data) { @@ -1456,6 +1709,13 @@ inline static void reply(neu_adapter_t *adapter, neu_reqresp_head_t *header, } } +/** + * 向监控模块发送通知的内联函数 + * + * @param adapter 适配器指针 + * @param event 事件类型 + * @param data 事件数据 + */ inline static void notify_monitor(neu_adapter_t * adapter, neu_reqresp_type_e event, void *data) { diff --git a/src/adapter/driver/cache.c b/src/adapter/driver/cache.c index fa4fe3953..18006ce1f 100644 --- a/src/adapter/driver/cache.c +++ b/src/adapter/driver/cache.c @@ -52,9 +52,13 @@ struct neu_driver_cache { struct elem *table; }; -// static void update_tag_error(neu_driver_cache_t *cache, const char *group, -// const char *tag, int64_t timestamp, int error); - +/** + * 将组名和标签名转换为缓存中的键 + * + * @param group 组名 + * @param tag 标签名 + * @return 生成的键结构体 + */ inline static tkey_t to_key(const char *group, const char *tag) { tkey_t key = { 0 }; @@ -65,6 +69,11 @@ inline static tkey_t to_key(const char *group, const char *tag) return key; } +/** + * 创建新的驱动缓存实例 + * + * @return 新创建的驱动缓存实例 + */ neu_driver_cache_t *neu_driver_cache_new() { neu_driver_cache_t *cache = calloc(1, sizeof(neu_driver_cache_t)); @@ -74,6 +83,11 @@ neu_driver_cache_t *neu_driver_cache_new() return cache; } +/** + * 销毁驱动缓存实例，释放所有资源 + * + * @param cache 驱动缓存实例 + */ void neu_driver_cache_destroy(neu_driver_cache_t *cache) { struct elem *elem = NULL; @@ -98,12 +112,14 @@ void neu_driver_cache_destroy(neu_driver_cache_t *cache) free(cache); } -// void neu_driver_cache_error(neu_driver_cache_t *cache, const char *group, -// const char *tag, int64_t timestamp, int32_t error) -//{ -// update_tag_error(cache, group, tag, timestamp, error); -//} - +/** + * 添加标签到缓存 + * + * @param cache 驱动缓存实例 + * @param group 组名 + * @param tag 标签名 + * @param value 标签初始值 + */ void neu_driver_cache_add(neu_driver_cache_t *cache, const char *group, const char *tag, neu_dvalue_t value) { @@ -129,6 +145,18 @@ void neu_driver_cache_add(neu_driver_cache_t *cache, const char *group, pthread_mutex_unlock(&cache->mtx); } +/** + * 更新缓存中的标签值并控制变更标志 + * + * @param cache 驱动缓存实例 + * @param group 组名 + * @param tag 标签名 + * @param timestamp 时间戳 + * @param value 新值 + * @param metas 元数据数组 + * @param n_meta 元数据数量 + * @param change 是否强制标记为已变更 + */ void neu_driver_cache_update_change(neu_driver_cache_t *cache, const char *group, const char *tag, int64_t timestamp, neu_dvalue_t value, @@ -243,6 +271,17 @@ void neu_driver_cache_update_change(neu_driver_cache_t *cache, pthread_mutex_unlock(&cache->mtx); } +/** + * 更新缓存中的标签值 + * + * @param cache 驱动缓存实例 + * @param group 组名 + * @param tag 标签名 + * @param timestamp 时间戳 + * @param value 新值 + * @param metas 元数据数组 + * @param n_meta 元数据数量 + */ void neu_driver_cache_update(neu_driver_cache_t *cache, const char *group, const char *tag, int64_t timestamp, neu_dvalue_t value, neu_tag_meta_t *metas, @@ -252,6 +291,17 @@ void neu_driver_cache_update(neu_driver_cache_t *cache, const char *group, n_meta, false); } +/** + * 获取缓存中的标签值和元数据 + * + * @param cache 驱动缓存实例 + * @param group 组名 + * @param tag 标签名 + * @param value 输出参数，存放获取的值 + * @param metas 输出参数，存放获取的元数据 + * @param n_meta 元数据缓冲区大小 + * @return 0表示成功，-1表示标签不存在 + */ int neu_driver_cache_meta_get(neu_driver_cache_t *cache, const char *group, const char *tag, neu_driver_cache_value_t *value, neu_tag_meta_t *metas, int n_meta) @@ -333,6 +383,17 @@ int neu_driver_cache_meta_get(neu_driver_cache_t *cache, const char *group, return ret; } +/** + * 获取缓存中已变更的标签值和元数据 + * + * @param cache 驱动缓存实例 + * @param group 组名 + * @param tag 标签名 + * @param value 输出参数，存放获取的值 + * @param metas 输出参数，存放获取的元数据 + * @param n_meta 元数据缓冲区大小 + * @return 0表示成功且有变更，-1表示标签不存在或无变更 + */ int neu_driver_cache_meta_get_changed(neu_driver_cache_t *cache, const char *group, const char *tag, neu_driver_cache_value_t *value, @@ -418,6 +479,15 @@ int neu_driver_cache_meta_get_changed(neu_driver_cache_t *cache, return ret; } +/** + * 获取缓存中的标签值 + * + * @param cache 驱动缓存实例 + * @param group 组名 + * @param tag 标签名 + * @param value 输出参数，存放获取的值 + * @return 0表示成功，-1表示标签不存在 + */ int neu_driver_cache_get(neu_driver_cache_t *cache, const char *group, const char *tag, neu_driver_cache_value_t *value) { @@ -495,6 +565,15 @@ int neu_driver_cache_get(neu_driver_cache_t *cache, const char *group, return ret; } +/** + * 获取缓存中已变更的标签值 + * + * @param cache 驱动缓存实例 + * @param group 组名 + * @param tag 标签名 + * @param value 输出参数，存放获取的值 + * @return 0表示成功且有变更，-1表示标签不存在或无变更 + */ int neu_driver_cache_get_changed(neu_driver_cache_t *cache, const char *group, const char * tag, neu_driver_cache_value_t *value) @@ -575,6 +654,13 @@ int neu_driver_cache_get_changed(neu_driver_cache_t *cache, const char *group, return ret; } +/** + * 从缓存中删除标签 + * + * @param cache 驱动缓存实例 + * @param group 组名 + * @param tag 标签名 + */ void neu_driver_cache_del(neu_driver_cache_t *cache, const char *group, const char *tag) { diff --git a/src/adapter/driver/driver.c b/src/adapter/driver/driver.c index b5283c47f..a3b2dfb81 100644 --- a/src/adapter/driver/driver.c +++ b/src/adapter/driver/driver.c @@ -80,35 +80,161 @@ struct neu_adapter_driver { struct group *groups; }; -static int report_callback(void *usr_data); +/** + * 数据上报回调函数 + * + * @param usr_data 用户数据，包含组信息 + * @return 0表示成功 + */ +static int report_callback(void *usr_data); + +/** + * 向指定应用发送组数据 + * + * @param driver 驱动适配器实例 + * @param group 组结构体 + * @param dst 目标地址 + */ static void report_to_app(neu_adapter_driver_t *driver, group_t *group, struct sockaddr_in dst); -static int read_callback(void *usr_data); -static int write_callback(void *usr_data); +/** + * 读取回调函数 + * + * @param usr_data 用户数据，包含组信息 + * @return 0表示成功 + */ +static int read_callback(void *usr_data); + +/** + * 写入回调函数 + * + * @param usr_data 用户数据，包含组信息 + * @return 0表示成功 + */ +static int write_callback(void *usr_data); + +/** + * 读取组中的标签数据 + * + * @param timestamp 当前时间戳 + * @param timeout 超时时间 + * @param cache_type 缓存类型 + * @param cache 缓存实例 + * @param group 组名 + * @param tags 标签数组 + * @param tag_values 输出参数，存放标签值的数组 + */ static void read_group(int64_t timestamp, int64_t timeout, neu_tag_cache_type_e cache_type, neu_driver_cache_t *cache, const char *group, UT_array *tags, UT_array *tag_values); + +/** + * 读取并上报组中的标签数据 + * + * @param timestamp 当前时间戳 + * @param timeout 超时时间 + * @param cache_type 缓存类型 + * @param cache 缓存实例 + * @param group 组名 + * @param tags 标签数组 + * @param tag_values 输出参数，存放标签值的数组 + */ static void read_report_group(int64_t timestamp, int64_t timeout, neu_tag_cache_type_e cache_type, neu_driver_cache_t *cache, const char *group, UT_array *tags, UT_array *tag_values); + +/** + * 更新标签值（不含元数据） + * + * @param adapter 适配器实例 + * @param group 组名 + * @param tag 标签名 + * @param value 更新的值 + */ static void update(neu_adapter_t *adapter, const char *group, const char *tag, neu_dvalue_t value); + +/** + * 立即更新标签值并通知订阅者 + * + * @param adapter 适配器实例 + * @param group 组名 + * @param tag 标签名 + * @param value 更新的值 + * @param metas 元数据数组 + * @param n_meta 元数据数量 + */ static void update_im(neu_adapter_t *adapter, const char *group, const char *tag, neu_dvalue_t value, neu_tag_meta_t *metas, int n_meta); + +/** + * 更新标签值并添加元数据信息 + * + * @param adapter 适配器实例 + * @param group 组名 + * @param tag 标签名，为NULL时表示整组 + * @param value 更新的值 + * @param metas 元数据数组 + * @param n_meta 元数据数量 + */ static void update_with_meta(neu_adapter_t *adapter, const char *group, const char *tag, neu_dvalue_t value, neu_tag_meta_t *metas, int n_meta); + +/** + * 处理写标签请求的响应函数 + * + * @param adapter 适配器实例 + * @param r 请求指针 + * @param error 错误码 + */ static void write_response(neu_adapter_t *adapter, void *r, neu_error error); -static group_t * find_group(neu_adapter_driver_t *driver, const char *name); -static void store_write_tag(group_t *group, to_be_write_tag_t *tag); + +/** + * 查找组 + * + * @param driver 驱动适配器实例 + * @param name 组名 + * @return 找到的组指针，未找到返回NULL + */ +static group_t *find_group(neu_adapter_driver_t *driver, const char *name); + +/** + * 存储待写入的标签 + * + * @param group 组结构体 + * @param tag 待写入的标签 + */ +static void store_write_tag(group_t *group, to_be_write_tag_t *tag); + +/** + * 启动组定时器 + * + * @param driver 驱动适配器实例 + * @param grp 组结构体 + */ static inline void start_group_timer(neu_adapter_driver_t *driver, group_t * grp); + +/** + * 停止组定时器 + * + * @param driver 驱动适配器实例 + * @param grp 组结构体 + */ static inline void stop_group_timer(neu_adapter_driver_t *driver, group_t *grp); +/** + * 处理写标签请求的响应函数 + * + * @param adapter 适配器实例 + * @param r 请求指针 + * @param error 错误码 + */ static void write_response(neu_adapter_t *adapter, void *r, neu_error error) { neu_reqresp_head_t *req = (neu_reqresp_head_t *) r; @@ -129,6 +255,16 @@ static void write_response(neu_adapter_t *adapter, void *r, neu_error error) adapter->cb_funs.response(adapter, req, &nerror); } +/** + * 更新标签值并添加元数据信息 + * + * @param adapter 适配器实例 + * @param group 组名 + * @param tag 标签名，为NULL时表示整组 + * @param value 更新的值 + * @param metas 元数据数组 + * @param n_meta 元数据数量 + */ static void update_with_meta(neu_adapter_t *adapter, const char *group, const char *tag, neu_dvalue_t value, neu_tag_meta_t *metas, int n_meta) @@ -179,6 +315,16 @@ static void update_with_meta(neu_adapter_t *adapter, const char *group, global_timestamp, n_meta); } +/** + * 立即更新标签值并通知订阅者 + * + * @param adapter 适配器实例 + * @param group 组名 + * @param tag 标签名 + * @param value 更新的值 + * @param metas 元数据数组 + * @param n_meta 元数据数量 + */ static void update_im(neu_adapter_t *adapter, const char *group, const char *tag, neu_dvalue_t value, neu_tag_meta_t *metas, int n_meta) @@ -273,12 +419,25 @@ static void update_im(neu_adapter_t *adapter, const char *group, free(data); } +/** + * 更新标签值（不含元数据） + * + * @param adapter 适配器实例 + * @param group 组名 + * @param tag 标签名 + * @param value 更新的值 + */ static void update(neu_adapter_t *adapter, const char *group, const char *tag, neu_dvalue_t value) { update_with_meta(adapter, group, tag, value, NULL, 0); } +/** + * 创建驱动适配器实例 + * + * @return 创建的驱动适配器实例 + */ neu_adapter_driver_t *neu_adapter_driver_create() { neu_adapter_driver_t *driver = calloc(1, sizeof(neu_adapter_driver_t)); @@ -293,24 +452,47 @@ neu_adapter_driver_t *neu_adapter_driver_create() return driver; } +/** + * 销毁驱动适配器实例 + * + * @param driver 驱动适配器实例 + */ void neu_adapter_driver_destroy(neu_adapter_driver_t *driver) { neu_event_close(driver->driver_events); neu_driver_cache_destroy(driver->cache); } +/** + * 启动驱动适配器 + * + * @param driver 驱动适配器实例 + * @return 0表示成功，其他值表示失败 + */ int neu_adapter_driver_start(neu_adapter_driver_t *driver) { (void) driver; return 0; } +/** + * 停止驱动适配器 + * + * @param driver 驱动适配器实例 + * @return 0表示成功，其他值表示失败 + */ int neu_adapter_driver_stop(neu_adapter_driver_t *driver) { (void) driver; return 0; } +/** + * 初始化驱动适配器 + * + * @param driver 驱动适配器实例 + * @return 0表示成功，其他值表示失败 + */ int neu_adapter_driver_init(neu_adapter_driver_t *driver) { (void) driver; @@ -318,6 +500,12 @@ int neu_adapter_driver_init(neu_adapter_driver_t *driver) return 0; } +/** + * 取消初始化驱动适配器，释放所有组和标签资源 + * + * @param driver 驱动适配器实例 + * @return 0表示成功，其他值表示失败 + */ int neu_adapter_driver_uninit(neu_adapter_driver_t *driver) { group_t *el = NULL, *tmp = NULL; @@ -350,6 +538,12 @@ int neu_adapter_driver_uninit(neu_adapter_driver_t *driver) return 0; } +/** + * 启动组定时器 + * + * @param driver 驱动适配器实例 + * @param grp 组结构体 + */ static inline void start_group_timer(neu_adapter_driver_t *driver, group_t *grp) { uint32_t interval = neu_group_get_interval(grp->group); @@ -382,6 +576,11 @@ static inline void start_group_timer(neu_adapter_driver_t *driver, group_t *grp) grp->write = neu_event_add_timer(driver->driver_events, param); } +/** + * 启动所有组的定时器 + * + * @param driver 驱动适配器实例 + */ void neu_adapter_driver_start_group_timer(neu_adapter_driver_t *driver) { group_t *el = NULL, *tmp = NULL; @@ -398,6 +597,12 @@ void neu_adapter_driver_start_group_timer(neu_adapter_driver_t *driver) &driver->adapter, NEU_METRIC_TAGS_TOTAL, driver->tag_cnt, NULL); } +/** + * 停止组定时器 + * + * @param driver 驱动适配器实例 + * @param grp 组结构体 + */ static inline void stop_group_timer(neu_adapter_driver_t *driver, group_t *grp) { if (grp->report) { @@ -414,6 +619,11 @@ static inline void stop_group_timer(neu_adapter_driver_t *driver, group_t *grp) } } +/** + * 停止所有组的定时器 + * + * @param driver 驱动适配器实例 + */ void neu_adapter_driver_stop_group_timer(neu_adapter_driver_t *driver) { group_t *el = NULL, *tmp = NULL; @@ -421,6 +631,12 @@ void neu_adapter_driver_stop_group_timer(neu_adapter_driver_t *driver) HASH_ITER(hh, driver->groups, el, tmp) { stop_group_timer(driver, el); } } +/** + * 读取组中所有标签的值 + * + * @param driver 驱动适配器实例 + * @param req 读取组请求 + */ void neu_adapter_driver_read_group(neu_adapter_driver_t *driver, neu_reqresp_head_t * req) { @@ -494,6 +710,13 @@ void neu_adapter_driver_read_group(neu_adapter_driver_t *driver, driver->adapter.cb_funs.response(&driver->adapter, req, &resp); } +/** + * 修正数据值的格式和字节序 + * + * @param tag 标签结构体 + * @param value_type 值类型 + * @param value 需要修正的值指针 + */ static void fix_value(neu_datatag_t *tag, neu_type_e value_type, neu_dvalue_t *value) { @@ -595,6 +818,14 @@ static void fix_value(neu_datatag_t *tag, neu_type_e value_type, } } +/** + * 计算小数点转换 + * + * @param tag_type 标签类型 + * @param value_type 值类型 + * @param value 值指针 + * @param decimal 小数因子 + */ static void cal_decimal(neu_type_e tag_type, neu_type_e value_type, neu_value_u *value, double decimal) { @@ -673,6 +904,12 @@ static void cal_decimal(neu_type_e tag_type, neu_type_e value_type, } } +/** + * 批量写入多个标签的值 + * + * @param driver 驱动适配器实例 + * @param req 写入标签请求 + */ void neu_adapter_driver_write_tags(neu_adapter_driver_t *driver, neu_reqresp_head_t * req) { @@ -747,6 +984,12 @@ void neu_adapter_driver_write_tags(neu_adapter_driver_t *driver, store_write_tag(g, &wtag); } +/** + * 批量写入多个组的多个标签值 + * + * @param driver 驱动适配器实例 + * @param req 写入组标签请求 + */ void neu_adapter_driver_write_gtags(neu_adapter_driver_t *driver, neu_reqresp_head_t * req) { @@ -843,6 +1086,12 @@ void neu_adapter_driver_write_gtags(neu_adapter_driver_t *driver, store_write_tag(first_g, &wtag); } +/** + * 写入单个标签的值 + * + * @param driver 驱动适配器实例 + * @param req 写入标签请求 + */ void neu_adapter_driver_write_tag(neu_adapter_driver_t *driver, neu_reqresp_head_t * req) { @@ -911,6 +1160,14 @@ void neu_adapter_driver_write_tag(neu_adapter_driver_t *driver, neu_adapter_register_group_metric((adapter), group, name, name##_HELP, \ name##_TYPE, (init)) +/** + * 添加新的组 + * + * @param driver 驱动适配器实例 + * @param name 组名 + * @param interval 更新间隔时间(毫秒) + * @return NEU_ERR_SUCCESS表示成功，其他值表示失败 + */ int neu_adapter_driver_add_group(neu_adapter_driver_t *driver, const char *name, uint32_t interval) { @@ -960,6 +1217,15 @@ int neu_adapter_driver_add_group(neu_adapter_driver_t *driver, const char *name, return ret; } +/** + * 更新组的名称和间隔时间 + * + * @param driver 驱动适配器实例 + * @param name 原组名 + * @param new_name 新组名，为NULL则不修改 + * @param interval 新间隔时间，值小于NEU_GROUP_INTERVAL_LIMIT则不修改 + * @return 0表示成功，其他值表示失败 + */ int neu_adapter_driver_update_group(neu_adapter_driver_t *driver, const char *name, const char *new_name, uint32_t interval) @@ -1030,6 +1296,13 @@ int neu_adapter_driver_update_group(neu_adapter_driver_t *driver, return ret; } +/** + * 删除组 + * + * @param driver 驱动适配器实例 + * @param name 组名 + * @return NEU_ERR_SUCCESS表示成功，其他值表示失败 + */ int neu_adapter_driver_del_group(neu_adapter_driver_t *driver, const char *name) { group_t *find = NULL; @@ -1094,6 +1367,13 @@ int neu_adapter_driver_del_group(neu_adapter_driver_t *driver, const char *name) return ret; } +/** + * 查找组 + * + * @param driver 驱动适配器实例 + * @param name 组名 + * @return 找到的组指针，未找到返回NULL + */ static group_t *find_group(neu_adapter_driver_t *driver, const char *name) { group_t *find = NULL; @@ -1102,6 +1382,14 @@ static group_t *find_group(neu_adapter_driver_t *driver, const char *name) return find; } + +/** + * 判断组是否存在 + * + * @param driver 驱动适配器实例 + * @param name 组名 + * @return NEU_ERR_SUCCESS表示组存在，NEU_ERR_GROUP_NOT_EXIST表示组不存在 + */ int neu_adapter_driver_group_exist(neu_adapter_driver_t *driver, const char * name) { @@ -1116,6 +1404,12 @@ int neu_adapter_driver_group_exist(neu_adapter_driver_t *driver, return ret; } +/** + * 获取所有组的信息 + * + * @param driver 驱动适配器实例 + * @return 包含所有组信息的数组 + */ UT_array *neu_adapter_driver_get_group(neu_adapter_driver_t *driver) { group_t * el = NULL, *tmp = NULL; @@ -1138,6 +1432,15 @@ UT_array *neu_adapter_driver_get_group(neu_adapter_driver_t *driver) return groups; } +/** + * 尝试添加标签 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @param tags 标签数组 + * @param n_tag 标签数量 + * @return 0表示成功，其他值表示失败 + */ int neu_adapter_driver_try_add_tag(neu_adapter_driver_t *driver, const char *group, neu_datatag_t *tags, int n_tag) @@ -1150,6 +1453,15 @@ int neu_adapter_driver_try_add_tag(neu_adapter_driver_t *driver, return ret; } +/** + * 加载标签 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @param tags 标签数组 + * @param n_tag 标签数量 + * @return 0表示成功，其他值表示失败 + */ int neu_adapter_driver_load_tag(neu_adapter_driver_t *driver, const char *group, neu_datatag_t *tags, int n_tag) { @@ -1161,6 +1473,13 @@ int neu_adapter_driver_load_tag(neu_adapter_driver_t *driver, const char *group, return ret; } +/** + * 尝试删除标签 + * + * @param driver 驱动适配器实例 + * @param n_tag 标签数量 + * @return 0表示成功，其他值表示失败 + */ int neu_adapter_driver_try_del_tag(neu_adapter_driver_t *driver, int n_tag) { int ret = 0; @@ -1171,6 +1490,14 @@ int neu_adapter_driver_try_del_tag(neu_adapter_driver_t *driver, int n_tag) return ret; } +/** + * 验证标签参数是否有效 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @param tag 待验证的标签 + * @return NEU_ERR_SUCCESS表示有效，其他值表示无效 + */ int neu_adapter_driver_validate_tag(neu_adapter_driver_t *driver, const char *group, neu_datatag_t *tag) { @@ -1210,6 +1537,14 @@ int neu_adapter_driver_validate_tag(neu_adapter_driver_t *driver, return NEU_ERR_SUCCESS; } +/** + * 添加标签 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @param tag 标签 + * @return NEU_ERR_SUCCESS表示成功，其他值表示失败 + */ int neu_adapter_driver_add_tag(neu_adapter_driver_t *driver, const char *group, neu_datatag_t *tag) { @@ -1241,6 +1576,14 @@ int neu_adapter_driver_add_tag(neu_adapter_driver_t *driver, const char *group, return ret; } +/** + * 删除标签 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @param tag 标签名 + * @return NEU_ERR_SUCCESS表示成功，其他值表示失败 + */ int neu_adapter_driver_del_tag(neu_adapter_driver_t *driver, const char *group, const char *tag) { @@ -1267,6 +1610,14 @@ int neu_adapter_driver_del_tag(neu_adapter_driver_t *driver, const char *group, return ret; } +/** + * 更新标签 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @param tag 标签 + * @return NEU_ERR_SUCCESS表示成功，其他值表示失败 + */ int neu_adapter_driver_update_tag(neu_adapter_driver_t *driver, const char *group, neu_datatag_t *tag) { @@ -1308,6 +1659,14 @@ int neu_adapter_driver_update_tag(neu_adapter_driver_t *driver, return ret; } +/** + * 获取组中所有标签 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @param tags 输出参数，存放标签数组的指针 + * @return NEU_ERR_SUCCESS表示成功，其他值表示失败 + */ int neu_adapter_driver_get_tag(neu_adapter_driver_t *driver, const char *group, UT_array **tags) { @@ -1324,6 +1683,15 @@ int neu_adapter_driver_get_tag(neu_adapter_driver_t *driver, const char *group, return ret; } +/** + * 查询标签 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @param name 标签名，为空时返回所有标签 + * @param tags 输出参数，存放标签数组的指针 + * @return NEU_ERR_SUCCESS表示成功，其他值表示失败 + */ int neu_adapter_driver_query_tag(neu_adapter_driver_t *driver, const char *group, const char *name, UT_array **tags) @@ -1345,6 +1713,13 @@ int neu_adapter_driver_query_tag(neu_adapter_driver_t *driver, return ret; } +/** + * 获取带值的标签 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @param tags 输出参数，存放标签数组的指针 + */ void neu_adapter_driver_get_value_tag(neu_adapter_driver_t *driver, const char *group, UT_array **tags) { @@ -1370,6 +1745,13 @@ void neu_adapter_driver_get_value_tag(neu_adapter_driver_t *driver, } } +/** + * 获取可读标签 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @return 可读标签数组 + */ UT_array *neu_adapter_driver_get_read_tag(neu_adapter_driver_t *driver, const char * group) { @@ -1384,6 +1766,14 @@ UT_array *neu_adapter_driver_get_read_tag(neu_adapter_driver_t *driver, return tags; } +/** + * 获取指定标签 + * + * @param driver 驱动适配器实例 + * @param group 组名 + * @param tag 标签名 + * @return 指定标签的数组，如未找到返回NULL + */ UT_array *neu_adapter_driver_get_ptag(neu_adapter_driver_t *driver, const char *group, const char *tag) { @@ -1403,6 +1793,13 @@ UT_array *neu_adapter_driver_get_ptag(neu_adapter_driver_t *driver, return tags; } +/** + * 向指定应用发送组数据 + * + * @param driver 驱动适配器实例 + * @param group 组结构体 + * @param dst 目标地址 + */ static void report_to_app(neu_adapter_driver_t *driver, group_t *group, struct sockaddr_in dst) { @@ -1451,6 +1848,12 @@ static void report_to_app(neu_adapter_driver_t *driver, group_t *group, free(data); } +/** + * 数据上报回调函数 + * + * @param usr_data 用户数据，包含组信息 + * @return 0表示成功 + */ static int report_callback(void *usr_data) { group_t * group = (group_t *) usr_data; @@ -1520,6 +1923,15 @@ static int report_callback(void *usr_data) return 0; } +/** + * 组变更处理函数 + * + * @param arg 组指针 + * @param timestamp 时间戳 + * @param static_tags 静态标签数组 + * @param other_tags 其他标签数组 + * @param interval 组间隔时间 + */ static void group_change(void *arg, int64_t timestamp, UT_array *static_tags, UT_array *other_tags, uint32_t interval) { @@ -1590,6 +2002,12 @@ static void group_change(void *arg, int64_t timestamp, UT_array *static_tags, timestamp); } +/** + * 写入回调函数 + * + * @param usr_data 用户数据，包含组信息 + * @return 0表示成功 + */ static int write_callback(void *usr_data) { group_t * group = (group_t *) usr_data; @@ -1622,6 +2040,12 @@ static int write_callback(void *usr_data) return 0; } +/** + * 读取回调函数 + * + * @param usr_data 用户数据，包含组信息 + * @return 0表示成功 + */ static int read_callback(void *usr_data) { group_t * group = (group_t *) usr_data; @@ -1652,6 +2076,17 @@ static int read_callback(void *usr_data) return 0; } +/** + * 读取并上报组中的标签数据 + * + * @param timestamp 当前时间戳 + * @param timeout 超时时间 + * @param cache_type 缓存类型 + * @param cache 缓存实例 + * @param group 组名 + * @param tags 标签数组 + * @param tag_values 输出参数，存放标签值的数组 + */ static void read_report_group(int64_t timestamp, int64_t timeout, neu_tag_cache_type_e cache_type, neu_driver_cache_t *cache, const char *group, @@ -1822,6 +2257,17 @@ static void read_report_group(int64_t timestamp, int64_t timeout, } } +/** + * 读取组中的标签数据 + * + * @param timestamp 当前时间戳 + * @param timeout 超时时间 + * @param cache_type 缓存类型 + * @param cache 缓存实例 + * @param group 组名 + * @param tags 标签数组 + * @param tag_values 输出参数，存放标签值的数组 + */ static void read_group(int64_t timestamp, int64_t timeout, neu_tag_cache_type_e cache_type, neu_driver_cache_t *cache, const char *group, @@ -1981,6 +2427,12 @@ static void read_group(int64_t timestamp, int64_t timeout, } } +/** + * 存储待写入的标签 + * + * @param group 组结构体 + * @param tag 待写入的标签 + */ static void store_write_tag(group_t *group, to_be_write_tag_t *tag) { pthread_mutex_lock(&group->wt_mtx); @@ -1988,6 +2440,12 @@ static void store_write_tag(group_t *group, to_be_write_tag_t *tag) pthread_mutex_unlock(&group->wt_mtx); } +/** + * 处理订阅请求 + * + * @param driver 驱动适配器实例 + * @param req 订阅请求 + */ void neu_adapter_driver_subscribe(neu_adapter_driver_t *driver, neu_req_subscribe_t * req) { @@ -2023,6 +2481,12 @@ void neu_adapter_driver_subscribe(neu_adapter_driver_t *driver, report_to_app(driver, find, sub_app.addr); } +/** + * 处理取消订阅请求 + * + * @param driver 驱动适配器实例 + * @param req 取消订阅请求 + */ void neu_adapter_driver_unsubscribe(neu_adapter_driver_t * driver, neu_req_unsubscribe_t *req) { diff --git a/src/adapter/msg_q.c b/src/adapter/msg_q.c index 6e2b1bded..98cacdb86 100644 --- a/src/adapter/msg_q.c +++ b/src/adapter/msg_q.c @@ -38,6 +38,13 @@ struct adapter_msg_q { pthread_cond_t cond; }; +/** + * 创建新的适配器消息队列 + * + * @param name 队列名称 + * @param size 队列最大容量 + * @return 返回新创建的消息队列指针 + */ adapter_msg_q_t *adapter_msg_q_new(const char *name, uint32_t size) { struct adapter_msg_q *q = calloc(1, sizeof(struct adapter_msg_q)); @@ -51,6 +58,11 @@ adapter_msg_q_t *adapter_msg_q_new(const char *name, uint32_t size) return q; } +/** + * 释放适配器消息队列资源 + * + * @param q 消息队列指针 + */ void adapter_msg_q_free(adapter_msg_q_t *q) { struct item *tmp = NULL, *elt = NULL; @@ -70,6 +82,13 @@ void adapter_msg_q_free(adapter_msg_q_t *q) free(q); } +/** + * 向消息队列推送消息 + * + * @param q 消息队列指针 + * @param msg 要推送的消息 + * @return 成功返回0，队列已满返回-1 + */ int adapter_msg_q_push(adapter_msg_q_t *q, neu_msg_t *msg) { int ret = -1; @@ -93,6 +112,13 @@ int adapter_msg_q_push(adapter_msg_q_t *q, neu_msg_t *msg) return ret; } +/** + * 从消息队列弹出消息 + * + * @param q 消息队列指针 + * @param p_data 输出参数，用于接收弹出的消息 + * @return 弹出消息后队列中剩余的消息数量 + */ uint32_t adapter_msg_q_pop(adapter_msg_q_t *q, neu_msg_t **p_data) { uint32_t ret = 0; diff --git a/src/adapter/storage.c b/src/adapter/storage.c index d4b00812d..00af04103 100644 --- a/src/adapter/storage.c +++ b/src/adapter/storage.c @@ -23,16 +23,35 @@ #include "driver/driver_internal.h" #include "storage.h" +/** + * 保存节点运行状态到持久化存储 + * + * @param node 节点名称 + * @param state 节点运行状态 + */ void adapter_storage_state(const char *node, neu_node_running_state_e state) { neu_persister_update_node_state(node, state); } +/** + * 保存节点配置到持久化存储 + * + * @param node 节点名称 + * @param setting 节点配置内容（JSON字符串） + */ void adapter_storage_setting(const char *node, const char *setting) { neu_persister_store_node_setting(node, setting); } +/** + * 添加数据组信息到持久化存储 + * + * @param node 节点名称 + * @param group 数据组名称 + * @param interval 数据组采集间隔 + */ void adapter_storage_add_group(const char *node, const char *group, uint32_t interval) { @@ -44,6 +63,14 @@ void adapter_storage_add_group(const char *node, const char *group, neu_persister_store_group(node, &info); } +/** + * 更新数据组信息到持久化存储 + * + * @param node 节点名称 + * @param group 原数据组名称 + * @param new_name 新数据组名称 + * @param interval 数据组采集间隔 + */ void adapter_storage_update_group(const char *node, const char *group, const char *new_name, uint32_t interval) { @@ -59,11 +86,24 @@ void adapter_storage_update_group(const char *node, const char *group, } } +/** + * 从持久化存储中删除数据组 + * + * @param node 节点名称 + * @param group 数据组名称 + */ void adapter_storage_del_group(const char *node, const char *group) { neu_persister_delete_group(node, group); } +/** + * 添加单个数据标签到持久化存储 + * + * @param node 节点名称 + * @param group 数据组名称 + * @param tag 数据标签 + */ void adapter_storage_add_tag(const char *node, const char *group, const neu_datatag_t *tag) { @@ -74,6 +114,14 @@ void adapter_storage_add_tag(const char *node, const char *group, } } +/** + * 批量添加数据标签到持久化存储 + * + * @param node 节点名称 + * @param group 数据组名称 + * @param tags 数据标签数组 + * @param n 数据标签数量 + */ void adapter_storage_add_tags(const char *node, const char *group, const neu_datatag_t *tags, size_t n) { @@ -92,6 +140,13 @@ void adapter_storage_add_tags(const char *node, const char *group, } } +/** + * 更新数据标签到持久化存储 + * + * @param node 节点名称 + * @param group 数据组名称 + * @param tag 数据标签 + */ void adapter_storage_update_tag(const char *node, const char *group, const neu_datatag_t *tag) { @@ -102,6 +157,13 @@ void adapter_storage_update_tag(const char *node, const char *group, } } +/** + * 更新数据标签值到持久化存储 + * + * @param node 节点名称 + * @param group 数据组名称 + * @param tag 数据标签 + */ void adapter_storage_update_tag_value(const char *node, const char *group, const neu_datatag_t *tag) { @@ -112,6 +174,13 @@ void adapter_storage_update_tag_value(const char *node, const char *group, } } +/** + * 从持久化存储中删除数据标签 + * + * @param node 节点名称 + * @param group 数据组名称 + * @param name 数据标签名称 + */ void adapter_storage_del_tag(const char *node, const char *group, const char *name) { @@ -121,6 +190,13 @@ void adapter_storage_del_tag(const char *node, const char *group, } } +/** + * 从持久化存储加载节点配置 + * + * @param node 节点名称 + * @param setting 输出参数，用于接收节点配置 + * @return 成功返回0，失败返回-1 + */ int adapter_load_setting(const char *node, char **setting) { int rv = neu_persister_load_node_setting(node, (const char **) setting); @@ -132,6 +208,12 @@ int adapter_load_setting(const char *node, char **setting) return 0; } +/** + * 从持久化存储加载数据组和标签 + * + * @param driver 驱动适配器 + * @return 成功返回0，失败返回错误码 + */ int adapter_load_group_and_tag(neu_adapter_driver_t *driver) { UT_array * group_infos = NULL; diff --git a/src/parser/neu_json_error.c b/src/parser/neu_json_error.c index feac6b810..18488c0d2 100644 --- a/src/parser/neu_json_error.c +++ b/src/parser/neu_json_error.c @@ -29,6 +29,13 @@ #include "json/neu_json_error.h" +/** + * 编码错误响应到JSON + * + * @param json_object JSON对象指针 + * @param param 要编码的neu_json_error_resp_t结构体指针 + * @return 成功返回0，失败返回非0 + */ int neu_json_encode_error_resp(void *json_object, void *param) { int ret = 0; diff --git a/src/parser/neu_json_fn.c b/src/parser/neu_json_fn.c index fec85da98..a4cbb554e 100644 --- a/src/parser/neu_json_fn.c +++ b/src/parser/neu_json_fn.c @@ -30,6 +30,14 @@ #include "json/neu_json_param.h" #include "json/neu_json_rw.h" +/** + * 使用指定的编码函数将数据编码为JSON字符串 + * + * @param param 要编码的数据 + * @param fn 编码函数指针 + * @param result 输出参数，指向编码后的JSON字符串 + * @return 成功返回0，失败返回-1 + */ int neu_json_encode_by_fn(void *param, neu_json_encode_fn fn, char **result) { void *object = neu_json_encode_new(); @@ -46,6 +54,16 @@ int neu_json_encode_by_fn(void *param, neu_json_encode_fn fn, char **result) return ret; } +/** + * 使用指定的编码函数和MQTT编码函数将数据编码为JSON字符串 + * + * @param param 要编码的数据 + * @param fn 编码函数指针 + * @param mqtt_param MQTT相关参数 + * @param mqtt_fn MQTT编码函数指针 + * @param result 输出参数，指向编码后的JSON字符串 + * @return 成功返回0，失败返回-1 + */ int neu_json_encode_with_mqtt(void *param, neu_json_encode_fn fn, void *mqtt_param, neu_json_encode_fn mqtt_fn, char **result) @@ -71,6 +89,16 @@ int neu_json_encode_with_mqtt(void *param, neu_json_encode_fn fn, return ret; } +/** + * 从JSON字符串中解析参数 + * + * @param buf 包含JSON数据的字符串 + * @param err_param 错误时输出的参数名称 + * @param n 参数个数 + * @param ele 第一个neu_json_elem_t参数 + * @param ... 更多neu_json_elem_t参数 + * @return 成功返回0，失败返回-1 + */ int neu_parse_param(const char *buf, char **err_param, int n, neu_json_elem_t *ele, ...) { diff --git a/src/parser/neu_json_global_config.c b/src/parser/neu_json_global_config.c index 29c35cfc6..4d417b167 100644 --- a/src/parser/neu_json_global_config.c +++ b/src/parser/neu_json_global_config.c @@ -30,6 +30,11 @@ #include "parser/neu_json_group_config.h" #include "parser/neu_json_tag.h" +/** + * 释放添加标签请求结构体内部分配的内存 + * + * @param req 需要释放内部资源的neu_json_add_tags_req_t结构体指针 + */ static void fini_add_tags_req(neu_json_add_tags_req_t *req) { neu_json_tag_array_t arr = { @@ -42,6 +47,13 @@ static void fini_add_tags_req(neu_json_add_tags_req_t *req) free(req->group); } +/** + * 从JSON对象解码到添加标签请求结构体 + * + * @param json_obj JSON对象指针 + * @param req 输出参数，已分配内存的neu_json_add_tags_req_t结构体指针 + * @return 成功返回0，失败返回-1 + */ static int decode_add_tags_req(void *json_obj, neu_json_add_tags_req_t *req) { int ret = 0; @@ -85,6 +97,14 @@ static int decode_add_tags_req(void *json_obj, neu_json_add_tags_req_t *req) return -1; } +/** + * 从JSON对象解码到全局配置请求标签结构体 + * + * @param json_obj JSON对象指针 + * @param result + * 输出参数，指向解码后的neu_json_global_config_req_tags_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_global_config_req_tags( void *json_obj, neu_json_global_config_req_tags_t **result) { @@ -130,6 +150,11 @@ int neu_json_decode_global_config_req_tags( return ret; } +/** + * 释放全局配置请求标签结构体及其内部分配的内存 + * + * @param req_tags 需要释放的neu_json_global_config_req_tags_t结构体指针 + */ void neu_json_decode_global_config_req_tags_free( neu_json_global_config_req_tags_t *req_tags) { @@ -145,6 +170,13 @@ void neu_json_decode_global_config_req_tags_free( free(req_tags); } +/** + * 解码JSON对象到订阅请求结构体 + * + * @param json_obj JSON对象指针 + * @param req 输出参数，已分配内存的neu_json_subscribe_req_t结构体指针 + * @return 成功返回0，失败返回-1 + */ static int decode_subscribe_req(json_t *json_obj, neu_json_subscribe_req_t *req) { neu_json_elem_t req_elems[] = { @@ -179,6 +211,11 @@ static int decode_subscribe_req(json_t *json_obj, neu_json_subscribe_req_t *req) return -1; } +/** + * 释放订阅请求结构体内部分配的内存 + * + * @param req 需要释放内部资源的neu_json_subscribe_req_t结构体指针 + */ static inline void fini_subscribe_req(neu_json_subscribe_req_t *req) { free(req->app); @@ -187,6 +224,14 @@ static inline void fini_subscribe_req(neu_json_subscribe_req_t *req) free(req->params); } +/** + * 从JSON对象解码到全局配置请求订阅结构体 + * + * @param json_obj JSON对象指针 + * @param result + * 输出参数，指向解码后的neu_json_global_config_req_subscriptions_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_global_config_req_subscriptions( void *json_obj, neu_json_global_config_req_subscriptions_t **result) { @@ -263,6 +308,11 @@ int neu_json_decode_global_config_req_subscriptions( return -1; } +/** + * 释放全局配置请求订阅结构体及其内部分配的内存 + * + * @param req_sub 需要释放的neu_json_global_config_req_subscriptions_t结构体指针 + */ void neu_json_decode_global_config_req_subscriptions_free( neu_json_global_config_req_subscriptions_t *req_sub) { @@ -278,12 +328,25 @@ void neu_json_decode_global_config_req_subscriptions_free( free(req_sub); } +/** + * 释放节点设置请求结构体内部分配的内存 + * + * @param req 需要释放内部资源的neu_json_node_setting_req_t结构体指针 + */ static inline void fini_node_setting(neu_json_node_setting_req_t *req) { free(req->node); free(req->setting); } +/** + * 从JSON对象解码到全局配置请求设置结构体 + * + * @param json_obj JSON对象指针 + * @param result + * 输出参数，指向解码后的neu_json_global_config_req_settings_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_global_config_req_settings( void *json_obj, neu_json_global_config_req_settings_t **result) { @@ -343,6 +406,11 @@ int neu_json_decode_global_config_req_settings( return -1; } +/** + * 释放全局配置请求设置结构体及其内部分配的内存 + * + * @param req_settings 需要释放的neu_json_global_config_req_settings_t结构体指针 + */ void neu_json_decode_global_config_req_settings_free( neu_json_global_config_req_settings_t *req_settings) { @@ -355,6 +423,13 @@ void neu_json_decode_global_config_req_settings_free( } } +/** + * 解码JSON到全局配置请求结构体 + * + * @param buf 包含JSON数据的字符串 + * @param result 输出参数，指向解码后的neu_json_global_config_req_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_global_config_req(char * buf, neu_json_global_config_req_t **result) { @@ -391,6 +466,11 @@ int neu_json_decode_global_config_req(char * buf, return ret; } +/** + * 释放全局配置请求结构体及其内部分配的内存 + * + * @param req 需要释放的neu_json_global_config_req_t结构体指针 + */ void neu_json_decode_global_config_req_free(neu_json_global_config_req_t *req) { if (req) { diff --git a/src/parser/neu_json_group_config.c b/src/parser/neu_json_group_config.c index 806024846..ad0206594 100644 --- a/src/parser/neu_json_group_config.c +++ b/src/parser/neu_json_group_config.c @@ -32,6 +32,13 @@ #include "neu_json_group_config.h" +/** + * 编码添加组配置请求到JSON + * + * @param json_object JSON对象指针 + * @param param 要编码的neu_json_add_group_config_req_t结构体指针 + * @return 成功返回0，失败返回非0 + */ int neu_json_encode_add_group_config_req(void *json_object, void *param) { int ret = 0; @@ -58,6 +65,13 @@ int neu_json_encode_add_group_config_req(void *json_object, void *param) return ret; } +/** + * 解码JSON到添加组配置请求结构体 + * + * @param buf 包含JSON数据的字符串 + * @param result 输出参数，指向解码后的neu_json_add_group_config_req_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_add_group_config_req( char *buf, neu_json_add_group_config_req_t **result) { @@ -107,6 +121,11 @@ int neu_json_decode_add_group_config_req( return ret; } +/** + * 释放添加组配置请求结构体及其内部分配的内存 + * + * @param req 需要释放的neu_json_add_group_config_req_t结构体指针 + */ void neu_json_decode_add_group_config_req_free( neu_json_add_group_config_req_t *req) { @@ -116,6 +135,13 @@ void neu_json_decode_add_group_config_req_free( free(req); } +/** + * 编码删除组配置请求到JSON + * + * @param json_object JSON对象指针 + * @param param 要编码的neu_json_del_group_config_req_t结构体指针 + * @return 成功返回0，失败返回非0 + */ int neu_json_encode_del_group_config_req(void *json_object, void *param) { int ret = 0; @@ -137,6 +163,13 @@ int neu_json_encode_del_group_config_req(void *json_object, void *param) return ret; } +/** + * 解码JSON到删除组配置请求结构体 + * + * @param buf 包含JSON数据的字符串 + * @param result 输出参数，指向解码后的neu_json_del_group_config_req_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_del_group_config_req( char *buf, neu_json_del_group_config_req_t **result) { @@ -181,6 +214,11 @@ int neu_json_decode_del_group_config_req( return ret; } +/** + * 释放删除组配置请求结构体及其内部分配的内存 + * + * @param req 需要释放的neu_json_del_group_config_req_t结构体指针 + */ void neu_json_decode_del_group_config_req_free( neu_json_del_group_config_req_t *req) { @@ -190,6 +228,13 @@ void neu_json_decode_del_group_config_req_free( free(req); } +/** + * 编码获取组配置响应到JSON + * + * @param json_object JSON对象指针 + * @param param 要编码的neu_json_get_group_config_resp_t结构体指针 + * @return 成功返回0，失败返回非0 + */ int neu_json_encode_get_group_config_resp(void *json_object, void *param) { int ret = 0; @@ -234,6 +279,13 @@ int neu_json_encode_get_group_config_resp(void *json_object, void *param) return ret; } +/** + * 编码获取驱动组响应到JSON + * + * @param json_object JSON对象指针 + * @param param 要编码的neu_json_get_driver_group_resp_t结构体指针 + * @return 成功返回0，失败返回非0 + */ int neu_json_encode_get_driver_group_resp(void *json_object, void *param) { int ret = 0; @@ -281,6 +333,14 @@ int neu_json_encode_get_driver_group_resp(void *json_object, void *param) return ret; } +/** + * 解码JSON到获取驱动组响应结构体 + * + * @param buf 包含JSON数据的字符串 + * @param result + * 输出参数，指向解码后的neu_json_get_driver_group_resp_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_get_driver_group_resp( char *buf, neu_json_get_driver_group_resp_t **result) { @@ -294,6 +354,14 @@ int neu_json_decode_get_driver_group_resp( return ret; } +/** + * 从JSON对象解码到获取驱动组响应结构体 + * + * @param json_obj JSON对象指针 + * @param result + * 输出参数，指向解码后的neu_json_get_driver_group_resp_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_get_driver_group_resp_json( void *json_obj, neu_json_get_driver_group_resp_t **result) { @@ -364,6 +432,11 @@ int neu_json_decode_get_driver_group_resp_json( return ret; } +/** + * 释放获取驱动组响应结构体及其内部分配的内存 + * + * @param resp 需要释放的neu_json_get_driver_group_resp_t结构体指针 + */ void neu_json_decode_get_driver_group_resp_free( neu_json_get_driver_group_resp_t *resp) { @@ -377,6 +450,13 @@ void neu_json_decode_get_driver_group_resp_free( } } +/** + * 编码获取订阅响应到JSON + * + * @param object JSON对象指针 + * @param param 要编码的neu_json_get_subscribe_resp_t结构体指针 + * @return 成功返回0，失败返回非0 + */ int neu_json_encode_get_subscribe_resp(void *object, void *param) { int ret = 0; @@ -415,11 +495,25 @@ int neu_json_encode_get_subscribe_resp(void *object, void *param) return ret; } +/** + * 从JSON对象中提取params字段 + * + * @param root JSON对象指针 + * @param result 输出参数，指向提取的params字符串 + * @return 成功返回0，失败返回非0 + */ static inline int dump_params(void *root, char **const result) { return neu_json_dump_key(root, "params", result, false); } +/** + * 解码JSON到订阅请求结构体 + * + * @param buf 包含JSON数据的字符串 + * @param result 输出参数，指向解码后的neu_json_subscribe_req_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_subscribe_req(char *buf, neu_json_subscribe_req_t **result) { int ret = 0; @@ -472,6 +566,11 @@ int neu_json_decode_subscribe_req(char *buf, neu_json_subscribe_req_t **result) return ret; } +/** + * 释放订阅请求结构体及其内部分配的内存 + * + * @param req 需要释放的neu_json_subscribe_req_t结构体指针 + */ void neu_json_decode_subscribe_req_free(neu_json_subscribe_req_t *req) { free(req->app); @@ -482,6 +581,13 @@ void neu_json_decode_subscribe_req_free(neu_json_subscribe_req_t *req) free(req); } +/** + * 解码JSON到取消订阅请求结构体 + * + * @param buf 包含JSON数据的字符串 + * @param result 输出参数，指向解码后的neu_json_unsubscribe_req_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_unsubscribe_req(char * buf, neu_json_unsubscribe_req_t **result) { @@ -531,6 +637,11 @@ int neu_json_decode_unsubscribe_req(char * buf, return ret; } +/** + * 释放取消订阅请求结构体及其内部分配的内存 + * + * @param req 需要释放的neu_json_unsubscribe_req_t结构体指针 + */ void neu_json_decode_unsubscribe_req_free(neu_json_unsubscribe_req_t *req) { @@ -541,6 +652,13 @@ void neu_json_decode_unsubscribe_req_free(neu_json_unsubscribe_req_t *req) free(req); } +/** + * 编码更新组配置请求到JSON + * + * @param json_object JSON对象指针 + * @param param 要编码的neu_json_update_group_config_req_t结构体指针 + * @return 成功返回0，失败返回非0 + */ int neu_json_encode_update_group_config_req(void *json_object, void *param) { int ret = 0; @@ -579,6 +697,14 @@ int neu_json_encode_update_group_config_req(void *json_object, void *param) return ret; } +/** + * 解码JSON到更新组配置请求结构体 + * + * @param buf 包含JSON数据的字符串 + * @param result + * 输出参数，指向解码后的neu_json_update_group_config_req_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_update_group_config_req( char *buf, neu_json_update_group_config_req_t **result) { @@ -642,6 +768,11 @@ int neu_json_decode_update_group_config_req( return -1; } +/** + * 释放更新组配置请求结构体及其内部分配的内存 + * + * @param req 需要释放的neu_json_update_group_config_req_t结构体指针 + */ void neu_json_decode_update_group_config_req_free( neu_json_update_group_config_req_t *req) { @@ -652,6 +783,13 @@ void neu_json_decode_update_group_config_req_free( free(req); } +/** + * 从JSON对象解码到订阅组信息结构体 + * + * @param json_obj JSON对象指针 + * @param info 输出参数，指向解码后的neu_json_subscribe_groups_info_t结构体 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_subscribe_groups_info_json( void *json_obj, neu_json_subscribe_groups_info_t *info) { @@ -686,6 +824,11 @@ int neu_json_decode_subscribe_groups_info_json( return 0; } +/** + * 释放订阅组信息结构体内部分配的内存 + * + * @param req 需要释放内部资源的neu_json_subscribe_groups_info_t结构体指针 + */ void neu_json_decode_subscribe_groups_info_fini( neu_json_subscribe_groups_info_t *req) { @@ -694,6 +837,13 @@ void neu_json_decode_subscribe_groups_info_fini( free(req->params); } +/** + * 解码JSON到订阅组请求结构体 + * + * @param buf 包含JSON数据的字符串 + * @param result 输出参数，指向解码后的neu_json_subscribe_groups_req_t结构体指针 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_subscribe_groups_req( char *buf, neu_json_subscribe_groups_req_t **result) { @@ -765,6 +915,11 @@ int neu_json_decode_subscribe_groups_req( return -1; } +/** + * 释放订阅组请求结构体及其内部分配的内存 + * + * @param req 需要释放的neu_json_subscribe_groups_req_t结构体指针 + */ void neu_json_decode_subscribe_groups_req_free( neu_json_subscribe_groups_req_t *req) { diff --git a/src/parser/neu_json_log.c b/src/parser/neu_json_log.c index 5ac653a20..f0b2391ae 100644 --- a/src/parser/neu_json_log.c +++ b/src/parser/neu_json_log.c @@ -30,6 +30,13 @@ #include "neu_json_log.h" #include "utils/log.h" +/** + * @brief 从JSON字符串解码更新日志级别请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 解码结果存储位置，由函数分配内存 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_update_log_level_req( char *buf, neu_json_update_log_level_req_t **result) { @@ -88,6 +95,11 @@ int neu_json_decode_update_log_level_req( return ret; } +/** + * @brief 释放更新日志级别请求资源 + * + * @param req 要释放的请求结构体指针 + */ void neu_json_decode_update_log_level_req_free( neu_json_update_log_level_req_t *req) { @@ -102,6 +114,13 @@ void neu_json_decode_update_log_level_req_free( } } +/** + * @brief 编码获取日志响应为JSON + * + * @param json_object 输出的JSON对象 + * @param param 要编码的响应结构体指针(neu_json_get_log_resp_t类型) + * @return int 成功返回0，失败返回非0 + */ int neu_json_encode_get_log_resp(void *json_object, void *param) { int ret = 0; diff --git a/src/parser/neu_json_login.c b/src/parser/neu_json_login.c index e12cd8534..55b1cf643 100644 --- a/src/parser/neu_json_login.c +++ b/src/parser/neu_json_login.c @@ -29,6 +29,13 @@ #include "neu_json_login.h" +/** + * @brief 从JSON字符串解码登录请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 解码结果存储位置，由函数分配内存 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_login_req(char *buf, neu_json_login_req_t **result) { int ret = 0; @@ -58,6 +65,11 @@ int neu_json_decode_login_req(char *buf, neu_json_login_req_t **result) return -1; } +/** + * @brief 释放登录请求资源 + * + * @param req 要释放的请求结构体指针 + */ void neu_json_decode_login_req_free(neu_json_login_req_t *req) { @@ -67,6 +79,13 @@ void neu_json_decode_login_req_free(neu_json_login_req_t *req) free(req); } +/** + * @brief 从JSON字符串解码密码修改请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 解码结果存储位置，由函数分配内存 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_password_req(char *buf, neu_json_password_req_t **result) { int ret = 0; @@ -103,6 +122,11 @@ int neu_json_decode_password_req(char *buf, neu_json_password_req_t **result) return -1; } +/** + * @brief 释放密码修改请求资源 + * + * @param req 要释放的请求结构体指针 + */ void neu_json_decode_password_req_free(neu_json_password_req_t *req) { if (req) { @@ -114,6 +138,13 @@ void neu_json_decode_password_req_free(neu_json_password_req_t *req) } } +/** + * @brief 编码登录响应为JSON + * + * @param json_object 输出的JSON对象 + * @param param 要编码的响应结构体指针(neu_json_login_resp_t类型) + * @return int 成功返回0，失败返回非0 + */ int neu_json_encode_login_resp(void *json_object, void *param) { int ret = 0; diff --git a/src/parser/neu_json_mqtt.c b/src/parser/neu_json_mqtt.c index 8702c9e82..486e39298 100644 --- a/src/parser/neu_json_mqtt.c +++ b/src/parser/neu_json_mqtt.c @@ -30,6 +30,13 @@ #include "json/neu_json_mqtt.h" +/** + * @brief 从JSON字符串解码MQTT请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 解码结果存储位置，由函数分配内存 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_mqtt_req(char *buf, neu_json_mqtt_t **result) { int ret = 0; @@ -57,6 +64,11 @@ int neu_json_decode_mqtt_req(char *buf, neu_json_mqtt_t **result) return -1; } +/** + * @brief 释放MQTT请求资源 + * + * @param req 要释放的请求结构体指针 + */ void neu_json_decode_mqtt_req_free(neu_json_mqtt_t *req) { if (NULL == req) { @@ -70,6 +82,13 @@ void neu_json_decode_mqtt_req_free(neu_json_mqtt_t *req) free(req); } +/** + * @brief 编码MQTT响应为JSON + * + * @param json_object 输出的JSON对象 + * @param param 要编码的响应结构体指针(neu_json_mqtt_t类型) + * @return int 成功返回0，失败返回非0 + */ int neu_json_encode_mqtt_resp(void *json_object, void *param) { int ret = 0; @@ -87,6 +106,13 @@ int neu_json_encode_mqtt_resp(void *json_object, void *param) return ret; } +/** + * @brief 编码状态头部响应为JSON + * + * @param json_object 输出的JSON对象 + * @param param 要编码的状态头部结构体指针(neu_json_states_head_t类型) + * @return int 成功返回0，失败返回非0 + */ int neu_json_encode_state_header_resp(void *json_object, void *param) { int ret = 0; @@ -108,6 +134,13 @@ int neu_json_encode_state_header_resp(void *json_object, void *param) return ret; } +/** + * @brief 编码状态响应为JSON + * + * @param json_object 输出的JSON对象 + * @param param 要编码的状态结构体指针(neu_json_states_t类型) + * @return int 成功返回0，失败返回非0 + */ int neu_json_encode_states_resp(void *json_object, void *param) { int ret = 0; diff --git a/src/parser/neu_json_ndriver.c b/src/parser/neu_json_ndriver.c index bb16252a0..ff8c84fa6 100644 --- a/src/parser/neu_json_ndriver.c +++ b/src/parser/neu_json_ndriver.c @@ -26,6 +26,13 @@ #include "neu_json_ndriver.h" +/** + * @brief 将ndriver映射对象编码为JSON + * + * @param json_object 输出的JSON对象 + * @param param 要编码的ndriver映射结构体指针(neu_json_ndriver_map_t类型) + * @return int 成功返回0，失败返回非0 + */ int neu_json_encode_ndriver_map(void *json_object, void *param) { int ret = 0; @@ -55,8 +62,20 @@ int neu_json_encode_ndriver_map(void *json_object, void *param) return ret; } +/** + * @brief 释放ndriver映射对象资源的前向声明 + * + * @param req 要释放的ndriver映射结构体指针 + */ void neu_json_decode_ndriver_map_free(neu_json_ndriver_map_t *req); +/** + * @brief 从JSON字符串解码ndriver映射对象 + * + * @param buf 包含JSON数据的字符串 + * @param result 解码结果存储位置，由函数分配内存 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_ndriver_map(char *buf, neu_json_ndriver_map_t **result) { int ret = 0; @@ -107,6 +126,11 @@ int neu_json_decode_ndriver_map(char *buf, neu_json_ndriver_map_t **result) return -1; } +/** + * @brief 释放ndriver映射对象资源 + * + * @param req 要释放的ndriver映射结构体指针 + */ void neu_json_decode_ndriver_map_free(neu_json_ndriver_map_t *req) { if (req) { @@ -117,6 +141,13 @@ void neu_json_decode_ndriver_map_free(neu_json_ndriver_map_t *req) } } +/** + * @brief 将ndriver组数组编码为JSON数组 + * + * @param json_arr 输出的JSON数组对象 + * @param param 要编码的组数组结构体指针(neu_json_ndriver_map_group_array_t类型) + * @return int 成功返回0，失败返回-1 + */ int neu_json_encode_ndriver_group_array(void *json_arr, void *param) { neu_json_ndriver_map_group_array_t *resp = @@ -140,6 +171,13 @@ int neu_json_encode_ndriver_group_array(void *json_arr, void *param) return 0; } +/** + * @brief 编码获取ndriver映射响应 + * + * @param json_obj 输出的JSON对象 + * @param param 要编码的组数组结构体指针(neu_json_ndriver_map_group_array_t类型) + * @return int 成功返回0，失败返回-1 + */ int neu_json_encode_get_ndriver_maps_resp(void *json_obj, void *param) { int ret = 0; @@ -165,6 +203,13 @@ int neu_json_encode_get_ndriver_maps_resp(void *json_obj, void *param) return ret; } +/** + * @brief 将单个ndriver标签编码为JSON对象 + * + * @param json_obj 输出的JSON对象 + * @param param 要编码的标签结构体指针(neu_json_ndriver_tag_t类型) + * @return int 成功返回0，失败返回-1 + */ int neu_json_encode_ndriver_tag(void *json_obj, void *param) { int ret = 0; @@ -205,6 +250,13 @@ int neu_json_encode_ndriver_tag(void *json_obj, void *param) return ret; } +/** + * @brief 将ndriver标签数组编码为JSON数组 + * + * @param json_obj 输出的JSON数组对象 + * @param param 要编码的标签数组结构体指针(neu_json_ndriver_tag_array_t类型) + * @return int 成功返回0，失败返回-1 + */ int neu_json_encode_ndriver_tag_array(void *json_obj, void *param) { neu_json_ndriver_tag_array_t *array = param; @@ -226,6 +278,13 @@ int neu_json_encode_ndriver_tag_array(void *json_obj, void *param) return 0; } +/** + * @brief 编码获取ndriver标签响应 + * + * @param json_obj 输出的JSON对象 + * @param param 要编码的标签数组结构体指针(neu_json_ndriver_tag_array_t类型) + * @return int 成功返回0，失败返回-1 + */ int neu_json_encode_get_ndriver_tags_resp(void *json_obj, void *param) { int ret = 0; @@ -251,12 +310,24 @@ int neu_json_encode_get_ndriver_tags_resp(void *json_obj, void *param) return ret; } +/** + * @brief 释放ndriver标签参数资源 + * + * @param tag_param 要释放的标签参数结构体指针 + */ void neu_json_ndriver_tag_param_fini(neu_json_ndriver_tag_param_t *tag_param) { free(tag_param->name); free(tag_param->params); } +/** + * @brief 从JSON对象解码ndriver标签参数 + * + * @param json_obj 包含JSON数据的对象 + * @param tag_param_p 解码结果存储位置 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_ndriver_tag_param_json( void *json_obj, neu_json_ndriver_tag_param_t *tag_param_p) { @@ -291,6 +362,11 @@ int neu_json_decode_ndriver_tag_param_json( return 0; } +/** + * @brief 释放ndriver标签参数数组资源 + * + * @param arr 要释放的标签参数数组结构体指针 + */ void neu_json_ndriver_tag_param_array_fini( neu_json_ndriver_tag_param_array_t *arr) { @@ -299,6 +375,13 @@ void neu_json_ndriver_tag_param_array_fini( } } +/** + * @brief 从JSON对象解码ndriver标签参数数组 + * + * @param json_obj 包含JSON数据的数组对象 + * @param arr 解码结果存储位置 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_ndriver_tag_param_array_json( void *json_obj, neu_json_ndriver_tag_param_array_t *arr) { @@ -342,6 +425,13 @@ int neu_json_decode_ndriver_tag_param_array_json( return -1; } +/** + * @brief 从JSON字符串解码更新ndriver标签参数请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 解码结果存储位置，由函数分配内存 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_update_ndriver_tag_param_req( char *buf, neu_json_update_ndriver_tag_param_req_t **result) { @@ -405,6 +495,11 @@ int neu_json_decode_update_ndriver_tag_param_req( return -1; } +/** + * @brief 释放更新ndriver标签参数请求资源 + * + * @param req 要释放的请求结构体指针 + */ void neu_json_decode_update_ndriver_tag_param_req_free( neu_json_update_ndriver_tag_param_req_t *req) { @@ -418,12 +513,24 @@ void neu_json_decode_update_ndriver_tag_param_req_free( } } +/** + * @brief 释放ndriver标签信息资源 + * + * @param tag_info 要释放的标签信息结构体指针 + */ void neu_json_ndriver_tag_info_fini(neu_json_ndriver_tag_info_t *tag_info) { free(tag_info->name); free(tag_info->address); } +/** + * @brief 从JSON对象解码ndriver标签信息 + * + * @param json_obj 包含JSON数据的对象 + * @param tag_info_p 解码结果存储位置 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_ndriver_tag_info_json( void *json_obj, neu_json_ndriver_tag_info_t *tag_info_p) { @@ -463,6 +570,11 @@ int neu_json_decode_ndriver_tag_info_json( return -1; } +/** + * @brief 释放ndriver标签信息数组资源 + * + * @param arr 要释放的标签信息数组结构体指针 + */ void neu_json_ndriver_tag_info_array_fini( neu_json_ndriver_tag_info_array_t *arr) { @@ -471,6 +583,13 @@ void neu_json_ndriver_tag_info_array_fini( } } +/** + * @brief 从JSON对象解码ndriver标签信息数组 + * + * @param json_obj 包含JSON数据的数组对象 + * @param arr 解码结果存储位置 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_ndriver_tag_info_array_json( void *json_obj, neu_json_ndriver_tag_info_array_t *arr) { @@ -514,6 +633,13 @@ int neu_json_decode_ndriver_tag_info_array_json( return -1; } +/** + * @brief 从JSON字符串解码更新ndriver标签信息请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 解码结果存储位置，由函数分配内存 + * @return int 成功返回0，失败返回-1 + */ int neu_json_decode_update_ndriver_tag_info_req( char *buf, neu_json_update_ndriver_tag_info_req_t **result) { @@ -577,6 +703,11 @@ int neu_json_decode_update_ndriver_tag_info_req( return -1; } +/** + * @brief 释放更新ndriver标签信息请求资源 + * + * @param req 要释放的请求结构体指针 + */ void neu_json_decode_update_ndriver_tag_info_req_free( neu_json_update_ndriver_tag_info_req_t *req) { diff --git a/src/parser/neu_json_node.c b/src/parser/neu_json_node.c index 52ebfa4fe..7ba5707ed 100644 --- a/src/parser/neu_json_node.c +++ b/src/parser/neu_json_node.c @@ -31,6 +31,13 @@ #include "neu_json_node.h" +/** + * 将添加节点请求编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向添加节点请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_add_node_req(void *json_object, void *param) { int ret = 0; @@ -53,6 +60,13 @@ int neu_json_encode_add_node_req(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码添加节点请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的添加节点请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_add_node_req(char *buf, neu_json_add_node_req_t **result) { int ret = 0; @@ -95,6 +109,11 @@ int neu_json_decode_add_node_req(char *buf, neu_json_add_node_req_t **result) return ret; } +/** + * 释放添加节点请求结构的内存 + * + * @param req 指向要释放的添加节点请求结构的指针 + */ void neu_json_decode_add_node_req_free(neu_json_add_node_req_t *req) { @@ -104,6 +123,13 @@ void neu_json_decode_add_node_req_free(neu_json_add_node_req_t *req) free(req); } +/** + * 将删除节点请求编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向删除节点请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_del_node_req(void *json_object, void *param) { int ret = 0; @@ -121,6 +147,13 @@ int neu_json_encode_del_node_req(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码删除节点请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的删除节点请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_del_node_req(char *buf, neu_json_del_node_req_t **result) { int ret = 0; @@ -158,12 +191,24 @@ int neu_json_decode_del_node_req(char *buf, neu_json_del_node_req_t **result) return ret; } +/** + * 释放删除节点请求结构的内存 + * + * @param req 指向要释放的删除节点请求结构的指针 + */ void neu_json_decode_del_node_req_free(neu_json_del_node_req_t *req) { free(req->name); free(req); } +/** + * 将获取节点状态响应编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向获取节点状态响应的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_get_node_state_resp(void *json_object, void *param) { int ret = 0; @@ -201,6 +246,13 @@ int neu_json_encode_get_node_state_resp(void *json_object, void *param) return ret; } +/** + * 将获取多个节点状态响应编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向获取多个节点状态响应的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_get_nodes_state_resp(void *json_object, void *param) { int ret = 0; @@ -256,6 +308,13 @@ int neu_json_encode_get_nodes_state_resp(void *json_object, void *param) return ret; } +/** + * 将获取节点列表响应编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向获取节点列表响应的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_get_nodes_resp(void *json_object, void *param) { int ret = 0; @@ -299,6 +358,13 @@ int neu_json_encode_get_nodes_resp(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码获取节点列表响应 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的获取节点列表响应结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_get_nodes_resp(char * buf, neu_json_get_nodes_resp_t **result) { @@ -312,6 +378,13 @@ int neu_json_decode_get_nodes_resp(char * buf, return ret; } +/** + * 从JSON对象解码获取节点列表响应 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param result 二级指针，用于返回解码后的获取节点列表响应结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_get_nodes_resp_json(void * json_obj, neu_json_get_nodes_resp_t **result) { @@ -375,6 +448,11 @@ int neu_json_decode_get_nodes_resp_json(void * json_obj, return ret; } +/** + * 释放获取节点列表响应结构的内存 + * + * @param resp 指向要释放的获取节点列表响应结构的指针 + */ void neu_json_decode_get_nodes_resp_free(neu_json_get_nodes_resp_t *resp) { if (resp) { @@ -387,6 +465,13 @@ void neu_json_decode_get_nodes_resp_free(neu_json_get_nodes_resp_t *resp) } } +/** + * 将更新节点请求编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向更新节点请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_update_node_req(void *json_object, void *param) { int ret = 0; @@ -409,6 +494,13 @@ int neu_json_encode_update_node_req(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码更新节点请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的更新节点请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_update_node_req(char * buf, neu_json_update_node_req_t **result) { @@ -452,6 +544,11 @@ int neu_json_decode_update_node_req(char * buf, return -1; } +/** + * 释放更新节点请求结构的内存 + * + * @param req 指向要释放的更新节点请求结构的指针 + */ void neu_json_decode_update_node_req_free(neu_json_update_node_req_t *req) { if (req) { @@ -461,6 +558,13 @@ void neu_json_decode_update_node_req_free(neu_json_update_node_req_t *req) } } +/** + * 将节点控制请求编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向节点控制请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_node_ctl_req(void *json_object, void *param) { int ret = 0; @@ -483,6 +587,13 @@ int neu_json_encode_node_ctl_req(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码节点控制请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的节点控制请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_node_ctl_req(char *buf, neu_json_node_ctl_req_t **result) { int ret = 0; @@ -525,12 +636,24 @@ int neu_json_decode_node_ctl_req(char *buf, neu_json_node_ctl_req_t **result) return ret; } +/** + * 释放节点控制请求结构的内存 + * + * @param req 指向要释放的节点控制请求结构的指针 + */ void neu_json_decode_node_ctl_req_free(neu_json_node_ctl_req_t *req) { free(req->node); free(req); } +/** + * 将节点设置请求编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向节点设置请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_node_setting_req(void *json_object, void *param) { int ret = 0; @@ -552,6 +675,13 @@ int neu_json_encode_node_setting_req(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码节点设置请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的节点设置请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_node_setting_req(char * buf, neu_json_node_setting_req_t **result) { @@ -598,6 +728,11 @@ int neu_json_decode_node_setting_req(char * buf, return ret; } +/** + * 释放节点设置请求结构的内存 + * + * @param req 指向要释放的节点设置请求结构的指针 + */ void neu_json_decode_node_setting_req_free(neu_json_node_setting_req_t *req) { free(req->node); @@ -605,6 +740,13 @@ void neu_json_decode_node_setting_req_free(neu_json_node_setting_req_t *req) free(req); } +/** + * 将获取节点设置响应编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向获取节点设置响应的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_get_node_setting_resp(void *json_object, void *param) { int ret = 0; diff --git a/src/parser/neu_json_plugin.c b/src/parser/neu_json_plugin.c index 570606480..4aaaa44b2 100644 --- a/src/parser/neu_json_plugin.c +++ b/src/parser/neu_json_plugin.c @@ -29,6 +29,13 @@ #include "neu_json_plugin.h" +/** + * 从JSON字符串解码添加插件请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的添加插件请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_add_plugin_req(char * buf, neu_json_add_plugin_req_t **result) { @@ -68,14 +75,24 @@ int neu_json_decode_add_plugin_req(char * buf, return ret; } +/** + * 释放添加插件请求结构的内存 + * + * @param req 指向要释放的添加插件请求结构的指针 + */ void neu_json_decode_add_plugin_req_free(neu_json_add_plugin_req_t *req) { - free(req->library); - free(req); } +/** + * 从JSON字符串解码删除插件请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的删除插件请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_del_plugin_req(char * buf, neu_json_del_plugin_req_t **result) { @@ -115,12 +132,24 @@ int neu_json_decode_del_plugin_req(char * buf, return ret; } +/** + * 释放删除插件请求结构的内存 + * + * @param req 指向要释放的删除插件请求结构的指针 + */ void neu_json_decode_del_plugin_req_free(neu_json_del_plugin_req_t *req) { free(req->plugin); free(req); } +/** + * 将获取插件响应编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向获取插件响应的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_get_plugin_resp(void *json_object, void *param) { int ret = 0; diff --git a/src/parser/neu_json_rw.c b/src/parser/neu_json_rw.c index 95ea87522..153bbed02 100644 --- a/src/parser/neu_json_rw.c +++ b/src/parser/neu_json_rw.c @@ -34,6 +34,13 @@ #include "json/neu_json_rw.h" +/** + * 将读取标签响应编码成JSON对象（使用标签数组格式） + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向读取响应的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_read_resp(void *json_object, void *param) { int ret = 0; @@ -81,6 +88,13 @@ int neu_json_encode_read_resp(void *json_object, void *param) return ret; } +/** + * 将读取标签响应编码成JSON对象（使用分组格式） + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向读取响应的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_read_resp1(void *json_object, void *param) { int ret = 0; @@ -152,6 +166,13 @@ int neu_json_encode_read_resp1(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码写入标签请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的写入标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_write_req(char *buf, neu_json_write_req_t **result) { void *json_obj = neu_json_decode_new(buf); @@ -164,6 +185,13 @@ int neu_json_decode_write_req(char *buf, neu_json_write_req_t **result) return ret; } +/** + * 从JSON对象解码写入标签请求 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param req 指向写入标签请求结构的指针，用于存储解码结果 + * @return 成功返回0，失败返回-1 + */ int decode_write_req_json(void *json_obj, neu_json_write_req_t *req) { int ret = 0; @@ -207,6 +235,13 @@ int decode_write_req_json(void *json_obj, neu_json_write_req_t *req) return ret; } +/** + * 从JSON对象解码写入标签请求并分配内存 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param result 二级指针，用于返回解码后的写入标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_write_req_json(void * json_obj, neu_json_write_req_t **result) { @@ -225,6 +260,11 @@ int neu_json_decode_write_req_json(void * json_obj, return ret; } +/** + * 释放写入标签请求结构的内存 + * + * @param req 指向要释放的写入标签请求结构的指针 + */ void neu_json_decode_write_req_free(neu_json_write_req_t *req) { free(req->group); @@ -240,6 +280,13 @@ void neu_json_decode_write_req_free(neu_json_write_req_t *req) free(req); } +/** + * 从JSON字符串解码写入多个标签请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的写入多个标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_write_tags_req(char * buf, neu_json_write_tags_req_t **result) { @@ -253,6 +300,13 @@ int neu_json_decode_write_tags_req(char * buf, return ret; } +/** + * 从JSON对象解码写入多个标签请求 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param req 指向写入多个标签请求结构的指针，用于存储解码结果 + * @return 成功返回0，失败返回-1 + */ static int decode_write_tags_req_json(void * json_obj, neu_json_write_tags_req_t *req) { @@ -323,6 +377,13 @@ static int decode_write_tags_req_json(void * json_obj, return 0; } +/** + * 从JSON对象解码写入多个标签请求并分配内存 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param result 二级指针，用于返回解码后的写入多个标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_write_tags_req_json(void * json_obj, neu_json_write_tags_req_t **result) { @@ -342,6 +403,11 @@ int neu_json_decode_write_tags_req_json(void * json_obj, return ret; } +/** + * 释放写入多个标签请求结构的内存 + * + * @param req 指向要释放的写入多个标签请求结构的指针 + */ void neu_json_decode_write_tags_req_free(neu_json_write_tags_req_t *req) { free(req->group); @@ -361,6 +427,13 @@ void neu_json_decode_write_tags_req_free(neu_json_write_tags_req_t *req) free(req); } +/** + * 从JSON字符串解码写入请求（支持单个标签或多个标签） + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的写入请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_write(char *buf, neu_json_write_t **result) { neu_json_write_t *req = calloc(1, sizeof(*req)); @@ -393,6 +466,11 @@ int neu_json_decode_write(char *buf, neu_json_write_t **result) return ret; } +/** + * 释放写入请求结构的内存（支持单个标签或多个标签） + * + * @param req 指向要释放的写入请求结构的指针 + */ void neu_json_decode_write_free(neu_json_write_t *req) { if (req) { @@ -405,6 +483,13 @@ void neu_json_decode_write_free(neu_json_write_t *req) } } +/** + * 从JSON字符串解码读取标签请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的读取标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_read_req(char *buf, neu_json_read_req_t **result) { int ret = 0; @@ -455,6 +540,11 @@ int neu_json_decode_read_req(char *buf, neu_json_read_req_t **result) return ret; } +/** + * 释放读取标签请求结构的内存 + * + * @param req 指向要释放的读取标签请求结构的指针 + */ void neu_json_decode_read_req_free(neu_json_read_req_t *req) { free(req->group); @@ -463,6 +553,13 @@ void neu_json_decode_read_req_free(neu_json_read_req_t *req) free(req); } +/** + * 将周期性读取响应编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向周期性读取响应的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_read_periodic_resp(void *json_object, void *param) { int ret = 0; @@ -489,6 +586,13 @@ int neu_json_encode_read_periodic_resp(void *json_object, void *param) return ret; } +/** + * 将标签元数据转换为JSON格式 + * + * @param metas 标签元数据数组 + * @param n_meta 元数据数量 + * @param json_tag 用于存储JSON格式元数据的标签结构 + */ void neu_json_metas_to_json(neu_tag_meta_t *metas, int n_meta, neu_json_read_resp_tag_t *json_tag) { @@ -561,6 +665,13 @@ void neu_json_metas_to_json(neu_tag_meta_t *metas, int n_meta, } } +/** + * 从JSON字符串解码写入多组标签请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的写入多组标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_write_gtags_req(char * buf, neu_json_write_gtags_req_t **result) { @@ -576,6 +687,13 @@ int neu_json_decode_write_gtags_req(char * buf, #include "utils/log.h" +/** + * 从JSON对象解码写入多组标签请求 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param req 指向写入多组标签请求结构的指针，用于存储解码结果 + * @return 成功返回0，失败返回-1 + */ static int decode_write_gtags_req_json(void * json_obj, neu_json_write_gtags_req_t *req) { @@ -660,6 +778,13 @@ static int decode_write_gtags_req_json(void * json_obj, return 0; } +/** + * 从JSON对象解码写入多组标签请求并分配内存 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param result 二级指针，用于返回解码后的写入多组标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_write_gtags_req_json(void * json_obj, neu_json_write_gtags_req_t **result) { @@ -679,6 +804,11 @@ int neu_json_decode_write_gtags_req_json(void * json_obj, return ret; } +/** + * 释放写入多组标签请求结构的内存 + * + * @param req 指向要释放的写入多组标签请求结构的指针 + */ void neu_json_decode_write_gtags_req_free(neu_json_write_gtags_req_t *req) { free(req->node); diff --git a/src/parser/neu_json_tag.c b/src/parser/neu_json_tag.c index a3f9beab1..e7dc0891d 100644 --- a/src/parser/neu_json_tag.c +++ b/src/parser/neu_json_tag.c @@ -33,6 +33,13 @@ #include "tag.h" #include "type.h" +/** + * 将单个标签编码成JSON对象 + * + * @param json_obj JSON对象指针，用于存储编码结果 + * @param param 指向标签的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_tag(void *json_obj, void *param) { int ret = 0; @@ -87,6 +94,13 @@ int neu_json_encode_tag(void *json_obj, void *param) return ret; } +/** + * 从JSON对象解码单个标签数据 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param tag_p 指向标签结构的指针，用于存储解码结果 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_tag_json(void *json_obj, neu_json_tag_t *tag_p) { if (NULL == tag_p) { @@ -164,6 +178,11 @@ int neu_json_decode_tag_json(void *json_obj, neu_json_tag_t *tag_p) return -1; } +/** + * 释放标签结构中分配的内存资源 + * + * @param tag 指向要释放资源的标签结构的指针 + */ void neu_json_decode_tag_fini(neu_json_tag_t *tag) { free(tag->name); @@ -174,6 +193,12 @@ void neu_json_decode_tag_fini(neu_json_tag_t *tag) } } +/** + * 检查标签类型与值类型是否匹配 + * + * @param tag 指向要检查的标签结构的指针 + * @return 类型匹配返回true，不匹配返回false + */ int neu_json_tag_check_type(neu_json_tag_t *tag) { if (NEU_ATTRIBUTE_STATIC & tag->attribute) { @@ -210,6 +235,13 @@ int neu_json_tag_check_type(neu_json_tag_t *tag) return true; } +/** + * 将标签数组编码成JSON对象 + * + * @param json_obj JSON对象指针，用于存储编码结果 + * @param param 指向标签数组的指针，作为要编码的数据 + * @return 成功返回0，失败返回-1 + */ int neu_json_encode_tag_array(void *json_obj, void *param) { neu_json_tag_array_t *array = param; @@ -231,6 +263,13 @@ int neu_json_encode_tag_array(void *json_obj, void *param) return 0; } +/** + * 从JSON对象解码标签数组数据 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param arr 指向标签数组结构的指针，用于存储解码结果 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_tag_array_json(void *json_obj, neu_json_tag_array_t *arr) { int len = 0; @@ -273,6 +312,11 @@ int neu_json_decode_tag_array_json(void *json_obj, neu_json_tag_array_t *arr) return -1; } +/** + * 释放标签数组结构中分配的内存资源 + * + * @param arr 指向要释放资源的标签数组结构的指针 + */ void neu_json_decode_tag_array_fini(neu_json_tag_array_t *arr) { for (int i = 0; i < arr->len; ++i) { @@ -281,6 +325,13 @@ void neu_json_decode_tag_array_fini(neu_json_tag_array_t *arr) free(arr->tags); } +/** + * 将添加标签请求编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向添加标签请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_add_tags_req(void *json_object, void *param) { int ret = 0; @@ -323,6 +374,13 @@ int neu_json_encode_add_tags_req(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码添加标签请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的添加标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_add_tags_req(char *buf, neu_json_add_tags_req_t **result) { int ret = 0; @@ -386,6 +444,11 @@ int neu_json_decode_add_tags_req(char *buf, neu_json_add_tags_req_t **result) return ret; } +/** + * 释放添加标签请求结构的内存 + * + * @param req 指向要释放的添加标签请求结构的指针 + */ void neu_json_decode_add_tags_req_free(neu_json_add_tags_req_t *req) { if (NULL == req) { @@ -403,6 +466,13 @@ void neu_json_decode_add_tags_req_free(neu_json_add_tags_req_t *req) free(req); } +/** + * 将标签操作响应编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向标签操作响应的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_au_tags_resp(void *json_object, void *param) { int ret = 0; @@ -427,6 +497,13 @@ int neu_json_encode_au_tags_resp(void *json_object, void *param) return ret; } +/** + * 将删除标签请求编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向删除标签请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_del_tags_req(void *json_object, void *param) { int ret = 0; @@ -469,6 +546,13 @@ int neu_json_encode_del_tags_req(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码删除标签请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的删除标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_del_tags_req(char *buf, neu_json_del_tags_req_t **result) { int ret = 0; @@ -538,6 +622,11 @@ int neu_json_decode_del_tags_req(char *buf, neu_json_del_tags_req_t **result) return ret; } +/** + * 释放删除标签请求结构的内存 + * + * @param req 指向要释放的删除标签请求结构的指针 + */ void neu_json_decode_del_tags_req_free(neu_json_del_tags_req_t *req) { free(req->node); @@ -551,6 +640,13 @@ void neu_json_decode_del_tags_req_free(neu_json_del_tags_req_t *req) free(req); } +/** + * 将获取标签响应编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向获取标签响应的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_get_tags_resp(void *json_object, void *param) { int ret = 0; @@ -582,6 +678,13 @@ int neu_json_encode_get_tags_resp(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码更新标签请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的更新标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_update_tags_req(char * buf, neu_json_update_tags_req_t **result) { @@ -647,6 +750,11 @@ int neu_json_decode_update_tags_req(char * buf, return ret; } +/** + * 释放更新标签请求结构的内存 + * + * @param req 指向要释放的更新标签请求结构的指针 + */ void neu_json_decode_update_tags_req_free(neu_json_update_tags_req_t *req) { if (NULL == req) { diff --git a/src/parser/neu_json_template.c b/src/parser/neu_json_template.c index 2cd6f8685..01dc2e005 100644 --- a/src/parser/neu_json_template.c +++ b/src/parser/neu_json_template.c @@ -26,6 +26,13 @@ #include "neu_json_template.h" +/** + * 将模板组编码成JSON对象 + * + * @param json_obj JSON对象指针，用于存储编码结果 + * @param param 指向模板组的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_template_group(void *json_obj, void *param) { int ret = 0; @@ -66,6 +73,13 @@ int neu_json_encode_template_group(void *json_obj, void *param) return ret; } +/** + * 从JSON对象解码模板组数据 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param grp 指向模板组结构的指针，用于存储解码结果 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_template_group(void * json_obj, neu_json_template_group_t *grp) { @@ -109,12 +123,24 @@ int neu_json_decode_template_group(void * json_obj, return -1; } +/** + * 释放模板组结构中分配的内存资源 + * + * @param grp 指向要释放资源的模板组结构的指针 + */ void neu_json_decode_template_group_fini(neu_json_template_group_t *grp) { free(grp->name); neu_json_decode_tag_array_fini(&grp->tags); } +/** + * 将模板组数组编码成JSON对象 + * + * @param json_obj JSON对象指针，用于存储编码结果 + * @param param 指向模板组数组的指针，作为要编码的数据 + * @return 成功返回0，失败返回-1 + */ int neu_json_encode_template_group_array(void *json_obj, void *param) { neu_json_template_group_array_t *array = param; @@ -136,6 +162,13 @@ int neu_json_encode_template_group_array(void *json_obj, void *param) return 0; } +/** + * 从JSON对象解码模板组数组数据 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param arr 指向模板组数组结构的指针，用于存储解码结果 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_template_group_array_json( void *json_obj, neu_json_template_group_array_t *arr) { @@ -179,6 +212,11 @@ int neu_json_decode_template_group_array_json( return -1; } +/** + * 释放模板组数组结构中分配的内存资源 + * + * @param arr 指向要释放资源的模板组数组结构的指针 + */ void neu_json_decode_template_group_array_fini( neu_json_template_group_array_t *arr) { @@ -188,6 +226,13 @@ void neu_json_decode_template_group_array_fini( free(arr->groups); } +/** + * 将模板编码成JSON对象 + * + * @param json_obj JSON对象指针，用于存储编码结果 + * @param param 指向模板的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_template(void *json_obj, void *param) { int ret = 0; @@ -228,6 +273,13 @@ int neu_json_encode_template(void *json_obj, void *param) return ret; } +/** + * 从JSON字符串解码模板数据 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的模板结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_template(char *buf, neu_json_template_t **result) { neu_json_template_t *tmpl = calloc(1, sizeof(neu_json_add_tags_req_t)); @@ -252,6 +304,13 @@ int neu_json_decode_template(char *buf, neu_json_template_t **result) return ret; } +/** + * 从JSON对象解码模板数据 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param tmpl 指向模板结构的指针，用于存储解码结果 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_template_json(void *json_obj, neu_json_template_t *tmpl) { int ret = 0; @@ -297,6 +356,11 @@ int neu_json_decode_template_json(void *json_obj, neu_json_template_t *tmpl) return -1; } +/** + * 释放模板结构中分配的内存资源 + * + * @param tmpl 指向要释放资源的模板结构的指针 + */ void neu_json_decode_template_fini(neu_json_template_t *tmpl) { free(tmpl->name); @@ -304,6 +368,11 @@ void neu_json_decode_template_fini(neu_json_template_t *tmpl) neu_json_decode_template_group_array_fini(&tmpl->groups); } +/** + * 释放模板结构及其自身的内存 + * + * @param tmpl 指向要释放的模板结构的指针 + */ void neu_json_decode_template_free(neu_json_template_t *tmpl) { if (tmpl) { @@ -312,6 +381,13 @@ void neu_json_decode_template_free(neu_json_template_t *tmpl) } } +/** + * 将模板信息数组编码成JSON对象 + * + * @param json_obj JSON对象指针，用于存储编码结果 + * @param param 指向模板信息数组的指针，作为要编码的数据 + * @return 成功返回0，失败返回-1 + */ int neu_json_encode_template_info_array(void *json_obj, void *param) { int ret = 0; @@ -353,6 +429,13 @@ int neu_json_encode_template_info_array(void *json_obj, void *param) return ret; } +/** + * 将获取模板响应编码成JSON对象 + * + * @param json_obj JSON对象指针，用于存储编码结果 + * @param param 指向要编码的数据 + * @return 成功返回0，失败返回-1 + */ int neu_json_encode_get_templates_resp(void *json_obj, void *param) { void *info_array = neu_json_array(); @@ -378,6 +461,13 @@ int neu_json_encode_get_templates_resp(void *json_obj, void *param) NEU_JSON_ELEM_SIZE(req_elems)); } +/** + * 将添加模板组请求编码成JSON对象 + * + * @param json_obj JSON对象指针，用于存储编码结果 + * @param param 指向添加模板组请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_template_add_group_req(void *json_obj, void *param) { int ret = 0; @@ -404,6 +494,13 @@ int neu_json_encode_template_add_group_req(void *json_obj, void *param) return ret; } +/** + * 从JSON字符串解码添加模板组请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的添加模板组请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_template_add_group_req( char *buf, neu_json_template_add_group_req_t **result) { @@ -454,6 +551,11 @@ int neu_json_decode_template_add_group_req( return -1; } +/** + * 释放添加模板组请求结构的内存 + * + * @param req 指向要释放的添加模板组请求结构的指针 + */ void neu_json_decode_template_add_group_req_free( neu_json_template_add_group_req_t *req) { @@ -464,6 +566,13 @@ void neu_json_decode_template_add_group_req_free( } } +/** + * 从JSON字符串解码更新模板组请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的更新模板组请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_template_update_group_req( char *buf, neu_json_template_update_group_req_t **result) { @@ -527,6 +636,11 @@ int neu_json_decode_template_update_group_req( return -1; } +/** + * 释放更新模板组请求结构的内存 + * + * @param req 指向要释放的更新模板组请求结构的指针 + */ void neu_json_decode_template_update_group_req_free( neu_json_template_update_group_req_t *req) { @@ -537,6 +651,13 @@ void neu_json_decode_template_update_group_req_free( free(req); } +/** + * 将删除模板组请求编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向删除模板组请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_template_del_group_req(void *json_object, void *param) { int ret = 0; @@ -558,6 +679,13 @@ int neu_json_encode_template_del_group_req(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码删除模板组请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的删除模板组请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_template_del_group_req( char *buf, neu_json_template_del_group_req_t **result) { @@ -602,6 +730,11 @@ int neu_json_decode_template_del_group_req( return -1; } +/** + * 释放删除模板组请求结构的内存 + * + * @param req 指向要释放的删除模板组请求结构的指针 + */ void neu_json_decode_template_del_group_req_free( neu_json_template_del_group_req_t *req) { @@ -612,6 +745,13 @@ void neu_json_decode_template_del_group_req_free( } } +/** + * 将修改模板标签请求编码成JSON对象 + * + * @param json_obj JSON对象指针，用于存储编码结果 + * @param param 指向修改模板标签请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_template_mod_tags_req(void *json_obj, void *param) { int ret = 0; @@ -654,6 +794,13 @@ int neu_json_encode_template_mod_tags_req(void *json_obj, void *param) return ret; } +/** + * 从JSON字符串解码修改模板标签请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的修改模板标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_template_mod_tags_req( char *buf, neu_json_template_mod_tags_req_t **result) { @@ -718,6 +865,11 @@ int neu_json_decode_template_mod_tags_req( return ret; } +/** + * 释放修改模板标签请求结构的内存 + * + * @param req 指向要释放的修改模板标签请求结构的指针 + */ void neu_json_decode_template_mod_tags_req_free( neu_json_template_mod_tags_req_t *req) { @@ -736,6 +888,13 @@ void neu_json_decode_template_mod_tags_req_free( free(req); } +/** + * 将删除模板标签请求编码成JSON对象 + * + * @param json_object JSON对象指针，用于存储编码结果 + * @param param 指向删除模板标签请求的指针，作为要编码的数据 + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_template_del_tags_req(void *json_object, void *param) { int ret = 0; @@ -778,6 +937,13 @@ int neu_json_encode_template_del_tags_req(void *json_object, void *param) return ret; } +/** + * 从JSON字符串解码删除模板标签请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的删除模板标签请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_template_del_tags_req( char *buf, neu_json_template_del_tags_req_t **result) { @@ -838,6 +1004,11 @@ int neu_json_decode_template_del_tags_req( return -1; } +/** + * 释放删除模板标签请求结构的内存 + * + * @param req 指向要释放的删除模板标签请求结构的指针 + */ void neu_json_decode_template_del_tags_req_free( neu_json_template_del_tags_req_t *req) { @@ -856,6 +1027,13 @@ void neu_json_decode_template_del_tags_req_free( free(req); } +/** + * 从JSON对象解码模板实例请求 + * + * @param json_obj JSON对象指针，包含要解码的数据 + * @param req 指向模板实例请求结构的指针，用于存储解码结果 + * @return 成功返回0，失败返回非0值 + */ int decode_template_inst_req_json(void * json_obj, neu_json_template_inst_req_t *req) { @@ -884,6 +1062,13 @@ int decode_template_inst_req_json(void * json_obj, return ret; } +/** + * 从JSON字符串解码模板实例请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的模板实例请求结构 + * @return 成功返回0，失败返回非0值 + */ int neu_json_decode_template_inst_req(char * buf, neu_json_template_inst_req_t **result) { @@ -913,6 +1098,11 @@ int neu_json_decode_template_inst_req(char * buf, return ret; } +/** + * 释放模板实例请求结构的内存 + * + * @param req 指向要释放的模板实例请求结构的指针 + */ void neu_json_decode_template_inst_req_free(neu_json_template_inst_req_t *req) { if (req) { @@ -922,6 +1112,13 @@ void neu_json_decode_template_inst_req_free(neu_json_template_inst_req_t *req) } } +/** + * 从JSON字符串解码模板实例数组请求 + * + * @param buf 包含JSON数据的字符串 + * @param result 二级指针，用于返回解码后的模板实例数组请求结构 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_template_insts_req(char * buf, neu_json_template_insts_req_t **result) { @@ -975,6 +1172,11 @@ int neu_json_decode_template_insts_req(char * buf, return -1; } +/** + * 释放模板实例数组请求结构的内存 + * + * @param req 指向要释放的模板实例数组请求结构的指针 + */ void neu_json_decode_template_insts_req_free(neu_json_template_insts_req_t *req) { if (req) { diff --git a/src/persist/json/persist_json_plugin.c b/src/persist/json/persist_json_plugin.c index 0c33eea20..983f91ab1 100644 --- a/src/persist/json/persist_json_plugin.c +++ b/src/persist/json/persist_json_plugin.c @@ -29,6 +29,14 @@ #include "persist/json/persist_json_plugin.h" +/** + * 解码JSON字符串为插件请求结构体 + * + * @param buf JSON字符串 + * @param result 输出参数，解码后的插件请求结构体 + * + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_plugin_req(char *buf, neu_json_plugin_req_t **result) { int ret = 0; @@ -82,6 +90,11 @@ int neu_json_decode_plugin_req(char *buf, neu_json_plugin_req_t **result) return ret; } +/** + * 释放插件请求结构体 + * + * @param req 插件请求结构体 + */ void neu_json_decode_plugin_req_free(neu_json_plugin_req_t *req) { @@ -96,6 +109,14 @@ void neu_json_decode_plugin_req_free(neu_json_plugin_req_t *req) free(req); } +/** + * 编码插件响应结构体为JSON对象 + * + * @param json_object JSON对象 + * @param param 插件响应结构体 + * + * @return 成功返回0，失败返回非0值 + */ int neu_json_encode_plugin_resp(void *json_object, void *param) { int ret = 0; diff --git a/src/persist/persist.c b/src/persist/persist.c index 23cb8b3ac..6cf6860af 100644 --- a/src/persist/persist.c +++ b/src/persist/persist.c @@ -57,6 +57,14 @@ pthread_rwlock_t global_rwlock = PTHREAD_RWLOCK_INITIALIZER; static int global_node_count = 0; static int global_tag_count = 0; +/** + * 检查字符串是否以指定后缀结尾 + * + * @param str 要检查的字符串 + * @param suffix 后缀字符串 + * + * @return 如果字符串以指定后缀结尾，返回true，否则返回false + */ static inline bool ends_with(const char *str, const char *suffix) { size_t m = strlen(str); @@ -65,15 +73,14 @@ static inline bool ends_with(const char *str, const char *suffix) } /** - * Concatenate a path string to another. + * 连接路径字符串 * - * @param dst destination path string buffer - * @param len destination path string len, not greater than size - * @param size destination path buffer size - * @param src path string + * @param dst 目标路径字符串缓冲区 + * @param len 目标路径字符串长度，不大于缓冲区大小 + * @param size 目标路径缓冲区大小 + * @param src 源路径字符串 * - * @return length of the result path string excluding the terminating NULL - * byte, `size` indicates overflow. + * @return 结果路径字符串的长度（不包括终止NULL字节），如果溢出则返回size */ static int path_cat(char *dst, size_t len, size_t size, const char *src) { @@ -98,6 +105,14 @@ static int path_cat(char *dst, size_t len, size_t size, const char *src) return i; } +/** + * 将字符串写入文件 + * + * @param fn 文件名 + * @param s 要写入的字符串 + * + * @return 成功返回0，失败返回-1 + */ static int write_file_string(const char *fn, const char *s) { char *tmp = NULL; @@ -137,7 +152,14 @@ static int write_file_string(const char *fn, const char *s) return 0; } -// read all file contents as string +/** + * 读取文件内容为字符串 + * + * @param fn 文件名 + * @param out 输出参数，保存读取到的字符串 + * + * @return 成功返回0，失败返回-1 + */ static int read_file_string(const char *fn, char **out) { int rv = 0; @@ -188,6 +210,15 @@ static int read_file_string(const char *fn, char **out) return rv; } +/** + * 执行SQL语句 + * + * @param db 数据库连接 + * @param sql SQL语句格式字符串 + * @param ... 格式化参数 + * + * @return 成功返回0，失败返回错误码 + */ static inline int execute_sql(sqlite3 *db, const char *sql, ...) { int rv = 0; @@ -216,6 +247,15 @@ static inline int execute_sql(sqlite3 *db, const char *sql, ...) return rv; } +/** + * 获取数据库架构版本 + * + * @param db 数据库连接 + * @param version_p 输出参数，保存版本字符串 + * @param dirty_p 输出参数，表示数据库是否为脏状态 + * + * @return 成功返回0，失败返回错误码 + */ static int get_schema_version(sqlite3 *db, char **version_p, bool *dirty_p) { sqlite3_stmt *stmt = NULL; @@ -245,11 +285,28 @@ static int get_schema_version(sqlite3 *db, char **version_p, bool *dirty_p) return 0; } +/** + * 比较两个架构版本字符串 + * + * @param a 第一个版本字符串指针 + * @param b 第二个版本字符串指针 + * + * @return 比较结果 + */ int schema_version_cmp(const void *a, const void *b) { return strcmp(*(char **) a, *(char **) b); } +/** + * 从文件名中提取架构信息 + * + * @param file 文件名 + * @param version_p 输出参数，保存版本字符串 + * @param description_p 输出参数，保存描述字符串 + * + * @return 成功返回0，失败返回错误码 + */ static int extract_schema_info(const char *file, char **version_p, char **description_p) { @@ -293,6 +350,14 @@ static int extract_schema_info(const char *file, char **version_p, return 0; } +/** + * 检查架构版本是否应该应用 + * + * @param db 数据库连接 + * @param version 版本字符串 + * + * @return 1表示应该应用，0表示不应该应用，-1表示出错 + */ static int should_apply(sqlite3 *db, const char *version) { int rv = 0; @@ -324,6 +389,15 @@ static int should_apply(sqlite3 *db, const char *version) return rv; } +/** + * 应用架构文件到数据库 + * + * @param db 数据库连接 + * @param dir 目录路径 + * @param file 文件名 + * + * @return 成功返回0，失败返回-1 + */ static int apply_schema_file(sqlite3 *db, const char *dir, const char *file) { int rv = 0; @@ -401,6 +475,13 @@ static int apply_schema_file(sqlite3 *db, const char *dir, const char *file) return rv; } +/** + * 收集目录中的架构文件 + * + * @param dir 目录路径 + * + * @return 架构文件列表数组，失败返回NULL + */ static UT_array *collect_schemas(const char *dir) { DIR * dirp = NULL; @@ -425,6 +506,14 @@ static UT_array *collect_schemas(const char *dir) return files; } +/** + * 应用架构文件到数据库 + * + * @param db 数据库连接 + * @param dir 架构文件目录 + * + * @return 成功返回0，失败返回错误码 + */ static int apply_schemas(sqlite3 *db, const char *dir) { int rv = 0; @@ -478,6 +567,11 @@ static int apply_schemas(sqlite3 *db, const char *dir) return rv; } +/** + * 加载节点计数 + * + * @return 成功返回0，失败返回-1 + */ static inline int node_count_load() { int rv = 0; @@ -497,6 +591,11 @@ static inline int node_count_load() return rv; } +/** + * 加载标签计数 + * + * @return 成功返回0，失败返回-1 + */ static inline int tag_count_load() { int rv = 0; @@ -516,6 +615,13 @@ static inline int tag_count_load() return rv; } +/** + * 创建持久化存储 + * + * @param schema_dir 架构文件目录 + * + * @return 成功返回0，失败返回-1 + */ int neu_persister_create(const char *schema_dir) { int rv = sqlite3_open(db_file, &global_db); @@ -557,11 +663,21 @@ int neu_persister_create(const char *schema_dir) return 0; } +/** + * 获取数据库连接 + * + * @return 数据库连接对象 + */ sqlite3 *neu_persister_get_db() { return global_db; } +/** + * 增加节点计数 + * + * @param n 增加的数量 + */ static inline void node_count_add(int n) { pthread_rwlock_wrlock(&global_rwlock); @@ -569,6 +685,11 @@ static inline void node_count_add(int n) pthread_rwlock_unlock(&global_rwlock); } +/** + * 获取节点计数 + * + * @return 节点数量 + */ int neu_persister_node_count() { pthread_rwlock_rdlock(&global_rwlock); @@ -577,6 +698,11 @@ int neu_persister_node_count() return cnt; } +/** + * 增加标签计数 + * + * @param n 增加的数量 + */ static inline void tag_count_add(int n) { pthread_rwlock_wrlock(&global_rwlock); @@ -584,6 +710,11 @@ static inline void tag_count_add(int n) pthread_rwlock_unlock(&global_rwlock); } +/** + * 获取标签计数 + * + * @return 标签数量 + */ int neu_persister_tag_count() { pthread_rwlock_rdlock(&global_rwlock); @@ -592,11 +723,21 @@ int neu_persister_tag_count() return cnt; } +/** + * 销毁持久化存储 + */ void neu_persister_destroy() { sqlite3_close(global_db); } +/** + * 存储节点信息 + * + * @param info 节点信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_node(neu_persist_node_info_t *info) { int rv = 0; @@ -617,6 +758,13 @@ static UT_icd node_info_icd = { (dtor_f *) neu_persist_node_info_fini, }; +/** + * 加载所有节点信息 + * + * @param node_infos 输出参数，保存节点信息数组 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_load_nodes(UT_array **node_infos) { int rv = 0; @@ -664,6 +812,13 @@ int neu_persister_load_nodes(UT_array **node_infos) return rv; } +/** + * 删除节点 + * + * @param node_name 节点名称 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_delete_node(const char *node_name) { // rely on foreign key constraints to remove settings, groups, tags and @@ -677,18 +832,41 @@ int neu_persister_delete_node(const char *node_name) return rv; } +/** + * 更新节点名称 + * + * @param node_name 原节点名称 + * @param new_name 新节点名称 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_update_node(const char *node_name, const char *new_name) { return execute_sql(global_db, "UPDATE nodes SET name=%Q WHERE name=%Q;", new_name, node_name); } +/** + * 更新节点状态 + * + * @param node_name 节点名称 + * @param state 新状态 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_update_node_state(const char *node_name, int state) { return execute_sql(global_db, "UPDATE nodes SET state=%i WHERE name=%Q;", state, node_name); } +/** + * 存储插件信息 + * + * @param plugin_infos 插件信息数组 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_plugins(UT_array *plugin_infos) { int index = 0; @@ -723,6 +901,14 @@ int neu_persister_store_plugins(UT_array *plugin_infos) return rv; } +/** + * 从文件加载插件信息 + * + * @param fname 文件名 + * @param plugin_infos 输出参数，保存插件信息数组 + * + * @return 成功返回0，失败返回错误码 + */ static int load_plugins_file(const char *fname, UT_array *plugin_infos) { char *json_str = NULL; @@ -749,11 +935,26 @@ static int load_plugins_file(const char *fname, UT_array *plugin_infos) return 0; } +/** + * 字符串比较函数 + * + * @param a 第一个字符串指针 + * @param b 第二个字符串指针 + * + * @return 比较结果 + */ static int ut_str_cmp(const void *a, const void *b) { return strcmp(*(char **) a, *(char **) b); } +/** + * 加载插件信息 + * + * @param plugin_infos 输出参数，保存插件信息数组 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_load_plugins(UT_array **plugin_infos) { UT_array *default_plugins = NULL; @@ -791,6 +992,15 @@ int neu_persister_load_plugins(UT_array **plugin_infos) return 0; } +/** + * 存储标签 + * + * @param driver_name 驱动名称 + * @param group_name 组名称 + * @param tag 标签信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_tag(const char *driver_name, const char *group_name, const neu_datatag_t *tag) { @@ -811,6 +1021,16 @@ int neu_persister_store_tag(const char *driver_name, const char *group_name, return rv; } +/** + * 批量添加标签 + * + * @param query SQL查询语句 + * @param stmt 预处理语句对象 + * @param tags 标签数组 + * @param n 标签数量 + * + * @return 成功返回0，失败返回-1 + */ static int put_tags(const char *query, sqlite3_stmt *stmt, const neu_datatag_t *tags, size_t n) { @@ -882,6 +1102,16 @@ static int put_tags(const char *query, sqlite3_stmt *stmt, return 0; } +/** + * 批量存储标签 + * + * @param driver_name 驱动名称 + * @param group_name 组名称 + * @param tags 标签数组 + * @param n 标签数量 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_tags(const char *driver_name, const char *group_name, const neu_datatag_t *tags, size_t n) { @@ -933,6 +1163,14 @@ int neu_persister_store_tags(const char *driver_name, const char *group_name, return NEU_ERR_EINTERNAL; } +/** + * 收集标签信息 + * + * @param stmt 预处理语句对象 + * @param tags 输出参数，保存标签数组 + * + * @return 成功返回0，失败返回-1 + */ static int collect_tag_info(sqlite3_stmt *stmt, UT_array **tags) { int step = sqlite3_step(stmt); @@ -962,6 +1200,15 @@ static int collect_tag_info(sqlite3_stmt *stmt, UT_array **tags) return 0; } +/** + * 加载标签 + * + * @param driver_name 驱动名称 + * @param group_name 组名称 + * @param tags 输出参数，保存标签数组 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_load_tags(const char *driver_name, const char *group_name, UT_array **tags) { @@ -1004,6 +1251,15 @@ int neu_persister_load_tags(const char *driver_name, const char *group_name, return NEU_ERR_EINTERNAL; } +/** + * 更新标签 + * + * @param driver_name 驱动名称 + * @param group_name 组名称 + * @param tag 标签信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_update_tag(const char *driver_name, const char *group_name, const neu_datatag_t *tag) { @@ -1020,6 +1276,15 @@ int neu_persister_update_tag(const char *driver_name, const char *group_name, return rv; } +/** + * 更新标签值 + * + * @param driver_name 驱动名称 + * @param group_name 组名称 + * @param tag 标签信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_update_tag_value(const char * driver_name, const char * group_name, const neu_datatag_t *tag) @@ -1033,6 +1298,15 @@ int neu_persister_update_tag_value(const char * driver_name, return rv; } +/** + * 删除标签 + * + * @param driver_name 驱动名称 + * @param group_name 组名称 + * @param tag_name 标签名称 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_delete_tag(const char *driver_name, const char *group_name, const char *tag_name) { @@ -1046,6 +1320,16 @@ int neu_persister_delete_tag(const char *driver_name, const char *group_name, return rv; } +/** + * 存储订阅关系 + * + * @param app_name 应用名称 + * @param driver_name 驱动名称 + * @param group_name 组名称 + * @param params 订阅参数 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_subscription(const char *app_name, const char *driver_name, const char *group_name, const char *params) @@ -1057,6 +1341,16 @@ int neu_persister_store_subscription(const char *app_name, app_name, driver_name, group_name, params); } +/** + * 更新订阅参数 + * + * @param app_name 应用名称 + * @param driver_name 驱动名称 + * @param group_name 组名称 + * @param params 新订阅参数 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_update_subscription(const char *app_name, const char *driver_name, const char *group_name, @@ -1075,6 +1369,14 @@ static UT_icd subscription_info_icd = { (dtor_f *) neu_persist_subscription_info_fini, }; +/** + * 加载应用的所有订阅关系 + * + * @param app_name 应用名称 + * @param subscription_infos 输出参数，保存订阅信息数组 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_load_subscriptions(const char *app_name, UT_array ** subscription_infos) { @@ -1140,6 +1442,15 @@ int neu_persister_load_subscriptions(const char *app_name, return NEU_ERR_EINTERNAL; } +/** + * 删除订阅关系 + * + * @param app_name 应用名称 + * @param driver_name 驱动名称 + * @param group_name 组名称 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_delete_subscription(const char *app_name, const char *driver_name, const char *group_name) @@ -1150,6 +1461,14 @@ int neu_persister_delete_subscription(const char *app_name, app_name, driver_name, group_name); } +/** + * 存储组信息 + * + * @param driver_name 驱动名称 + * @param group_info 组信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_group(const char * driver_name, neu_persist_group_info_t *group_info) { @@ -1159,6 +1478,15 @@ int neu_persister_store_group(const char * driver_name, driver_name, group_info->name, (unsigned) group_info->interval); } +/** + * 更新组信息 + * + * @param driver_name 驱动名称 + * @param group_name 原组名称 + * @param group_info 新组信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_update_group(const char *driver_name, const char *group_name, neu_persist_group_info_t *group_info) { @@ -1194,6 +1522,14 @@ static UT_icd group_info_icd = { (dtor_f *) neu_persist_group_info_fini, }; +/** + * 收集组信息 + * + * @param stmt 预处理语句对象 + * @param group_infos 输出参数，保存组信息数组 + * + * @return 成功返回0，失败返回-1 + */ static int collect_group_info(sqlite3_stmt *stmt, UT_array **group_infos) { int step = sqlite3_step(stmt); @@ -1218,6 +1554,14 @@ static int collect_group_info(sqlite3_stmt *stmt, UT_array **group_infos) return 0; } +/** + * 加载驱动的所有组信息 + * + * @param driver_name 驱动名称 + * @param group_infos 输出参数，保存组信息数组 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_load_groups(const char *driver_name, UT_array **group_infos) { sqlite3_stmt *stmt = NULL; @@ -1250,6 +1594,14 @@ int neu_persister_load_groups(const char *driver_name, UT_array **group_infos) return NEU_ERR_EINTERNAL; } +/** + * 删除组 + * + * @param driver_name 驱动名称 + * @param group_name 组名称 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_delete_group(const char *driver_name, const char *group_name) { // rely on foreign key constraints to delete tags and subscriptions @@ -1262,6 +1614,14 @@ int neu_persister_delete_group(const char *driver_name, const char *group_name) return rv; } +/** + * 存储节点设置 + * + * @param node_name 节点名称 + * @param setting 设置内容 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_node_setting(const char *node_name, const char *setting) { return execute_sql( @@ -1270,6 +1630,14 @@ int neu_persister_store_node_setting(const char *node_name, const char *setting) node_name, setting); } +/** + * 加载节点设置 + * + * @param node_name 节点名称 + * @param setting 输出参数，保存设置内容 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_load_node_setting(const char * node_name, const char **const setting) { @@ -1311,12 +1679,26 @@ int neu_persister_load_node_setting(const char * node_name, return rv; } +/** + * 删除节点设置 + * + * @param node_name 节点名称 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_delete_node_setting(const char *node_name) { return execute_sql(global_db, "DELETE FROM settings WHERE node_name=%Q", node_name); } +/** + * 存储用户信息 + * + * @param user 用户信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_user(const neu_persist_user_info_t *user) { return execute_sql(global_db, @@ -1324,12 +1706,27 @@ int neu_persister_store_user(const neu_persist_user_info_t *user) user->name, user->hash); } +/** + * 更新用户信息 + * + * @param user 用户信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_update_user(const neu_persist_user_info_t *user) { return execute_sql(global_db, "UPDATE users SET password=%Q WHERE name=%Q", user->hash, user->name); } +/** + * 加载用户信息 + * + * @param user_name 用户名 + * @param user_p 输出参数，保存用户信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_load_user(const char * user_name, neu_persist_user_info_t **user_p) { @@ -1385,11 +1782,26 @@ int neu_persister_load_user(const char * user_name, return NEU_ERR_EINTERNAL; } +/** + * 删除用户 + * + * @param user_name 用户名 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_delete_user(const char *user_name) { return execute_sql(global_db, "DELETE FROM users WHERE name=%Q", user_name); } +/** + * 存储模板信息 + * + * @param name 模板名称 + * @param plugin 插件名称 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_template(const char *name, const char *plugin) { return execute_sql(global_db, @@ -1398,6 +1810,11 @@ int neu_persister_store_template(const char *name, const char *plugin) name, plugin); } +/** + * 释放模板信息 + * + * @param info 模板信息 + */ static inline void neu_persist_template_info_fini(neu_persist_template_info_t *info) { @@ -1412,6 +1829,13 @@ static UT_icd template_info_icd = { (dtor_f *) neu_persist_template_info_fini, }; +/** + * 加载所有模板信息 + * + * @param infos 输出参数，保存模板信息数组 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_load_templates(UT_array **infos) { int rv = 0; @@ -1455,18 +1879,38 @@ int neu_persister_load_templates(UT_array **infos) return rv; } +/** + * 删除模板 + * + * @param name 模板名称 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_delete_template(const char *name) { // rely on foreign key constraints to remove groups and tags return execute_sql(global_db, "DELETE FROM templates WHERE name=%Q;", name); } +/** + * 清除所有模板 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_clear_templates() { // rely on foreign key constraints to remove groups and tags return execute_sql(global_db, "DELETE FROM templates"); } +/** + * 存储模板组信息 + * + * @param tmpl_name 模板名称 + * @param group_info 组信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_template_group(const char * tmpl_name, neu_persist_group_info_t *group_info) { @@ -1477,6 +1921,15 @@ int neu_persister_store_template_group(const char * tmpl_name, (unsigned) group_info->interval); } +/** + * 更新模板组信息 + * + * @param tmpl_name 模板名称 + * @param group_name 原组名称 + * @param group_info 新组信息 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_update_template_group(const char * tmpl_name, const char * group_name, neu_persist_group_info_t *group_info) @@ -1506,6 +1959,14 @@ int neu_persister_update_template_group(const char * tmpl_name, return ret; } +/** + * 加载模板的所有组信息 + * + * @param tmpl_name 模板名称 + * @param group_infos 输出参数，保存组信息数组 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_load_template_groups(const char *tmpl_name, UT_array ** group_infos) { @@ -1540,6 +2001,14 @@ int neu_persister_load_template_groups(const char *tmpl_name, return NEU_ERR_EINTERNAL; } +/** + * 删除模板组 + * + * @param tmpl_name 模板名称 + * @param group_name 组名称 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_delete_template_group(const char *tmpl_name, const char *group_name) { @@ -1549,6 +2018,16 @@ int neu_persister_delete_template_group(const char *tmpl_name, tmpl_name, group_name); } +/** + * 存储模板标签 + * + * @param tmpl_name 模板名称 + * @param group_name 组名称 + * @param tags 标签数组 + * @param n 标签数量 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_store_template_tags(const char * tmpl_name, const char * group_name, const neu_datatag_t *tags, size_t n) @@ -1602,6 +2081,15 @@ int neu_persister_store_template_tags(const char * tmpl_name, return NEU_ERR_EINTERNAL; } +/** + * 加载模板标签 + * + * @param tmpl_name 模板名称 + * @param group_name 组名称 + * @param tags 输出参数，保存标签数组 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_load_template_tags(const char *tmpl_name, const char *group_name, UT_array **tags) { @@ -1644,6 +2132,16 @@ int neu_persister_load_template_tags(const char *tmpl_name, return NEU_ERR_EINTERNAL; } +/** + * 更新模板标签 + * + * @param tmpl_name 模板名称 + * @param group_name 组名称 + * @param tags 标签数组 + * @param n 标签数量 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_update_template_tags(const char * tmpl_name, const char * group_name, const neu_datatag_t *tags, size_t n) @@ -1695,6 +2193,16 @@ int neu_persister_update_template_tags(const char * tmpl_name, return NEU_ERR_EINTERNAL; } +/** + * 删除模板标签 + * + * @param tmpl_name 模板名称 + * @param group_name 组名称 + * @param tags 标签名称数组 + * @param n_tag 标签数量 + * + * @return 成功返回0，失败返回错误码 + */ int neu_persister_delete_template_tags(const char * tmpl_name, const char * group_name, const char *const *tags, size_t n_tag) diff --git a/src/utils/asprintf.c b/src/utils/asprintf.c index dd7fe3afd..2ca858094 100644 --- a/src/utils/asprintf.c +++ b/src/utils/asprintf.c @@ -30,6 +30,14 @@ #include "utils/asprintf.h" +/** + * @brief 格式化字符串并将结果存储在动态分配的内存中 + * + * @param strp 指向字符串指针的指针，用于存储格式化结果 + * @param fmt 格式化字符串 + * @param ... 可变参数列表 + * @return int 成功时返回写入的字符数，失败时返回-1 + */ int neu_asprintf(char **strp, const char *fmt, ...) { va_list ap; @@ -39,6 +47,14 @@ int neu_asprintf(char **strp, const char *fmt, ...) return rv; } +/** + * @brief 使用va_list参数格式化字符串并将结果存储在动态分配的内存中 + * + * @param strp 指向字符串指针的指针，用于存储格式化结果 + * @param fmt 格式化字符串 + * @param ap 可变参数列表 + * @return int 成功时返回写入的字符数，失败时返回-1 + */ int neu_vasprintf(char **strp, const char *fmt, va_list ap) { #if defined(_GNU_SOURCE) || defined(BSD) || defined(__APPLE__) diff --git a/src/utils/async_queue.c b/src/utils/async_queue.c index 52e226c8d..f0348f48d 100644 --- a/src/utils/async_queue.c +++ b/src/utils/async_queue.c @@ -44,6 +44,15 @@ struct neu_async_queue { element_list *list; }; +/** + * @brief 创建一个新的异步队列 + * + * @param key_fn 生成元素键值的回调函数 + * @param expire_fn 检查元素是否过期的回调函数 + * @param free_fn 释放元素的回调函数 + * @param max_size 队列的最大容量 + * @return neu_async_queue_t* 返回创建的异步队列对象 + */ neu_async_queue_t *neu_async_queue_new(neu_async_queue_key key_fn, neu_async_queue_expire expire_fn, neu_async_queue_free free_fn, @@ -62,6 +71,11 @@ neu_async_queue_t *neu_async_queue_new(neu_async_queue_key key_fn, return q; } +/** + * @brief 销毁异步队列并释放所有资源 + * + * @param q 要销毁的异步队列 + */ void neu_async_queue_destroy(neu_async_queue_t *q) { element *elt = NULL, *tmp = NULL; @@ -79,6 +93,12 @@ void neu_async_queue_destroy(neu_async_queue_t *q) free(q); } +/** + * @brief 向异步队列中添加元素 + * + * @param q 目标异步队列 + * @param elem 要添加的元素 + */ void neu_async_queue_push(neu_async_queue_t *q, void *elem) { element *elt = NULL; @@ -103,6 +123,14 @@ void neu_async_queue_push(neu_async_queue_t *q, void *elem) pthread_mutex_unlock(&q->mtx); } +/** + * @brief 从异步队列中取出指定键值的元素 + * + * @param q 目标异步队列 + * @param key 要查找的元素键值 + * @param elem 用于存储取出元素的指针 + * @return int 成功取出返回0，失败返回-1 + */ int neu_async_queue_pop(neu_async_queue_t *q, uint64_t key, void **elem) { element *elt = NULL, *tmp = NULL; @@ -130,6 +158,13 @@ int neu_async_queue_pop(neu_async_queue_t *q, uint64_t key, void **elem) return ret; } +/** + * @brief 根据过滤条件移除队列中的元素 + * + * @param q 目标异步队列 + * @param filter 过滤函数，返回true的元素将被移除 + * @param filter_elem 传递给过滤函数的参数 + */ void neu_async_queue_remove(neu_async_queue_t *q, neu_async_queue_filter filter, void *filter_elem) { @@ -147,6 +182,11 @@ void neu_async_queue_remove(neu_async_queue_t *q, neu_async_queue_filter filter, pthread_mutex_unlock(&q->mtx); } +/** + * @brief 清空异步队列中的所有元素 + * + * @param q 要清空的异步队列 + */ void neu_async_queue_clean(neu_async_queue_t *q) { element *el = NULL, *tmp = NULL; diff --git a/src/utils/base64.c b/src/utils/base64.c index 4dd131a25..fbe7139b4 100644 --- a/src/utils/base64.c +++ b/src/utils/base64.c @@ -25,6 +25,13 @@ #include #include +/** + * @brief 将二进制数据编码为Base64字符串 + * + * @param input 需要编码的二进制数据 + * @param length 二进制数据的长度 + * @return char* 返回Base64编码后的字符串，使用后需要调用者释放 + */ char *neu_encode64(const unsigned char *input, int length) { const int pl = 4 * ((length + 2) / 3); @@ -36,6 +43,12 @@ char *neu_encode64(const unsigned char *input, int length) return (char *) output; } +/** + * @brief 计算Base64解码后的数据长度 + * + * @param b64input Base64编码的字符串 + * @return size_t 解码后的数据长度 + */ size_t calcDecodeLength(const char *b64input) { // Calculates the length of a decoded string size_t len = strlen(b64input), padding = 0; @@ -53,6 +66,14 @@ size_t calcDecodeLength(const char *b64input) return (len * 3) / 4 - padding; } +/** + * @brief 解码Base64字符串到二进制数据 + * + * @param b64message Base64编码的字符串 + * @param buffer 用于存储解码后数据的缓冲区指针的地址 + * @param length 解码后数据长度的指针 + * @return int 成功返回0 + */ int Base64Decode(const char *b64message, unsigned char **buffer, int *length) { // Decodes a base64 encoded string BIO *bio, *b64; @@ -75,6 +96,13 @@ int Base64Decode(const char *b64message, unsigned char **buffer, int *length) return (0); // success } +/** + * @brief 将Base64字符串解码为二进制数据 + * + * @param length 用于存储解码后数据长度的指针 + * @param input Base64编码的字符串 + * @return unsigned char* 解码后的二进制数据，使用后需要调用者释放 + */ unsigned char *neu_decode64(int *length, const char *input) { unsigned char *output; diff --git a/src/utils/http.c b/src/utils/http.c index 7dad63319..b971fdbe4 100644 --- a/src/utils/http.c +++ b/src/utils/http.c @@ -32,6 +32,14 @@ #include "utils/http.h" #include "utils/log.h" +/** + * 发送HTTP响应 + * + * @param aio NNG异步I/O对象 + * @param content 响应内容 + * @param status HTTP状态码 + * @return 成功返回0 + */ static int response(nng_aio *aio, char *content, enum nng_http_status status) { nng_http_res *res = NULL; @@ -60,6 +68,15 @@ static int response(nng_aio *aio, char *content, enum nng_http_status status) return 0; } +/** + * URL解码 + * + * @param s 需要解码的URL字符串 + * @param len 输入字符串长度 + * @param buf 输出缓冲区 + * @param size 输出缓冲区大小 + * @return 解码后字符串长度，失败返回-1 + */ ssize_t neu_url_decode(const char *s, size_t len, char *buf, size_t size) { size_t i = 0, j = 0; @@ -81,6 +98,13 @@ ssize_t neu_url_decode(const char *s, size_t len, char *buf, size_t size) return j; } +/** + * 获取HTTP请求头 + * + * @param aio NNG异步I/O对象 + * @param name 请求头名称 + * @return 请求头的值 + */ const char *neu_http_get_header(nng_aio *aio, char *name) { nng_http_req *req = nng_aio_get_input(aio, 0); @@ -88,6 +112,14 @@ const char *neu_http_get_header(nng_aio *aio, char *name) return nng_http_req_get_header(req, name); } +/** + * 获取HTTP请求体 + * + * @param aio NNG异步I/O对象 + * @param data 输出参数，存储请求体数据 + * @param data_size 输出参数，存储请求体大小 + * @return 成功返回0，失败返回-1 + */ int neu_http_get_body(nng_aio *aio, void **data, size_t *data_size) { nng_http_req *req = nng_aio_get_input(aio, 0); @@ -103,20 +135,14 @@ int neu_http_get_body(nng_aio *aio, void **data, size_t *data_size) } } -// Find query parameter value of the given name. -// -// On failure, returns NULL. -// On success, returns an alias pointer to the value following name in the url, -// if `len_p` is not NULL, then stores the length of the value in `*len_p`. -// -// Example -// ------- -// 1. get_param("/?key=val", "key", &len) will return a pointer to "val" -// and store 3 in len. -// 2. get_param("/?key&foo", "key", &len) will return a pointer to "&foo" -// and store 0 in len. -// 3. get_param("/?foo=bar", "key", &len) will return NULL and will not -// touch len. +/** + * 从URL中获取参数值 + * + * @param url URL字符串 + * @param name 参数名 + * @param len_p 输出参数，存储参数值长度 + * @return 参数值的指针，如果不存在返回NULL + */ static char *get_param(const char *url, const char *name, size_t *len_p) { const char *query = strchr(url, '?'); @@ -172,6 +198,14 @@ static char *get_param(const char *url, const char *name, size_t *len_p) return p; } +/** + * 获取HTTP请求参数 + * + * @param aio NNG异步I/O对象 + * @param name 参数名 + * @param len 输出参数，存储参数值长度 + * @return 参数值的指针，如果不存在返回NULL + */ const char *neu_http_get_param(nng_aio *aio, const char *name, size_t *len) { nng_http_req *nng_req = nng_aio_get_input(aio, 0); @@ -182,6 +216,15 @@ const char *neu_http_get_param(nng_aio *aio, const char *name, size_t *len) return val; } +/** + * 获取HTTP请求参数并URL解码为字符串 + * + * @param aio NNG异步I/O对象 + * @param name 参数名 + * @param buf 输出缓冲区 + * @param size 输出缓冲区大小 + * @return 解码后字符串长度，如果参数不存在返回-2，解码失败返回-1 + */ ssize_t neu_http_get_param_str(nng_aio *aio, const char *name, char *buf, size_t size) { @@ -193,6 +236,14 @@ ssize_t neu_http_get_param_str(nng_aio *aio, const char *name, char *buf, return neu_url_decode(s, len, buf, size); } +/** + * 获取HTTP请求参数并转换为无符号最大整数 + * + * @param aio NNG异步I/O对象 + * @param name 参数名 + * @param param 输出参数，存储转换后的整数 + * @return 成功返回0，失败返回-1 + */ int neu_http_get_param_uintmax(nng_aio *aio, const char *name, uintmax_t *param) { size_t len = 0; @@ -219,6 +270,14 @@ int neu_http_get_param_uintmax(nng_aio *aio, const char *name, uintmax_t *param) return 0; } +/** + * 获取HTTP请求参数并转换为uint64_t + * + * @param aio NNG异步I/O对象 + * @param name 参数名 + * @param param 输出参数，存储转换后的整数 + * @return 成功返回0，失败返回-1 + */ int neu_http_get_param_uint64(nng_aio *aio, const char *name, uint64_t *param) { uintmax_t val; @@ -236,6 +295,14 @@ int neu_http_get_param_uint64(nng_aio *aio, const char *name, uint64_t *param) return 0; } +/** + * 获取HTTP请求参数并转换为uint32_t + * + * @param aio NNG异步I/O对象 + * @param name 参数名 + * @param param 输出参数，存储转换后的整数 + * @return 成功返回0，失败返回-1 + */ int neu_http_get_param_uint32(nng_aio *aio, const char *name, uint32_t *param) { uintmax_t val; @@ -253,6 +320,14 @@ int neu_http_get_param_uint32(nng_aio *aio, const char *name, uint32_t *param) return 0; } +/** + * 获取HTTP请求参数并转换为节点类型 + * + * @param aio NNG异步I/O对象 + * @param name 参数名 + * @param param 输出参数，存储转换后的节点类型 + * @return 成功返回0，失败返回-1 + */ int neu_http_get_param_node_type(nng_aio *aio, const char *name, neu_node_type_e *param) { @@ -272,6 +347,14 @@ int neu_http_get_param_node_type(nng_aio *aio, const char *name, return 0; } +/** + * 发送HTTP响应 + * + * @param aio NNG异步I/O对象 + * @param code 错误码 + * @param content 响应内容 + * @return 成功返回0 + */ int neu_http_response(nng_aio *aio, neu_err_code_e code, char *content) { enum nng_http_status status = NNG_HTTP_STATUS_OK; @@ -396,6 +479,15 @@ int neu_http_response(nng_aio *aio, neu_err_code_e code, char *content) return response(aio, content, status); } +/** + * 发送文件作为HTTP响应 + * + * @param aio NNG异步I/O对象 + * @param data 文件数据 + * @param len 文件长度 + * @param disposition Content-Disposition头的值 + * @return 成功返回0，失败返回-1 + */ int neu_http_response_file(nng_aio *aio, void *data, size_t len, const char *disposition) { @@ -433,41 +525,97 @@ int neu_http_response_file(nng_aio *aio, void *data, size_t len, return 0; } +/** + * 发送HTTP 200 OK响应 + * + * @param aio NNG异步I/O对象 + * @param content 响应内容 + * @return 成功返回0 + */ int neu_http_ok(nng_aio *aio, char *content) { return response(aio, content, NNG_HTTP_STATUS_OK); } +/** + * 发送HTTP 201 Created响应 + * + * @param aio NNG异步I/O对象 + * @param content 响应内容 + * @return 成功返回0 + */ int neu_http_created(nng_aio *aio, char *content) { return response(aio, content, NNG_HTTP_STATUS_CREATED); } +/** + * 发送HTTP 206 Partial Content响应 + * + * @param aio NNG异步I/O对象 + * @param content 响应内容 + * @return 成功返回0 + */ int neu_http_partial(nng_aio *aio, char *content) { return response(aio, content, NNG_HTTP_STATUS_PARTIAL_CONTENT); } +/** + * 发送HTTP 400 Bad Request响应 + * + * @param aio NNG异步I/O对象 + * @param content 响应内容 + * @return 成功返回0 + */ int neu_http_bad_request(nng_aio *aio, char *content) { return response(aio, content, NNG_HTTP_STATUS_BAD_REQUEST); } +/** + * 发送HTTP 401 Unauthorized响应 + * + * @param aio NNG异步I/O对象 + * @param content 响应内容 + * @return 成功返回0 + */ int neu_http_unauthorized(nng_aio *aio, char *content) { return response(aio, content, NNG_HTTP_STATUS_UNAUTHORIZED); } +/** + * 发送HTTP 404 Not Found响应 + * + * @param aio NNG异步I/O对象 + * @param content 响应内容 + * @return 成功返回0 + */ int neu_http_not_found(nng_aio *aio, char *content) { return response(aio, content, NNG_HTTP_STATUS_NOT_FOUND); } +/** + * 发送HTTP 409 Conflict响应 + * + * @param aio NNG异步I/O对象 + * @param content 响应内容 + * @return 成功返回0 + */ int neu_http_conflict(nng_aio *aio, char *content) { return response(aio, content, NNG_HTTP_STATUS_CONFLICT); } +/** + * 发送HTTP 500 Internal Server Error响应 + * + * @param aio NNG异步I/O对象 + * @param content 响应内容 + * @return 成功返回0 + */ int neu_http_internal_error(nng_aio *aio, char *content) { return response(aio, content, NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR); diff --git a/src/utils/http_handler.c b/src/utils/http_handler.c index a7e72c173..e33019d4f 100644 --- a/src/utils/http_handler.c +++ b/src/utils/http_handler.c @@ -27,6 +27,12 @@ #include "utils/http_handler.h" #include "utils/log.h" +/** + * @brief 向HTTP服务器添加处理器 + * @param server HTTP服务器实例 + * @param http_handler HTTP处理器配置 + * @return 成功返回0，失败返回-1 + */ int neu_http_add_handler(nng_http_server * server, const struct neu_http_handler *http_handler) { @@ -89,6 +95,10 @@ int neu_http_add_handler(nng_http_server * server, return ret; } +/** + * @brief 处理CORS（跨域资源共享）请求 + * @param aio NNG异步I/O对象 + */ void neu_http_handle_cors(nng_aio *aio) { nng_http_res *res = NULL; diff --git a/src/utils/http_proxy.c b/src/utils/http_proxy.c index 4e5057e8b..e90735535 100644 --- a/src/utils/http_proxy.c +++ b/src/utils/http_proxy.c @@ -27,6 +27,10 @@ struct http_proxy_ctx; +/** + * @brief 处理代理请求的回调函数 + * @param aio NNG异步I/O对象 + */ static void handle_proxy(nng_aio *aio); typedef struct { @@ -48,6 +52,10 @@ struct http_proxy_ctx { struct http_proxy_ctx *next; }; +/** + * @brief 释放HTTP代理上下文 + * @param ctx 要释放的HTTP代理上下文 + */ static void http_proxy_ctx_free(struct http_proxy_ctx *ctx) { if (NULL == ctx) { @@ -56,6 +64,13 @@ static void http_proxy_ctx_free(struct http_proxy_ctx *ctx) nng_aio_free(ctx->aio); } +/** + * @brief 分配并初始化HTTP代理 + * @param proxy 输出参数，指向分配的HTTP代理 + * @param src_url 源URL + * @param dst_url 目标URL + * @return 成功返回0，失败返回负数 + */ static int http_proxy_alloc(http_proxy_t **proxy, const char *src_url, const char *dst_url) { @@ -113,6 +128,10 @@ static int http_proxy_alloc(http_proxy_t **proxy, const char *src_url, return ret; } +/** + * @brief 释放HTTP代理资源 + * @param proxy 要释放的HTTP代理 + */ static void http_proxy_free(http_proxy_t *proxy) { if (NULL == proxy) { @@ -138,6 +157,12 @@ static void http_proxy_free(http_proxy_t *proxy) free(proxy); } +/** + * @brief 设置HTTP请求的URI，替换源URI为目标URI + * @param proxy HTTP代理 + * @param req HTTP请求 + * @return 成功返回0，失败返回-1 + */ static inline int http_proxy_set_uri(http_proxy_t *proxy, nng_http_req *req) { const char *uri = nng_http_req_get_uri(req); @@ -170,6 +195,10 @@ static inline int http_proxy_set_uri(http_proxy_t *proxy, nng_http_req *req) return 0; } +/** + * @brief HTTP代理回调函数，处理从目标服务器返回的响应 + * @param arg 回调参数，HTTP代理上下文 + */ static void http_proxy_cb(void *arg) { int rv = 0; @@ -204,6 +233,11 @@ static void http_proxy_cb(void *arg) pthread_mutex_unlock(&ctx->proxy->mtx); } +/** + * @brief 获取HTTP代理上下文，优先从空闲列表获取，无可用时创建新的 + * @param proxy HTTP代理 + * @return 成功返回HTTP代理上下文指针，失败返回NULL + */ static struct http_proxy_ctx *http_proxy_get_ctx(http_proxy_t *proxy) { pthread_mutex_lock(&proxy->mtx); @@ -231,6 +265,12 @@ static struct http_proxy_ctx *http_proxy_get_ctx(http_proxy_t *proxy) return ctx; } +/** + * @brief 创建HTTP代理处理器 + * @param http_handler HTTP处理器配置 + * @param handler 输出参数，指向创建的HTTP处理器 + * @return 成功返回0，失败返回错误码 + */ int neu_http_proxy_handler(const struct neu_http_handler *http_handler, nng_http_handler ** handler) { @@ -285,6 +325,10 @@ int neu_http_proxy_handler(const struct neu_http_handler *http_handler, return ret; } +/** + * @brief 处理HTTP代理请求 + * @param aio NNG异步I/O对象 + */ static void handle_proxy(nng_aio *aio) { nng_http_res * res = NULL; diff --git a/src/utils/json.c b/src/utils/json.c index 3bb3c5038..12109f1f9 100644 --- a/src/utils/json.c +++ b/src/utils/json.c @@ -25,6 +25,12 @@ #include "utils/log.h" #include "json/json.h" +/** + * 将元素值编码为JSON对象 + * + * @param ele 要编码的元素 + * @return 编码后的JSON对象，失败返回NULL + */ static json_t *encode_object_value(neu_json_elem_t *ele) { json_t *ob = NULL; @@ -55,6 +61,13 @@ static json_t *encode_object_value(neu_json_elem_t *ele) return ob; } +/** + * 将元素编码到JSON对象中 + * + * @param object 目标JSON对象 + * @param ele 要编码的元素 + * @return 更新后的JSON对象 + */ static json_t *encode_object(json_t *object, neu_json_elem_t ele) { json_t *ob = object; @@ -101,6 +114,13 @@ static json_t *encode_object(json_t *object, neu_json_elem_t ele) return ob; } +/** + * 从JSON对象解码元素 + * + * @param root JSON对象 + * @param ele 要填充的元素 + * @return 成功返回0，失败返回-1 + */ static int decode_object(json_t *root, neu_json_elem_t *ele) { json_t *ob = NULL; @@ -194,11 +214,24 @@ static int decode_object(json_t *root, neu_json_elem_t *ele) return 0; } +/** + * 创建新的JSON数组 + * + * @return 新创建的JSON数组 + */ void *neu_json_array() { return json_array(); } +/** + * 解码JSON字符串到元素数组 + * + * @param buf JSON字符串 + * @param size 元素数组大小 + * @param ele 用于存储解码结果的元素数组 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode(char *buf, int size, neu_json_elem_t *ele) { json_error_t error; @@ -223,6 +256,14 @@ int neu_json_decode(char *buf, int size, neu_json_elem_t *ele) return 0; } +/** + * 从JSON对象解码到元素数组 + * + * @param json JSON对象 + * @param size 元素数组大小 + * @param ele 用于存储解码结果的元素数组 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_by_json(void *json, int size, neu_json_elem_t *ele) { if (json == NULL) { @@ -239,6 +280,16 @@ int neu_json_decode_by_json(void *json, int size, neu_json_elem_t *ele) return 0; } +/** + * 解码JSON字符串中的数组元素 + * + * @param buf JSON字符串 + * @param name 数组名称 + * @param index 数组索引 + * @param size 元素数组大小 + * @param ele 用于存储解码结果的元素数组 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_array(char *buf, char *name, int index, int size, neu_json_elem_t *ele) { @@ -278,6 +329,15 @@ int neu_json_decode_array(char *buf, char *name, int index, int size, return 0; } +/** + * 解码JSON数组中的元素 + * + * @param json JSON数组 + * @param index 数组索引 + * @param size 元素数组大小 + * @param ele 用于存储解码结果的元素数组 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_array_elem(void *json, int index, int size, neu_json_elem_t *ele) { @@ -297,6 +357,16 @@ int neu_json_decode_array_elem(void *json, int index, int size, return 0; } +/** + * 从JSON对象解码数组元素 + * + * @param json JSON对象 + * @param name 数组名称 + * @param index 数组索引 + * @param size 元素数组大小 + * @param ele 用于存储解码结果的元素数组 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_array_by_json(void *json, char *name, int index, int size, neu_json_elem_t *ele) { @@ -322,6 +392,13 @@ int neu_json_decode_array_by_json(void *json, char *name, int index, int size, return 0; } +/** + * 获取JSON对象中数组的大小 + * + * @param json JSON对象 + * @param child 数组名称 + * @return 成功返回数组大小，失败返回-1 + */ int neu_json_decode_array_size_by_json(void *json, char *child) { json_t *ob; @@ -337,6 +414,13 @@ int neu_json_decode_array_size_by_json(void *json, char *child) return ret; } +/** + * 获取JSON字符串中数组的大小 + * + * @param buf JSON字符串 + * @param child 数组名称 + * @return 成功返回数组大小，失败返回-1 + */ int neu_json_decode_array_size(char *buf, char *child) { json_error_t error; @@ -363,6 +447,14 @@ int neu_json_decode_array_size(char *buf, char *child) return ret; } +/** + * 将元素值编码为JSON数组 + * + * @param array 现有数组或NULL创建新数组 + * @param t 元素数组 + * @param n 元素数量 + * @return 更新后的JSON数组 + */ void *neu_json_encode_array_value(void *array, neu_json_elem_t *t, int n) { @@ -377,6 +469,14 @@ void *neu_json_encode_array_value(void *array, neu_json_elem_t *t, int n) return array; } +/** + * 将元素编码为JSON数组 + * + * @param array 现有数组或NULL创建新数组 + * @param t 元素数组 + * @param n 元素数量 + * @return 更新后的JSON数组 + */ void *neu_json_encode_array(void *array, neu_json_elem_t *t, int n) { if (array == NULL) { @@ -392,16 +492,34 @@ void *neu_json_encode_array(void *array, neu_json_elem_t *t, int n) return array; } +/** + * 创建新的JSON对象 + * + * @return 新创建的JSON对象 + */ void *neu_json_encode_new() { return json_object(); } +/** + * 释放JSON对象 + * + * @param json_object 要释放的JSON对象 + */ void neu_json_encode_free(void *json_object) { json_decref(json_object); } +/** + * 编码元素到JSON对象 + * + * @param json_object 目标JSON对象 + * @param elem 元素数组 + * @param n 元素数量 + * @return 成功返回0 + */ int neu_json_encode_field(void *json_object, neu_json_elem_t *elem, int n) { for (int i = 0; i < n; i++) { @@ -411,6 +529,13 @@ int neu_json_encode_field(void *json_object, neu_json_elem_t *elem, int n) return 0; } +/** + * 将JSON对象编码为字符串 + * + * @param json_object JSON对象 + * @param str 输出参数，存储编码后的字符串 + * @return 成功返回0 + */ int neu_json_encode(void *json_object, char **str) { *str = json_dumps(json_object, JSON_REAL_PRECISION(16)); @@ -418,6 +543,12 @@ int neu_json_encode(void *json_object, char **str) return 0; } +/** + * 从字符串解析新的JSON对象 + * + * @param buf JSON字符串 + * @return 成功返回JSON对象，失败返回NULL + */ void *neu_json_decode_new(const char *buf) { json_error_t error; @@ -434,6 +565,13 @@ void *neu_json_decode_new(const char *buf) return root; } +/** + * 从二进制数据解析新的JSON对象 + * + * @param buf 二进制数据 + * @param len 数据长度 + * @return 成功返回JSON对象，失败返回NULL + */ void *neu_json_decode_newb(char *buf, size_t len) { json_error_t error; @@ -450,16 +588,37 @@ void *neu_json_decode_newb(char *buf, size_t len) return root; } +/** + * 释放JSON对象 + * + * @param ob 要释放的JSON对象 + */ void neu_json_decode_free(void *ob) { json_decref(ob); } +/** + * 从JSON对象解码单个元素值 + * + * @param object JSON对象 + * @param ele 要填充的元素 + * @return 成功返回0，失败返回-1 + */ int neu_json_decode_value(void *object, neu_json_elem_t *ele) { return decode_object(object, ele); } +/** + * 从JSON对象中提取指定键的值并转为JSON字符串 + * + * @param object JSON对象 + * @param key 键名 + * @param result 输出参数，存储提取结果的JSON字符串 + * @param must_exist 键是否必须存在 + * @return 成功返回0，失败返回-1 + */ int neu_json_dump_key(void *object, const char *key, char **const result, bool must_exist) { @@ -487,6 +646,15 @@ int neu_json_dump_key(void *object, const char *key, char **const result, return rv; } +/** + * 从JSON字符串加载指定键的值到JSON对象 + * + * @param object 目标JSON对象 + * @param key 键名 + * @param input 输入JSON字符串 + * @param must_exist 键是否必须存在 + * @return 成功返回0，失败返回-1 + */ int neu_json_load_key(void *object, const char *key, const char *input, bool must_exist) { diff --git a/src/utils/log.c b/src/utils/log.c index 19b52d9c2..1bfb05202 100644 --- a/src/utils/log.c +++ b/src/utils/log.c @@ -25,6 +25,13 @@ #include "utils/utarray.h" #include "utils/utextend.h" +/** + * 收集指定节点的所有日志文件 + * + * @param dir 日志文件所在目录 + * @param node 节点名称 + * @return 包含所有匹配日志文件名的数组，失败返回NULL + */ static UT_array *collect_logs(const char *dir, const char *node) { DIR * dirp = NULL; @@ -51,6 +58,11 @@ static UT_array *collect_logs(const char *dir, const char *node) return files; } +/** + * 删除指定节点的所有日志文件 + * + * @param node 节点名称 + */ void remove_logs(const char *node) { UT_array *files = collect_logs("./logs", node); diff --git a/src/utils/mem_cache.c b/src/utils/mem_cache.c index c77b443f3..6efae0fa1 100644 --- a/src/utils/mem_cache.c +++ b/src/utils/mem_cache.c @@ -18,6 +18,13 @@ struct neu_mem_cache { element *head; }; +/** + * 创建内存缓存 + * + * @param max_bytes 最大字节数限制，0表示无限制 + * @param max_items 最大项目数限制，0表示无限制 + * @return 成功返回创建的内存缓存指针，失败返回NULL + */ neu_mem_cache_t *neu_mem_cache_create(const size_t max_bytes, const size_t max_items) { @@ -36,6 +43,13 @@ neu_mem_cache_t *neu_mem_cache_create(const size_t max_bytes, cache_item_t neu_mem_cache_earliest(neu_mem_cache_t *cache); +/** + * 检查缓存是否已满 + * + * @param cache 内存缓存指针 + * @param item 要添加的项目 + * @return 如果缓存已满返回true，否则返回false + */ static bool queue_is_full(neu_mem_cache_t *cache, cache_item_t *item) { if ((0 != cache->max_bytes) && @@ -50,6 +64,12 @@ static bool queue_is_full(neu_mem_cache_t *cache, cache_item_t *item) return false; } +/** + * 减少缓存大小以便添加新项目 + * + * @param cache 内存缓存指针 + * @param item 要添加的项目 + */ static void queue_reduce(neu_mem_cache_t *cache, cache_item_t *item) { while (queue_is_full(cache, item)) { @@ -64,6 +84,13 @@ static void queue_reduce(neu_mem_cache_t *cache, cache_item_t *item) } } +/** + * 向内存缓存添加项目 + * + * @param cache 内存缓存指针 + * @param item 要添加的项目 + * @return 成功返回0，失败返回-1 + */ int neu_mem_cache_add(neu_mem_cache_t *cache, cache_item_t *item) { assert(NULL != cache); @@ -83,6 +110,12 @@ int neu_mem_cache_add(neu_mem_cache_t *cache, cache_item_t *item) return 0; } +/** + * 获取并移除缓存中最早添加的项目 + * + * @param cache 内存缓存指针 + * @return 返回最早添加的项目，如果缓存为空则返回空项目 + */ cache_item_t neu_mem_cache_earliest(neu_mem_cache_t *cache) { assert(NULL != cache); @@ -102,6 +135,12 @@ cache_item_t neu_mem_cache_earliest(neu_mem_cache_t *cache) return item; } +/** + * 获取并移除缓存中最近添加的项目 + * + * @param cache 内存缓存指针 + * @return 返回最近添加的项目，如果缓存为空则返回空项目 + */ cache_item_t neu_mem_cache_latest(neu_mem_cache_t *cache) { assert(NULL != cache); @@ -121,6 +160,13 @@ cache_item_t neu_mem_cache_latest(neu_mem_cache_t *cache) return item; } +/** + * 获取缓存当前使用情况 + * + * @param cache 内存缓存指针 + * @param bytes 输出参数，返回当前使用的字节数 + * @param msgs 输出参数，返回当前项目数 + */ void neu_mem_cache_used(neu_mem_cache_t *cache, size_t *bytes, size_t *msgs) { assert(NULL != cache); @@ -129,6 +175,13 @@ void neu_mem_cache_used(neu_mem_cache_t *cache, size_t *bytes, size_t *msgs) *msgs = cache->used_items; } +/** + * 调整缓存大小限制 + * + * @param cache 内存缓存指针 + * @param new_bytes 新的字节数限制 + * @param new_items 新的项目数限制 + */ void neu_mem_cache_resize(neu_mem_cache_t *cache, size_t new_bytes, size_t new_items) { @@ -140,6 +193,14 @@ void neu_mem_cache_resize(neu_mem_cache_t *cache, size_t new_bytes, queue_reduce(cache, &item); } +/** + * 导出并清空缓存中的所有项目 + * + * @param cache 内存缓存指针 + * @param callback 处理每个项目的回调函数 + * @param ctx 传递给回调函数的上下文 + * @return 成功返回0 + */ int neu_mem_cache_dump(neu_mem_cache_t *cache, cache_dump callback, void *ctx) { assert(NULL != cache); @@ -162,6 +223,12 @@ int neu_mem_cache_dump(neu_mem_cache_t *cache, cache_dump callback, void *ctx) return 0; } +/** + * 清空缓存中的所有项目 + * + * @param cache 内存缓存指针 + * @return 成功返回0 + */ int neu_mem_cache_clear(neu_mem_cache_t *cache) { assert(NULL != cache); @@ -181,6 +248,11 @@ int neu_mem_cache_clear(neu_mem_cache_t *cache) return 0; } +/** + * 销毁内存缓存 + * + * @param cache 要销毁的内存缓存指针 + */ void neu_mem_cache_destroy(neu_mem_cache_t *cache) { assert(NULL != cache); diff --git a/src/utils/neu_jwt.c b/src/utils/neu_jwt.c index d489c8ea2..80d0cc180 100644 --- a/src/utils/neu_jwt.c +++ b/src/utils/neu_jwt.c @@ -43,6 +43,12 @@ static struct public_key_store key_store; static char neuron_private_key[2048] = { 0 }; static char neuron_public_key[2048] = { 0 }; +/** + * 在密钥存储中查找指定名称的密钥 + * + * @param name 要查找的密钥名称 + * @return 找到的密钥索引，未找到返回-1 + */ static int find_key(const char *name) { for (int i = 0; i < key_store.size; i++) { @@ -54,6 +60,12 @@ static int find_key(const char *name) return -1; } +/** + * 添加密钥到密钥存储 + * + * @param name 密钥名称 + * @param value 密钥内容 + */ static void add_key(char *name, char *value) { key_store.size += 1; @@ -65,6 +77,13 @@ static void add_key(char *name, char *value) sizeof(key_store.key[key_store.size - 1].key) - 1); } +/** + * 从指定目录加载密钥文件内容 + * + * @param dir 目录路径 + * @param name 文件名 + * @return 文件内容，如果加载失败返回NULL + */ static char *load_key(const char *dir, char *name) { FILE * f = NULL; @@ -93,6 +112,11 @@ static char *load_key(const char *dir, char *name) return content; } +/** + * 加载Neuron系统的公钥和私钥 + * + * @param dir_path 密钥文件目录路径 + */ static void load_neuron_key(const char *dir_path) { char *content = load_key(dir_path, "neuron.key"); @@ -106,6 +130,11 @@ static void load_neuron_key(const char *dir_path) strncpy(neuron_public_key, content, sizeof(neuron_public_key) - 1); } +/** + * 扫描并加载目录中的所有公钥文件 + * + * @param dir_path 公钥文件目录路径 + */ static void scanf_key(const char *dir_path) { DIR * dir = NULL; @@ -138,6 +167,12 @@ static void scanf_key(const char *dir_path) closedir(dir); } +/** + * 初始化JWT模块，加载密钥 + * + * @param dir_path 密钥文件目录路径 + * @return 成功返回0，失败返回错误码 + */ int neu_jwt_init(const char *dir_path) { load_neuron_key(dir_path); @@ -145,6 +180,12 @@ int neu_jwt_init(const char *dir_path) return 0; } +/** + * 创建新的JWT令牌 + * + * @param token 输出参数，存储生成的JWT令牌 + * @return 成功返回0，失败返回-1 + */ int neu_jwt_new(char **token) { struct timeval tv = { 0 }; @@ -214,6 +255,12 @@ int neu_jwt_new(char **token) return -1; } +/** + * 解码JWT令牌 + * + * @param token 要解码的JWT令牌 + * @return 解码后的JWT结构，解码失败返回NULL + */ static void *neu_jwt_decode(char *token) { jwt_t * jwt = NULL; @@ -273,6 +320,12 @@ static void *neu_jwt_decode(char *token) return jwt; } +/** + * 验证JWT令牌的有效性 + * + * @param b_token 带Bearer前缀的JWT令牌 + * @return 成功返回NEU_ERR_SUCCESS，失败返回相应错误码 + */ int neu_jwt_validate(char *b_token) { jwt_valid_t *jwt_valid = NULL; @@ -333,6 +386,9 @@ int neu_jwt_validate(char *b_token) return NEU_ERR_SUCCESS; } +/** + * 销毁JWT模块资源 + */ void neu_jwt_destroy() { // memset(token_local, 0, sizeof(token_local));