From 61475a0a7bc3854f19698417852d40d0cba22c4e Mon Sep 17 00:00:00 2001 From: wangmm0220 Date: Tue, 4 Jun 2024 17:24:10 +0800 Subject: [PATCH] docs:[TD-30393]add api document for tmq --- docs/en/08-client-libraries/03-cpp.mdx | 17 +++++++++++++++-- docs/zh/08-connector/10-cpp.mdx | 17 +++++++++++++++-- source/client/src/clientTmq.c | 8 ++++---- 3 files changed, 34 insertions(+), 8 deletions(-) diff --git a/docs/en/08-client-libraries/03-cpp.mdx b/docs/en/08-client-libraries/03-cpp.mdx index e343f59400..97fea49902 100644 --- a/docs/en/08-client-libraries/03-cpp.mdx +++ b/docs/en/08-client-libraries/03-cpp.mdx @@ -483,10 +483,18 @@ In addition to writing data using the SQL method or the parameter binding API, w ``` **Description** - tmq_conf_new : create a tmq_conf_t structure to configure consumption parameters - - tmq_conf_set : set configuration, key is parameter name，value is parameter value - - tmq_conf_set_auto_commit_cb : set automatic commit callback function, cb is call back function, param is callback function parameter + - tmq_conf_set : set configuration, configuration is key-value pair + - tmq_conf_set_auto_commit_cb : set auto commit callback function - tmq_conf_destroy : destroy tmq_conf_t structure + **Parameter description** + - tmq_conf_set : key is parameter name，value is parameter value + - tmq_conf_set_auto_commit_cb : cb is callback function, param is callback function parameter + + **Return value** + - tmq_conf_new: structure of tmq_conf_t, NULL failed + - tmq_conf_set: tmq_conf_res_t, TMQ_CONF_OK means success, others means failure + - `tmq_list_t *tmq_list_new()` - `int32_t tmq_list_append(tmq_list_t *, const char *)` @@ -501,6 +509,11 @@ In addition to writing data using the SQL method or the parameter binding API, w - tmq_list_get_size : get size of tmq_list_t - tmq_list_to_c_array : convert tmq_list_t to c array, element is string pointer + **Return value** + - tmq_list_new : structure of tmq_list_t, tmq_list_t is a list of strings, NULL failed + - tmq_list_append : zero success, none zero failed, wrong message can be obtained through `char *tmq_err2str(int32_t code)` + - tmq_list_get_size : size of tmq_list_t, -1 failed + - tmq_list_to_c_array : c array, element is pointer of string, NULL failed - `tmq_t *tmq_consumer_new(tmq_conf_t *conf, char *errstr, int32_t errstrLen)` - `int32_t tmq_subscribe(tmq_t *tmq, const tmq_list_t *topic_list)` diff --git a/docs/zh/08-connector/10-cpp.mdx b/docs/zh/08-connector/10-cpp.mdx index 746c09f59d..f03777ac4b 100644 --- a/docs/zh/08-connector/10-cpp.mdx +++ b/docs/zh/08-connector/10-cpp.mdx @@ -558,10 +558,17 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多 ``` **功能说明** - tmq_conf_new 接口用于创建一个 tmq_conf_t 结构体，用于配置消费参数。 - - tmq_conf_set 接口用于设置消费参数，key 为参数名，value 为参数值。 - - tmq_conf_set_auto_commit_cb 接口用于设置自动提交回调函数，参数为回调函数和回调函数的参数。 + - tmq_conf_set 接口用于设置消费参数。 + - tmq_conf_set_auto_commit_cb 接口用于设置自动提交回调函数。 - tmq_conf_destroy 接口用于销毁 tmq_conf_t 结构体。 + **参数说明** + - tmq_conf_set : key 为参数名，value 为参数值 + - tmq_conf_set_auto_commit_cb : cb 回调函数, param 回调函数参数 + + **返回值** + - tmq_conf_new: 配置 tmq_conf_t 类型指针, NULL 失败 + - tmq_conf_set: 结果 tmq_conf_res_t 类型, TMQ_CONF_OK 成功, 其他失败 - `tmq_list_t *tmq_list_new()` - `int32_t tmq_list_append(tmq_list_t *, const char *)` @@ -576,6 +583,12 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多 - tmq_list_get_size 接口用于获取 tmq_list_t 结构体中 topic 的个数。 - tmq_list_to_c_array 接口用于将 tmq_list_t 结构体转换为 C 数组，数组每个元素为字符串指针。 + **返回值** + - tmq_list_new : 返回 tmq_list_t 结果指针, tmq_list_t 是一个数组，每个元素是一个字符串, NULL 失败 + - tmq_list_append : 返回 0 表示成功，非0表示失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息。 + - tmq_list_get_size : 返回 tmq_list_t 结构体中 topic 的个数, -1 失败 + - tmq_list_to_c_array : 返回 c 数组, 每个元素是字符串指针, NULL 失败 + - `tmq_t *tmq_consumer_new(tmq_conf_t *conf, char *errstr, int32_t errstrLen)` - `int32_t tmq_subscribe(tmq_t *tmq, const tmq_list_t *topic_list)` diff --git a/source/client/src/clientTmq.c b/source/client/src/clientTmq.c index 8fe3dc4afa..6c06ee853c 100644 --- a/source/client/src/clientTmq.c +++ b/source/client/src/clientTmq.c @@ -412,11 +412,11 @@ tmq_conf_res_t tmq_conf_set(tmq_conf_t* conf, const char* key, const char* value tmq_list_t* tmq_list_new() { return (tmq_list_t*)taosArrayInit(0, sizeof(void*)); } int32_t tmq_list_append(tmq_list_t* list, const char* src) { - if (list == NULL) return -1; + if (list == NULL) return TSDB_CODE_INVALID_PARA; SArray* container = &list->container; - if (src == NULL || src[0] == 0) return -1; + if (src == NULL || src[0] == 0) return TSDB_CODE_INVALID_PARA; char* topic = taosStrdup(src); - if (taosArrayPush(container, &topic) == NULL) return -1; + if (taosArrayPush(container, &topic) == NULL) return TSDB_CODE_INVALID_PARA; return 0; } @@ -2708,7 +2708,7 @@ int32_t tmqCommitDone(SMqCommitCbParamSet* pParamSet) { if (tmq == NULL) { taosMemoryFree(pParamSet); terrno = TSDB_CODE_TMQ_CONSUMER_CLOSED; - return -1; + return terrno; } // if no more waiting rsp