The Connector section of the official website reconstructs the C language interface description
This commit is contained in:
Yaming Pei
gccgdb1234
parent
46ed6551a5
commit
a476dd4f66
|
|
@ -25,49 +25,51 @@
|
|||
|
||||
static int DemoCreateDB() {
|
||||
// ANCHOR: create_db_and_table
|
||||
int ret_code = -1;
|
||||
const char *ip = "localhost";
|
||||
const char *user = "root";
|
||||
const char *password = "taosdata";
|
||||
const char *ip = "localhost";
|
||||
const char *user = "root";
|
||||
const char *password = "taosdata";
|
||||
|
||||
// connect
|
||||
TAOS *taos = taos_connect(ip, user, password, NULL, 0);
|
||||
if (taos == NULL) {
|
||||
printf("failed to connect to server, reason: %s\n", taos_errstr(NULL));
|
||||
goto end;
|
||||
}
|
||||
// connect
|
||||
TAOS *taos = taos_connect(ip, user, password, NULL, 0);
|
||||
if (taos == NULL) {
|
||||
printf("failed to connect to server, reason: %s\n", taos_errstr(NULL));
|
||||
taos_cleanup();
|
||||
return -1;
|
||||
}
|
||||
|
||||
// create database
|
||||
TAOS_RES *result = taos_query(taos, "CREATE DATABASE IF NOT EXISTS power");
|
||||
int code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to create database, reason: %s\n", taos_errstr(result));
|
||||
goto end;
|
||||
}
|
||||
taos_free_result(result);
|
||||
printf("success to create database\n");
|
||||
|
||||
// use database
|
||||
result = taos_query(taos, "USE power");
|
||||
taos_free_result(result);
|
||||
|
||||
// create table
|
||||
const char* sql = "CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))";
|
||||
result = taos_query(taos, sql);
|
||||
code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to create table, reason: %s\n", taos_errstr(result));
|
||||
goto end;
|
||||
}
|
||||
taos_free_result(result);
|
||||
printf("success to create table\n");
|
||||
ret_code = 0;
|
||||
|
||||
end:
|
||||
// close & clean
|
||||
// create database
|
||||
TAOS_RES *result = taos_query(taos, "CREATE DATABASE IF NOT EXISTS power");
|
||||
int code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to create database, reason: %s\n", taos_errstr(result));
|
||||
taos_close(taos);
|
||||
taos_cleanup();
|
||||
return ret_code;
|
||||
return -1;
|
||||
}
|
||||
taos_free_result(result);
|
||||
printf("success to create database\n");
|
||||
|
||||
// use database
|
||||
result = taos_query(taos, "USE power");
|
||||
taos_free_result(result);
|
||||
|
||||
// create table
|
||||
const char* sql = "CREATE STABLE IF NOT EXISTS meters (ts TIMESTAMP, current FLOAT, voltage INT, phase FLOAT) TAGS (groupId INT, location BINARY(24))";
|
||||
result = taos_query(taos, sql);
|
||||
code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to create table, reason: %s\n", taos_errstr(result));
|
||||
taos_close(taos);
|
||||
taos_cleanup();
|
||||
return -1;
|
||||
}
|
||||
taos_free_result(result);
|
||||
printf("success to create table\n");
|
||||
|
||||
// close & clean
|
||||
taos_close(taos);
|
||||
taos_cleanup();
|
||||
return 0;
|
||||
// ANCHOR_END: create_db_and_table
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -24,50 +24,50 @@
|
|||
|
||||
static int DemoInsertData() {
|
||||
// ANCHOR: insert_data
|
||||
int ret_code = -1;
|
||||
const char *ip = "localhost";
|
||||
const char *user = "root";
|
||||
const char *password = "taosdata";
|
||||
const char *ip = "localhost";
|
||||
const char *user = "root";
|
||||
const char *password = "taosdata";
|
||||
|
||||
// connect
|
||||
TAOS *taos = taos_connect(ip, user, password, NULL, 0);
|
||||
if (taos == NULL) {
|
||||
printf("failed to connect to server, reason: %s\n", taos_errstr(NULL));
|
||||
goto end;
|
||||
}
|
||||
// connect
|
||||
TAOS *taos = taos_connect(ip, user, password, NULL, 0);
|
||||
if (taos == NULL) {
|
||||
printf("failed to connect to server, reason: %s\n", taos_errstr(NULL));
|
||||
taos_cleanup();
|
||||
return -1;
|
||||
}
|
||||
|
||||
// use database
|
||||
TAOS_RES *result = taos_query(taos, "USE power");
|
||||
taos_free_result(result);
|
||||
// use database
|
||||
TAOS_RES *result = taos_query(taos, "USE power");
|
||||
taos_free_result(result);
|
||||
|
||||
// insert data, please make sure the database and table are already created
|
||||
const char* sql = "INSERT INTO " \
|
||||
"power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') " \
|
||||
"VALUES " \
|
||||
"(NOW + 1a, 10.30000, 219, 0.31000) " \
|
||||
"(NOW + 2a, 12.60000, 218, 0.33000) " \
|
||||
"(NOW + 3a, 12.30000, 221, 0.31000) " \
|
||||
"power.d1002 USING power.meters TAGS(3, 'California.SanFrancisco') " \
|
||||
"VALUES " \
|
||||
"(NOW + 1a, 10.30000, 218, 0.25000) ";
|
||||
result = taos_query(taos, sql);
|
||||
int code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to insert rows, reason: %s\n", taos_errstr(result));
|
||||
goto end;
|
||||
}
|
||||
taos_free_result(result);
|
||||
|
||||
// you can check affectedRows here
|
||||
int rows = taos_affected_rows(result);
|
||||
printf("success to insert %d rows\n", rows);
|
||||
ret_code = 0;
|
||||
|
||||
end:
|
||||
// close & clean
|
||||
// insert data, please make sure the database and table are already created
|
||||
const char* sql = "INSERT INTO " \
|
||||
"power.d1001 USING power.meters TAGS(2,'California.SanFrancisco') " \
|
||||
"VALUES " \
|
||||
"(NOW + 1a, 10.30000, 219, 0.31000) " \
|
||||
"(NOW + 2a, 12.60000, 218, 0.33000) " \
|
||||
"(NOW + 3a, 12.30000, 221, 0.31000) " \
|
||||
"power.d1002 USING power.meters TAGS(3, 'California.SanFrancisco') " \
|
||||
"VALUES " \
|
||||
"(NOW + 1a, 10.30000, 218, 0.25000) ";
|
||||
result = taos_query(taos, sql);
|
||||
int code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to insert rows, reason: %s\n", taos_errstr(result));
|
||||
taos_close(taos);
|
||||
taos_cleanup();
|
||||
return ret_code;
|
||||
return -1;
|
||||
}
|
||||
taos_free_result(result);
|
||||
|
||||
// you can check affectedRows here
|
||||
int rows = taos_affected_rows(result);
|
||||
printf("success to insert %d rows\n", rows);
|
||||
|
||||
// close & clean
|
||||
taos_close(taos);
|
||||
taos_cleanup();
|
||||
return 0;
|
||||
// ANCHOR_END: insert_data
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -25,55 +25,55 @@
|
|||
|
||||
static int DemoQueryData() {
|
||||
// ANCHOR: query_data
|
||||
int ret_code = -1;
|
||||
const char *ip = "localhost";
|
||||
const char *user = "root";
|
||||
const char *password = "taosdata";
|
||||
const char *ip = "localhost";
|
||||
const char *user = "root";
|
||||
const char *password = "taosdata";
|
||||
|
||||
// connect
|
||||
TAOS *taos = taos_connect(ip, user, password, NULL, 0);
|
||||
if (taos == NULL) {
|
||||
printf("failed to connect to server, reason: %s\n", taos_errstr(NULL));
|
||||
goto end;
|
||||
}
|
||||
// connect
|
||||
TAOS *taos = taos_connect(ip, user, password, NULL, 0);
|
||||
if (taos == NULL) {
|
||||
printf("failed to connect to server, reason: %s\n", taos_errstr(NULL));
|
||||
taos_cleanup();
|
||||
return -1;
|
||||
}
|
||||
|
||||
// use database
|
||||
TAOS_RES *result = taos_query(taos, "USE power");
|
||||
taos_free_result(result);
|
||||
// use database
|
||||
TAOS_RES *result = taos_query(taos, "USE power");
|
||||
taos_free_result(result);
|
||||
|
||||
// query data, please make sure the database and table are already created
|
||||
const char* sql = "SELECT * FROM power.meters";
|
||||
result = taos_query(taos, sql);
|
||||
int code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to select, reason: %s\n", taos_errstr(result));
|
||||
goto end;
|
||||
}
|
||||
|
||||
TAOS_ROW row = NULL;
|
||||
int rows = 0;
|
||||
int num_fields = taos_field_count(result);
|
||||
TAOS_FIELD *fields = taos_fetch_fields(result);
|
||||
|
||||
printf("fields: %d\n", num_fields);
|
||||
printf("sql: %s, result:\n", sql);
|
||||
|
||||
// fetch the records row by row
|
||||
while ((row = taos_fetch_row(result))) {
|
||||
char temp[1024] = {0};
|
||||
rows++;
|
||||
taos_print_row(temp, row, fields, num_fields);
|
||||
printf("%s\n", temp);
|
||||
}
|
||||
printf("total rows: %d\n", rows);
|
||||
taos_free_result(result);
|
||||
ret_code = 0;
|
||||
|
||||
end:
|
||||
// close & clean
|
||||
// query data, please make sure the database and table are already created
|
||||
const char* sql = "SELECT * FROM power.meters";
|
||||
result = taos_query(taos, sql);
|
||||
int code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to select, reason: %s\n", taos_errstr(result));
|
||||
taos_close(taos);
|
||||
taos_cleanup();
|
||||
return ret_code;
|
||||
return -1;
|
||||
}
|
||||
|
||||
TAOS_ROW row = NULL;
|
||||
int rows = 0;
|
||||
int num_fields = taos_field_count(result);
|
||||
TAOS_FIELD *fields = taos_fetch_fields(result);
|
||||
|
||||
printf("fields: %d\n", num_fields);
|
||||
printf("sql: %s, result:\n", sql);
|
||||
|
||||
// fetch the records row by row
|
||||
while ((row = taos_fetch_row(result))) {
|
||||
char temp[1024] = {0};
|
||||
rows++;
|
||||
taos_print_row(temp, row, fields, num_fields);
|
||||
printf("%s\n", temp);
|
||||
}
|
||||
printf("total rows: %d\n", rows);
|
||||
taos_free_result(result);
|
||||
|
||||
// close & clean
|
||||
taos_close(taos);
|
||||
taos_cleanup();
|
||||
return 0;
|
||||
// ANCHOR_END: query_data
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -25,66 +25,68 @@
|
|||
|
||||
static int DemoWithReqId() {
|
||||
// ANCHOR: with_reqid
|
||||
int ret_code = -1;
|
||||
const char *ip = "localhost";
|
||||
const char *user = "root";
|
||||
const char *password = "taosdata";
|
||||
const char *ip = "localhost";
|
||||
const char *user = "root";
|
||||
const char *password = "taosdata";
|
||||
|
||||
// connect
|
||||
TAOS *taos = taos_connect(ip, user, password, NULL, 0);
|
||||
if (taos == NULL) {
|
||||
printf("failed to connect to server, reason: %s\n", taos_errstr(NULL));
|
||||
goto end;
|
||||
}
|
||||
// connect
|
||||
TAOS *taos = taos_connect(ip, user, password, NULL, 0);
|
||||
if (taos == NULL) {
|
||||
printf("failed to connect to server, reason: %s\n", taos_errstr(NULL));
|
||||
taos_cleanup();
|
||||
return -1;
|
||||
}
|
||||
|
||||
// create database
|
||||
TAOS_RES *result = taos_query_with_reqid(taos, "CREATE DATABASE IF NOT EXISTS power", 1L);
|
||||
int code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to create database, reason: %s\n", taos_errstr(result));
|
||||
taos_free_result(result);
|
||||
goto end;
|
||||
}
|
||||
// create database
|
||||
TAOS_RES *result = taos_query_with_reqid(taos, "CREATE DATABASE IF NOT EXISTS power", 1L);
|
||||
int code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to create database, reason: %s\n", taos_errstr(result));
|
||||
taos_free_result(result);
|
||||
printf("success to create database\n");
|
||||
|
||||
// use database
|
||||
result = taos_query_with_reqid(taos, "USE power", 2L);
|
||||
taos_free_result(result);
|
||||
|
||||
// query data
|
||||
const char* sql = "SELECT * FROM power.meters";
|
||||
result = taos_query_with_reqid(taos, sql, 3L);
|
||||
code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to select, reason: %s\n", taos_errstr(result));
|
||||
goto end;
|
||||
}
|
||||
|
||||
TAOS_ROW row = NULL;
|
||||
int rows = 0;
|
||||
int num_fields = taos_field_count(result);
|
||||
TAOS_FIELD *fields = taos_fetch_fields(result);
|
||||
|
||||
printf("fields: %d\n", num_fields);
|
||||
printf("sql: %s, result:\n", sql);
|
||||
|
||||
// fetch the records row by row
|
||||
while ((row = taos_fetch_row(result))) {
|
||||
char temp[1024] = {0};
|
||||
rows++;
|
||||
taos_print_row(temp, row, fields, num_fields);
|
||||
printf("%s\n", temp);
|
||||
}
|
||||
printf("total rows: %d\n", rows);
|
||||
taos_free_result(result);
|
||||
ret_code = 0;
|
||||
|
||||
end:
|
||||
// close & clean
|
||||
taos_close(taos);
|
||||
taos_cleanup();
|
||||
return ret_code;
|
||||
return -1;
|
||||
}
|
||||
taos_free_result(result);
|
||||
printf("success to create database\n");
|
||||
|
||||
// use database
|
||||
result = taos_query_with_reqid(taos, "USE power", 2L);
|
||||
taos_free_result(result);
|
||||
|
||||
// query data
|
||||
const char* sql = "SELECT * FROM power.meters";
|
||||
result = taos_query_with_reqid(taos, sql, 3L);
|
||||
code = taos_errno(result);
|
||||
if (code != 0) {
|
||||
printf("failed to select, reason: %s\n", taos_errstr(result));
|
||||
taos_close(taos);
|
||||
taos_cleanup();
|
||||
return -1;
|
||||
}
|
||||
|
||||
TAOS_ROW row = NULL;
|
||||
int rows = 0;
|
||||
int num_fields = taos_field_count(result);
|
||||
TAOS_FIELD *fields = taos_fetch_fields(result);
|
||||
|
||||
printf("fields: %d\n", num_fields);
|
||||
printf("sql: %s, result:\n", sql);
|
||||
|
||||
// fetch the records row by row
|
||||
while ((row = taos_fetch_row(result))) {
|
||||
char temp[1024] = {0};
|
||||
rows++;
|
||||
taos_print_row(temp, row, fields, num_fields);
|
||||
printf("%s\n", temp);
|
||||
}
|
||||
printf("total rows: %d\n", rows);
|
||||
taos_free_result(result);
|
||||
|
||||
// close & clean
|
||||
taos_close(taos);
|
||||
taos_cleanup();
|
||||
return 0;
|
||||
// ANCHOR_END: with_reqid
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -57,7 +57,7 @@ TDengine 客户端驱动的安装请参考 [安装指南](../#安装步骤)
|
|||
:::note
|
||||
|
||||
- 如未特别说明，当 API 的返回值是整数时，_0_ 代表成功，其它是代表失败原因的错误码，当返回值是指针时， _NULL_ 表示失败。
|
||||
- 所有的错误码以及对应的原因描述在 `taoserror.h` 文件中。
|
||||
- 所有的错误码以及对应的原因描述在 `taoserror.h` 文件中。<a href="./_01-error-code.md">查看错误代码文档</a>
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -225,7 +225,7 @@ int taos_print_row(char *str, TAOS_ROW row, TAOS_FIELD *fields, int num_fields)
|
|||
|
||||
- `int taos_init()`
|
||||
- **接口说明**：初始化运行环境。如果没有主动调用该 API，那么调用 `taos_connect()` 时驱动将自动调用该 API，故程序一般无需手动调用。
|
||||
- **返回值**：待补充，未找到相关资料。
|
||||
- **返回值**：`0`：成功，`非0`：失败，可调用函数 taos_errstr(NULL) 获取更详细的错误信息。
|
||||
|
||||
- `void taos_cleanup()`
|
||||
- **接口说明**：清理运行环境，应用退出前应调用。
|
||||
|
|
@ -267,24 +267,24 @@ int taos_print_row(char *str, TAOS_ROW row, TAOS_FIELD *fields, int num_fields)
|
|||
- `char *taos_get_server_info(TAOS *taos)`
|
||||
- **接口说明**：获取服务端版本信息。
|
||||
- **参数说明**：
|
||||
- taos：[入参] 数据库连接。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- **返回值**：返回获取服务端版本信息。
|
||||
|
||||
- `int taos_select_db(TAOS *taos, const char *db)`
|
||||
- **接口说明**：将当前的缺省数据库设置为 `db`。
|
||||
- **参数说明**：
|
||||
- taos：[入参] 数据库连接。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- db：[入参] 数据库名称。
|
||||
- **返回值**：`0`：成功，`非0`：失败，详情请参考错误码。待补充。
|
||||
- **返回值**：`0`：成功，`非0`：失败，详情请参考错误码页面。
|
||||
|
||||
- `int taos_get_current_db(TAOS *taos, char *database, int len, int *required)`
|
||||
- **接口说明**：获取当前数据库名称。
|
||||
- **参数说明**：
|
||||
- taos：[入参] 数据库连接。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- database：[出参] 存储当前数据库名称。
|
||||
- len：[入参] database 的空间大小。
|
||||
- required：[出参] 存储当前数据库名称所需的空间（包含最后的'\0'）。
|
||||
- **返回值**：`0`：成功，`-1`：失败，详情请调用 taos_errstr(NULL) 函数来获取错误提示。
|
||||
- **返回值**：`0`：成功，`-1`：失败，可调用函数 taos_errstr(NULL) 获取更详细的错误信息。
|
||||
- 如果，database == NULL 或者 len\<=0 返回失败。
|
||||
- 如果，len 小于 存储数据库名称所需的空间（包含最后的'\0'），返回失败，database 里赋值截断的数据，以'\0'结尾。
|
||||
- 如果，len 大于等于 存储数据库名称所需的空间（包含最后的'\0'），返回成功，database 里赋值以'\0‘结尾数据库名称。
|
||||
|
|
@ -292,16 +292,16 @@ int taos_print_row(char *str, TAOS_ROW row, TAOS_FIELD *fields, int num_fields)
|
|||
- `int taos_set_notify_cb(TAOS *taos, __taos_notify_fn_t fp, void *param, int type)`
|
||||
- **接口说明**：设置事件回调函数。
|
||||
- **参数说明**：
|
||||
- taos：[入参] 数据库连接。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- fp：[入参] 事件回调函数指针。函数声明：typedef void (*__taos_notify_fn_t)(void *param, void *ext, int type)；其中， param 为用户自定义参数，ext 为扩展参数(依赖事件类型，针对 TAOS_NOTIFY_PASSVER 返回用户密码版本)，type 为事件类型。
|
||||
- param：[入参] 用户自定义参数。
|
||||
- type：[入参] 事件类型。取值范围：1）TAOS_NOTIFY_PASSVER： 用户密码改变。
|
||||
- **返回值**：`0`：成功，`-1`：失败，详情请调用 taos_errstr(NULL) 函数来获取错误提示。
|
||||
- **返回值**：`0`：成功，`-1`：失败，可调用函数 taos_errstr(NULL) 获取更详细的错误信息。
|
||||
|
||||
- `void taos_close(TAOS *taos)`
|
||||
- **接口说明**：关闭连接。
|
||||
- **参数说明**：
|
||||
- taos：[入参] 数据库连接。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
|
||||
### 同步查询 API
|
||||
|
||||
|
|
@ -310,7 +310,7 @@ int taos_print_row(char *str, TAOS_ROW row, TAOS_FIELD *fields, int num_fields)
|
|||
- `TAOS_RES* taos_query(TAOS *taos, const char *sql)`
|
||||
- **接口说明**：执行 SQL 语句，可以是 DQL、DML 或 DDL 语句。
|
||||
- **参数说明**：
|
||||
- taos：[入参] 数据库连接。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- sql：[入参] 需要执行 SQL 语句。
|
||||
- **返回值**：不能通过返回值是否是 `NULL` 来判断执行结果是否失败，而是需要调用 `taos_errno()` 函数解析结果集中的错误代码来进行判断。
|
||||
- taos_errno 返回值：`0`：成功，`-1`：失败，详情请调用 taos_errstr 函数来获取错误提示。
|
||||
|
|
@ -324,20 +324,20 @@ int taos_print_row(char *str, TAOS_ROW row, TAOS_FIELD *fields, int num_fields)
|
|||
- `TAOS_ROW taos_fetch_row(TAOS_RES *res)`
|
||||
- **接口说明**：按行获取查询结果集中的数据。
|
||||
- **参数说明**：
|
||||
- res：[入参] 查询结果集。
|
||||
- **返回值**：`非NULL`：成功，`NULL`：失败，详情请调用 taos_errstr(NULL) 函数来获取错误提示。
|
||||
- res：[入参] 结果集。
|
||||
- **返回值**：`非NULL`：成功，`NULL`：失败，可调用函数 taos_errstr(NULL) 获取更详细的错误信息。
|
||||
|
||||
- `int taos_fetch_block(TAOS_RES *res, TAOS_ROW *rows)`
|
||||
- **接口说明**：批量获取查询结果集中的数据。
|
||||
- **参数说明**：
|
||||
- res：[入参] 查询结果集。
|
||||
- res：[入参] 结果集。
|
||||
- rows：[出参] 用于存储从结果集中获取的行。
|
||||
- **返回值**：返回值为获取到的数据的行数，如果没有更多的行则返回 0。
|
||||
|
||||
- `int taos_num_fields(TAOS_RES *res)` 和 `int taos_field_count(TAOS_RES *res)`
|
||||
- **接口说明**：这两个 API 等价，用于获取查询结果集中的列数。
|
||||
- **参数说明**：
|
||||
- res：[入参] 查询结果集。
|
||||
- res：[入参] 结果集。
|
||||
- **返回值**：返回值为结果集中列的数量。
|
||||
|
||||
- `int* taos_fetch_lengths(TAOS_RES *res)`
|
||||
|
|
@ -355,18 +355,18 @@ int taos_print_row(char *str, TAOS_ROW row, TAOS_FIELD *fields, int num_fields)
|
|||
- `TAOS_FIELD *taos_fetch_fields(TAOS_RES *res)`
|
||||
- **接口说明**：获取查询结果集每列数据的属性（列的名称、列的数据类型、列的长度），与 `taos_num_fields()` 配合使用，可用来解析 `taos_fetch_row()` 返回的一个元组(一行)的数据。
|
||||
- **参数说明**：
|
||||
- res：[入参] 查询结果集。
|
||||
- res：[入参] 结果集。
|
||||
- **返回值**：`非NULL`：成功，返回一个指向 TAOS_FIELD 结构体的指针，每个元素代表一列的元数据。`NULL`：失败。
|
||||
|
||||
- `void taos_stop_query(TAOS_RES *res)`
|
||||
- **接口说明**：停止当前查询的执行。
|
||||
- **参数说明**：
|
||||
- res：[入参] 查询结果集。
|
||||
- res：[入参] 结果集。
|
||||
|
||||
- `void taos_free_result(TAOS_RES *res)`
|
||||
- **接口说明**：释放查询结果集以及相关的资源。查询完成后，务必调用该 API 释放资源，否则可能导致应用内存泄露。但也需注意，释放资源后，如果再调用 `taos_consume()` 等获取查询结果的函数，将导致应用崩溃。
|
||||
- **参数说明**：
|
||||
- res：[入参] 查询结果集。
|
||||
- res：[入参] 结果集。
|
||||
|
||||
- `char *taos_errstr(TAOS_RES *res)`
|
||||
- **接口说明**：获取最近一次 API 调用失败的原因，返回值为字符串标识的错误提示信息。
|
||||
|
|
@ -397,7 +397,7 @@ TDengine 还提供性能更高的异步 API 处理数据插入、查询操作。
|
|||
- `void taos_query_a(TAOS *taos, const char *sql, void (*fp)(void *param, TAOS_RES *, int code), void *param);`
|
||||
- **接口说明**：异步执行 SQL 语句。
|
||||
- **参数说明**：
|
||||
- taos：[入参] 数据库连接。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- sql: [入参] 需要执行的 SQL 语句。
|
||||
- fp：用户定义的回调函数，其第三个参数 `code` 用于指示操作是否成功，`0` 表示成功，负数表示失败（调用 `taos_errstr()` 可获取失败原因）。应用在定义回调函数的时候，主要处理第二个参数 `TAOS_RES *`，该参数是查询返回的结果集。
|
||||
- param：应用提供的用于回调的参数。
|
||||
|
|
@ -431,92 +431,95 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多
|
|||
接口相关的具体函数如下（也可以参考 [prepare.c](https://github.com/taosdata/TDengine/blob/develop/examples/c/prepare.c) 文件中使用对应函数的方式）：
|
||||
|
||||
- `TAOS_STMT* taos_stmt_init(TAOS *taos)`
|
||||
|
||||
创建一个 TAOS_STMT 对象用于后续调用。
|
||||
- **接口说明**：初始化一个预编译的 SQL 语句对象。
|
||||
- **参数说明**：
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- **返回值**：`非NULL`：成功，返回一个指向 TAOS_STMT 结构体的指针，该结构体表示预编译的 SQL 语句对象。`NULL`：失败，详情请调用 taos_stmt_errstr() 函数来获取错误提示。
|
||||
|
||||
- `int taos_stmt_prepare(TAOS_STMT *stmt, const char *sql, unsigned long length)`
|
||||
|
||||
解析一条 SQL 语句，将解析结果和参数信息绑定到 stmt 上，如果参数 length 大于 0，将使用此参数作为 SQL 语句的长度，如等于 0，将自动判断 SQL 语句的长度。
|
||||
- **接口说明**：解析一条预编译的 SQL 语句，将解析结果和参数信息绑定到 stmt 上。
|
||||
- **参数说明**：
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- sql：[入参] 需要解析的 SQL 语句。
|
||||
- length：[入参] 参数 sql 的长度。如果参数 length 大于 0，将使用此参数作为 SQL 语句的长度，如等于 0，将自动判断 SQL 语句的长度。
|
||||
- **返回值**：`0`：成功。`非0`：失败，详情请参考错误码页面。
|
||||
|
||||
- `int taos_stmt_bind_param(TAOS_STMT *stmt, TAOS_MULTI_BIND *bind)`
|
||||
|
||||
不如 `taos_stmt_bind_param_batch()` 效率高，但可以支持非 INSERT 类型的 SQL 语句。
|
||||
进行参数绑定，bind 指向一个数组（代表所要绑定的一行数据），需保证此数组中的元素数量和顺序与 SQL 语句中的参数完全一致。TAOS_MULTI_BIND 的使用方法与 MySQL 中的 MYSQL_BIND 类似，具体定义如下：
|
||||
|
||||
```c
|
||||
typedef struct TAOS_MULTI_BIND {
|
||||
int buffer_type;
|
||||
void *buffer;
|
||||
uintptr_t buffer_length;
|
||||
uint32_t *length;
|
||||
char *is_null;
|
||||
int num; // the number of columns
|
||||
} TAOS_MULTI_BIND;
|
||||
```
|
||||
- **接口说明**：绑定参数到一个预编译的 SQL 语句。不如 `taos_stmt_bind_param_batch()` 效率高，但可以支持非 INSERT 类型的 SQL 语句。
|
||||
- **参数说明**：
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- bind：[入参] 指向一个有效的 TAOS_MULTI_BIND 结构体指针，该结构体包含了要绑定到 SQL 语句中的参数列表。需保证此数组中的元素数量和顺序与 SQL 语句中的参数完全一致。TAOS_MULTI_BIND 的使用方法与 MySQL 中的 MYSQL_BIND 类似。
|
||||
- **返回值**：`0`：成功。`非0`：失败，详情请参考错误码页面。
|
||||
|
||||
- `int taos_stmt_set_tbname(TAOS_STMT* stmt, const char* name)`
|
||||
|
||||
（2.1.1.0 版本新增，仅支持用于替换 INSERT 语句中的参数值）
|
||||
当 SQL 语句中的表名使用了 `?` 占位时，可以使用此函数绑定一个具体的表名。
|
||||
- **接口说明**：（2.1.1.0 版本新增，仅支持用于替换 INSERT 语句中的参数值）当 SQL 语句中的表名使用了 `?` 占位时，可以使用此函数绑定一个具体的表名。
|
||||
- **参数说明**：
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- name：[入参] 指向一个包含子表名称的字符串常量。
|
||||
- **返回值**：`0`：成功。`非0`：失败，详情请参考错误码页面。
|
||||
|
||||
- `int taos_stmt_set_tbname_tags(TAOS_STMT* stmt, const char* name, TAOS_MULTI_BIND* tags)`
|
||||
|
||||
（2.1.2.0 版本新增，仅支持用于替换 INSERT 语句中的参数值）
|
||||
当 SQL 语句中的表名和 TAGS 都使用了 `?` 占位时，可以使用此函数绑定具体的表名和具体的 TAGS 取值。最典型的使用场景是使用了自动建表功能的 INSERT 语句（目前版本不支持指定具体的 TAGS 列）。TAGS 参数中的列数量需要与 SQL 语句中要求的 TAGS 数量完全一致。
|
||||
- **接口说明**：（2.1.2.0 版本新增，仅支持用于替换 INSERT 语句中的参数值）当 SQL 语句中的表名和 TAGS 都使用了 `?` 占位时，可以使用此函数绑定具体的表名和具体的 TAGS 取值。最典型的使用场景是使用了自动建表功能的 INSERT 语句（目前版本不支持指定具体的 TAGS 列）。TAGS 参数中的列数量需要与 SQL 语句中要求的 TAGS 数量完全一致。
|
||||
- **参数说明**：
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- name：[入参] 指向一个包含子表名称的字符串常量。
|
||||
- tags：[入参] 指向一个有效的 TAOS_MULTI_BIND 结构体指针，该结构体包含了子表标签的值。
|
||||
- **返回值**：`0`：成功。`非0`：失败，详情请参考错误码页面。
|
||||
|
||||
- `int taos_stmt_bind_param_batch(TAOS_STMT* stmt, TAOS_MULTI_BIND* bind)`
|
||||
|
||||
（2.1.1.0 版本新增，仅支持用于替换 INSERT 语句中的参数值）
|
||||
以多列的方式传递待绑定的数据，需要保证这里传递的数据列的顺序、列的数量与 SQL 语句中的 VALUES 参数完全一致。TAOS_MULTI_BIND 的具体定义如下：
|
||||
- **接口说明**：（2.1.1.0 版本新增，仅支持用于替换 INSERT 语句中的参数值）以多列的方式传递待绑定的数据，需要保证这里传递的数据列的顺序、列的数量与 SQL 语句中的 VALUES 参数完全一致。
|
||||
- **参数说明**：
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- bind：[入参] 指向一个有效的 TAOS_MULTI_BIND 结构体指针，该结构体包含了要批量绑定到 SQL 语句中的参数列表。
|
||||
- **返回值**：`0`：成功。`非0`：失败，详情请参考错误码页面。
|
||||
|
||||
- `int taos_stmt_add_batch(TAOS_STMT *stmt)`
|
||||
|
||||
将当前绑定的参数加入批处理中，调用此函数后，可以再次调用 `taos_stmt_bind_param()` 或 `taos_stmt_bind_param_batch()` 绑定新的参数。需要注意，此函数仅支持 INSERT/IMPORT 语句，如果是 SELECT 等其他 SQL 语句，将返回错误。
|
||||
- **接口说明**：将当前绑定的参数加入批处理中，调用此函数后，可以再次调用 `taos_stmt_bind_param()` 或 `taos_stmt_bind_param_batch()` 绑定新的参数。需要注意，此函数仅支持 INSERT/IMPORT 语句，如果是 SELECT 等其他 SQL 语句，将返回错误。
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- **返回值**：`0`：成功。`非0`：失败，详情请参考错误码页面。
|
||||
|
||||
- `int taos_stmt_execute(TAOS_STMT *stmt)`
|
||||
|
||||
执行准备好的语句。目前，一条语句只能执行一次。
|
||||
- **接口说明**：执行准备好的语句。目前，一条语句只能执行一次。
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- **返回值**：`0`：成功。`非0`：失败，详情请参考错误码页面。
|
||||
|
||||
- `int taos_stmt_affected_rows(TAOS_STMT *stmt)`
|
||||
|
||||
获取执行多次绑定语句影响的行数。
|
||||
- **接口说明**：获取执行预编译 SQL 语句后受影响的行数。
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- **返回值**：返回受影响的行数。
|
||||
|
||||
- `int taos_stmt_affected_rows_once(TAOS_STMT *stmt)`
|
||||
|
||||
获取执行一次绑定语句影响的行数。
|
||||
- **接口说明**：获取执行一次绑定语句影响的行数。
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- **返回值**：返回受影响的行数。
|
||||
|
||||
- `TAOS_RES* taos_stmt_use_result(TAOS_STMT *stmt)`
|
||||
|
||||
获取语句的结果集。结果集的使用方式与非参数化调用时一致，使用完成后，应对此结果集调用 `taos_free_result()` 以释放资源。
|
||||
- **接口说明**：获取语句的结果集。结果集的使用方式与非参数化调用时一致，使用完成后，应对此结果集调用 `taos_free_result()` 以释放资源。
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- **返回值**：`非NULL`：成功，返回一个指向查询结果集的指针。`NULL`：失败，详情请调用 taos_stmt_errstr() 函数来获取错误提示。
|
||||
|
||||
- `int taos_stmt_close(TAOS_STMT *stmt)`
|
||||
|
||||
执行完毕，释放所有资源。
|
||||
- **接口说明**：执行完毕，释放所有资源。
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- **返回值**：`0`：成功。`非0`：失败，详情请参考错误码页面。
|
||||
|
||||
- `char * taos_stmt_errstr(TAOS_STMT *stmt)`
|
||||
|
||||
（2.1.3.0 版本新增）
|
||||
用于在其他 STMT API 返回错误（返回错误码或空指针）时获取错误信息。
|
||||
- **接口说明**：（2.1.3.0 版本新增）用于在其他 STMT API 返回错误（返回错误码或空指针）时获取错误信息。
|
||||
- stmt：[入参] 指向一个有效的预编译的 SQL 语句对象指针。
|
||||
- **返回值**：返回一个指向包含错误信息的字符串的指针。
|
||||
|
||||
### 无模式（schemaless）写入 API
|
||||
|
||||
除了使用 SQL 方式或者使用参数绑定 API 写入数据外，还可以使用 Schemaless 的方式完成写入。Schemaless 可以免于预先创建超级表/数据子表的数据结构，而是可以直接写入数据，TDengine 系统会根据写入的数据内容自动创建和维护所需要的表结构。Schemaless 的使用方式详见 [Schemaless 写入](../../reference/schemaless/) 章节，这里介绍与之配套使用的 C/C++ API。
|
||||
|
||||
- `TAOS_RES* taos_schemaless_insert(TAOS* taos, const char* lines[], int numLines, int protocol, int precision)`
|
||||
|
||||
**功能说明**
|
||||
- 该接口将行协议的文本数据写入到 TDengine 中。
|
||||
|
||||
**参数说明**
|
||||
- taos: 数据库连接，通过 `taos_connect()` 函数建立的数据库连接。
|
||||
- lines：文本数据。满足解析格式要求的无模式文本字符串。
|
||||
- numLines:文本数据的行数，不能为 0 。
|
||||
- protocol: 行协议类型，用于标识文本数据格式。
|
||||
- precision：文本数据中的时间戳精度字符串。
|
||||
|
||||
**返回值**
|
||||
- TAOS_RES 结构体，应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。
|
||||
在某些情况下，返回的 TAOS_RES 为 `NULL`，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。
|
||||
- **接口说明**：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine 中。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
|
||||
- numLines：[入参] 文本数据的行数，不能为 0 。
|
||||
- protocol：[入参] 行协议类型，用于标识文本数据格式。
|
||||
- precision：[入参] 文本数据中的时间戳精度字符串。
|
||||
- **返回值**：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。在某些情况下，返回的 TAOS_RES 为 `NULL`，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。
|
||||
返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。
|
||||
|
||||
**说明**
|
||||
|
|
@ -542,12 +545,86 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多
|
|||
|
||||
**schemaless 其他相关的接口**
|
||||
- `TAOS_RES *taos_schemaless_insert_with_reqid(TAOS *taos, char *lines[], int numLines, int protocol, int precision, int64_t reqid)`
|
||||
- **接口说明**：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine 中。通过传递参数reqid来跟踪整个的函数调用链情况。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
|
||||
- numLines：[入参] 文本数据的行数，不能为 0 。
|
||||
- protocol：[入参] 行协议类型，用于标识文本数据格式。
|
||||
- precision：[入参] 文本数据中的时间戳精度字符串。
|
||||
- reqid：[入参] 指定的请求 ID，用于跟踪调用请求。请求 ID (reqid) 可以用于在客户端和服务器端之间建立请求和响应之间的关联，对于分布式系统中的跟踪和调试非常有用。
|
||||
- **返回值**：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。在某些情况下，返回的 TAOS_RES 为 `NULL`，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。
|
||||
返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。
|
||||
|
||||
- `TAOS_RES *taos_schemaless_insert_raw(TAOS *taos, char *lines, int len, int32_t *totalRows, int protocol, int precision)`
|
||||
- **接口说明**：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine 中。通过传递的参数lines指针和长度len来表示数据，为了解决原始接口数据包含'\0'而被截断的问题。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
|
||||
- len：[入参] 数据缓冲区 lines 的总长度（字节数）。
|
||||
- totalRows：[出参] 指向一个整数指针，用于返回成功插入的记录总数。
|
||||
- protocol：[入参] 行协议类型，用于标识文本数据格式。
|
||||
- precision：[入参] 文本数据中的时间戳精度字符串。
|
||||
- **返回值**：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。在某些情况下，返回的 TAOS_RES 为 `NULL`，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。
|
||||
返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。
|
||||
|
||||
- `TAOS_RES *taos_schemaless_insert_raw_with_reqid(TAOS *taos, char *lines, int len, int32_t *totalRows, int protocol, int precision, int64_t reqid)`
|
||||
- **接口说明**：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine 中。通过传递的参数lines指针和长度len来表示数据，为了解决原始接口数据包含'\0'而被截断的问题。通过传递参数reqid来跟踪整个的函数调用链情况。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
|
||||
- len：[入参] 数据缓冲区 lines 的总长度（字节数）。
|
||||
- totalRows：[出参] 指向一个整数指针，用于返回成功插入的记录总数。
|
||||
- protocol：[入参] 行协议类型，用于标识文本数据格式。
|
||||
- precision：[入参] 文本数据中的时间戳精度字符串。
|
||||
- reqid：[入参] 指定的请求 ID，用于跟踪调用请求。请求 ID (reqid) 可以用于在客户端和服务器端之间建立请求和响应之间的关联，对于分布式系统中的跟踪和调试非常有用。
|
||||
- **返回值**：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。在某些情况下，返回的 TAOS_RES 为 `NULL`，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。
|
||||
返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。
|
||||
|
||||
- `TAOS_RES *taos_schemaless_insert_ttl(TAOS *taos, char *lines[], int numLines, int protocol, int precision, int32_t ttl)`
|
||||
- **接口说明**：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine 中。通过传递ttl参数来控制建表的ttl到期时间。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
|
||||
- numLines：[入参] 文本数据的行数，不能为 0 。
|
||||
- protocol：[入参] 行协议类型，用于标识文本数据格式。
|
||||
- precision：[入参] 文本数据中的时间戳精度字符串。
|
||||
- ttl：[入参] 指定的生存时间（TTL），单位为天。记录在超过这个生存时间后会被自动删除。
|
||||
- **返回值**：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。在某些情况下，返回的 TAOS_RES 为 `NULL`，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。
|
||||
返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。
|
||||
|
||||
- `TAOS_RES *taos_schemaless_insert_ttl_with_reqid(TAOS *taos, char *lines[], int numLines, int protocol, int precision, int32_t ttl, int64_t reqid)`
|
||||
- **接口说明**：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine 中。通过传递ttl参数来控制建表的ttl到期时间。通过传递参数reqid来跟踪整个的函数调用链情况。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
|
||||
- numLines：[入参] 文本数据的行数，不能为 0 。
|
||||
- protocol：[入参] 行协议类型，用于标识文本数据格式。
|
||||
- precision：[入参] 文本数据中的时间戳精度字符串。
|
||||
- ttl：[入参] 指定的生存时间（TTL），单位为天。记录在超过这个生存时间后会被自动删除。
|
||||
- reqid：[入参] 指定的请求 ID，用于跟踪调用请求。请求 ID (reqid) 可以用于在客户端和服务器端之间建立请求和响应之间的关联，对于分布式系统中的跟踪和调试非常有用。
|
||||
- **返回值**：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。在某些情况下，返回的 TAOS_RES 为 `NULL`，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。
|
||||
返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。
|
||||
|
||||
- `TAOS_RES *taos_schemaless_insert_raw_ttl(TAOS *taos, char *lines, int len, int32_t *totalRows, int protocol, int precision, int32_t ttl)`
|
||||
- **接口说明**：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine 中。通过传递的参数lines指针和长度len来表示数据，为了解决原始接口数据包含'\0'而被截断的问题。通过传递ttl参数来控制建表的ttl到期时间。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
|
||||
- len：[入参] 数据缓冲区 lines 的总长度（字节数）。
|
||||
- totalRows：[出参] 指向一个整数指针，用于返回成功插入的记录总数。
|
||||
- protocol：[入参] 行协议类型，用于标识文本数据格式。
|
||||
- precision：[入参] 文本数据中的时间戳精度字符串。
|
||||
- ttl：[入参] 指定的生存时间（TTL），单位为天。记录在超过这个生存时间后会被自动删除。
|
||||
- **返回值**：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。在某些情况下，返回的 TAOS_RES 为 `NULL`，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。
|
||||
返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。
|
||||
|
||||
- `TAOS_RES *taos_schemaless_insert_raw_ttl_with_reqid(TAOS *taos, char *lines, int len, int32_t *totalRows, int protocol, int precision, int32_t ttl, int64_t reqid)`
|
||||
- **接口说明**：执行无模式的批量插入操作，将行协议的文本数据写入到 TDengine 中。通过传递的参数lines指针和长度len来表示数据，为了解决原始接口数据包含'\0'而被截断的问题。通过传递ttl参数来控制建表的ttl到期时间。通过传递参数reqid来跟踪整个的函数调用链情况。
|
||||
- taos：[入参] 指向数据库连接的指针，数据库连接是通过 `taos_connect()` 函数建立。
|
||||
- lines：[入参] 文本数据。满足解析格式要求的无模式文本字符串。
|
||||
- len：[入参] 数据缓冲区 lines 的总长度（字节数）。
|
||||
- totalRows：[出参] 指向一个整数指针，用于返回成功插入的记录总数。
|
||||
- protocol：[入参] 行协议类型，用于标识文本数据格式。
|
||||
- precision：[入参] 文本数据中的时间戳精度字符串。
|
||||
- ttl：[入参] 指定的生存时间（TTL），单位为天。记录在超过这个生存时间后会被自动删除。
|
||||
- reqid：[入参] 指定的请求 ID，用于跟踪调用请求。请求 ID (reqid) 可以用于在客户端和服务器端之间建立请求和响应之间的关联，对于分布式系统中的跟踪和调试非常有用。
|
||||
- **返回值**：返回一个指向 TAOS_RES 结构体的指针，该结构体包含了插入操作的结果。应用可以通过使用 `taos_errstr()` 获得错误信息，也可以使用 `taos_errno()` 获得错误码。在某些情况下，返回的 TAOS_RES 为 `NULL`，此时仍然可以调用 `taos_errno()` 来安全地获得错误码信息。
|
||||
返回的 TAOS_RES 需要调用方来负责释放，否则会出现内存泄漏。
|
||||
|
||||
**说明**
|
||||
- 上面这7个接口是扩展接口，主要用于在schemaless写入时传递ttl、reqid参数，可以根据需要使用。
|
||||
|
|
@ -557,213 +634,205 @@ TDengine 的异步 API 均采用非阻塞调用模式。应用程序可以用多
|
|||
|
||||
### 数据订阅 API
|
||||
- `const char *tmq_err2str(int32_t code)`
|
||||
- **接口说明**：用于将数据订阅的错误码转换为错误信息。
|
||||
- code：[入参] 数据订阅的错误码。
|
||||
- **返回值**：返回一个指向包含错误信息字符串的指针，返回值非NULL，但是错误信息可能为空字符串。
|
||||
|
||||
**功能说明**
|
||||
- 该接口用于将数据订阅的错误码转换为错误信息
|
||||
|
||||
**参数说明**
|
||||
- code: 数据订阅的错误码
|
||||
- `tmq_conf_t *tmq_conf_new()`
|
||||
- **接口说明**：创建一个新的 TMQ 配置对象。
|
||||
- **返回值**：`非NULL`：成功，返回一个指向 tmq_conf_t 结构体的指针，该结构体用于配置 TMQ 的行为和特性。`NULL`：失败，可调用函数 taos_errstr(NULL) 获取更详细的错误信息。
|
||||
|
||||
**返回值**
|
||||
- 非NULL，返回错误信息，错误信息可能为空字符串
|
||||
|
||||
|
||||
- `tmq_conf_t *tmq_conf_new()`
|
||||
- `tmq_conf_res_t tmq_conf_set(tmq_conf_t *conf, const char *key, const char *value)`
|
||||
- `void tmq_conf_set_auto_commit_cb(tmq_conf_t *conf, tmq_commit_cb *cb, void *param)`
|
||||
- `void tmq_conf_destroy(tmq_conf_t *conf)`
|
||||
tmq_conf_res_t 错误码定义如下：
|
||||
```
|
||||
typedef enum tmq_conf_res_t {
|
||||
TMQ_CONF_UNKNOWN = -2,
|
||||
TMQ_CONF_INVALID = -1,
|
||||
TMQ_CONF_OK = 0,
|
||||
} tmq_conf_res_t;
|
||||
```
|
||||
- **接口说明**：设置 TMQ 配置对象中的配置项，用于配置消费参数。
|
||||
- conf：[入参] 指向一个有效的 tmq_conf_t 结构体指针，该结构体代表一个 TMQ 配置对象。
|
||||
- key：[入参] 数配置项的键名。
|
||||
- value：[入参] 配置项的值。
|
||||
- **返回值**：返回一个 tmq_conf_res_t 枚举值，表示配置设置的结果。
|
||||
- TMQ_CONF_OK：成功设置配置项。
|
||||
- TMQ_CONF_INVALID_KEY：键值无效。
|
||||
- TMQ_CONF_UNKNOWN：键名无效。
|
||||
|
||||
- `void tmq_conf_set_auto_commit_cb(tmq_conf_t *conf, tmq_commit_cb *cb, void *param)`
|
||||
- **接口说明**：设置 TMQ 配置对象中的自动提交回调函数。
|
||||
- conf：[入参] 指向一个有效的 tmq_conf_t 结构体指针，该结构体代表一个 TMQ 配置对象。
|
||||
- cb：[入参] 指向一个有效的 tmq_commit_cb 回调函数指针，该函数将在消息被消费后调用以确认消息处理状态。
|
||||
- param：[入参] 传递给回调函数的用户自定义参数。
|
||||
|
||||
设置自动提交回调函数的定义如下：
|
||||
```
|
||||
typedef void(tmq_commit_cb(tmq_t *tmq, int32_t code, void *param))
|
||||
```
|
||||
**功能说明**
|
||||
- tmq_conf_new 接口用于创建一个 tmq_conf_t 结构体，用于配置消费参数。
|
||||
- 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 成功, 其他失败
|
||||
- `void tmq_conf_destroy(tmq_conf_t *conf)`
|
||||
- **接口说明**：销毁一个 TMQ 配置对象并释放相关资源。
|
||||
- conf：[入参] 指向一个有效的 tmq_conf_t 结构体指针，该结构体代表一个 TMQ 配置对象。
|
||||
|
||||
- `tmq_list_t *tmq_list_new()`
|
||||
- `int32_t tmq_list_append(tmq_list_t *, const char *)`
|
||||
- `void tmq_list_destroy(tmq_list_t *)`
|
||||
- `int32_t tmq_list_get_size(const tmq_list_t *)`
|
||||
- `char **tmq_list_to_c_array(const tmq_list_t *)`
|
||||
- **接口说明**：用于创建一个 tmq_list_t 结构体，用于存储订阅的 topic。
|
||||
- **返回值**：`非NULL`：成功，返回一个指向 tmq_list_t 结构体的指针。`NULL`：失败，可调用函数 taos_errstr(NULL) 获取更详细的错误信息。
|
||||
|
||||
- `int32_t tmq_list_append(tmq_list_t *list, const char* topic)`
|
||||
- **接口说明**：用于向 tmq_list_t 结构体中添加一个 topic。
|
||||
- list：[入参] 指向一个有效的 tmq_list_t 结构体指针，该结构体代表一个 TMQ 列表对象。
|
||||
- topic：[入参] topic 名称。
|
||||
- **返回值**：`0`：成功。`非0`：失败，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
- `void tmq_list_destroy(tmq_list_t *list)`
|
||||
- **接口说明**：用于销毁 tmq_list_t 结构体，tmq_list_new 的结果需要通过该接口销毁。
|
||||
- list：[入参] 指向一个有效的 tmq_list_t 结构体指针，该结构体代表一个 TMQ 列表对象。
|
||||
|
||||
- `int32_t tmq_list_get_size(const tmq_list_t *list)`
|
||||
- **接口说明**：用于获取 tmq_list_t 结构体中 topic 的个数。
|
||||
- list：[入参] 指向一个有效的 tmq_list_t 结构体指针，该结构体代表一个 TMQ 列表对象。
|
||||
- **返回值**：`>=0`：成功，返回 tmq_list_t 结构体中 topic 的个数。`-1`：失败，表示输入参数 list 为 NULL 。
|
||||
|
||||
- `char **tmq_list_to_c_array(const tmq_list_t *list)`
|
||||
- **接口说明**：用于将 tmq_list_t 结构体转换为 C 数组，数组每个元素为字符串指针。
|
||||
- list：[入参] 指向一个有效的 tmq_list_t 结构体指针，该结构体代表一个 TMQ 列表对象。
|
||||
- **返回值**：`非NULL`：成功，返回 c 数组, 每个元素是字符串指针，代表一个 topic 名称。`NULL`：失败，表示输入参数 list 为 NULL 。
|
||||
|
||||
- `tmq_t *tmq_consumer_new(tmq_conf_t *conf, char *errstr, int32_t errstrLen)`
|
||||
- **接口说明**：用于创建一个 tmq_t 结构体，用于消费数据，消费完数据后需调用 tmq_consumer_close 关闭消费者。
|
||||
- conf：[入参] 指向一个有效的 tmq_conf_t 结构体指针，该结构体代表一个 TMQ 配置对象。
|
||||
- errstr：[出参] 指向一个有效的字符缓冲区指针，用于接收创建过程中可能产生的错误信息。内存的申请/释放由调用者负责。
|
||||
- errstrLen：[入参] 指定 errstr 缓冲区的大小（以字节为单位）。
|
||||
- **返回值**：`非NULL`：成功，返回一个指向 tmq_t 结构体的指针，该结构体代表一个 TMQ 消费者对象。。`NULL`：失败，错误信息存储在参数 errstr 中 。
|
||||
|
||||
- `int32_t tmq_subscribe(tmq_t *tmq, const tmq_list_t *topic_list)`
|
||||
- **接口说明**：用于订阅 topic 列表，消费完数据后，需调用 tmq_subscribe 取消订阅。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- topic_list：[入参] 指向一个有效的 tmq_list_t 结构体指针，该结构体包含一个或多个主题名称。
|
||||
- **返回值**：`0`：成功。`非0`：失败，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
**功能说明**
|
||||
- tmq_list_new 接口用于创建一个 tmq_list_t 结构体，用于存储订阅的 topic。
|
||||
- tmq_list_append 接口用于向 tmq_list_t 结构体中添加一个 topic。
|
||||
- tmq_list_destroy 接口用于销毁 tmq_list_t 结构体，tmq_list_new 的结果需要通过该接口销毁。
|
||||
- tmq_list_get_size 接口用于获取 tmq_list_t 结构体中 topic 的个数。
|
||||
- tmq_list_to_c_array 接口用于将 tmq_list_t 结构体转换为 C 数组，数组每个元素为字符串指针。
|
||||
- `int32_t tmq_unsubscribe(tmq_t *tmq)`
|
||||
- **接口说明**：用于取消订阅的 topic 列表。需与 tmq_subscribe 配合使用。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- **返回值**：`0`：成功。`非0`：失败，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
**返回值**
|
||||
- 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 失败
|
||||
- `int32_t tmq_subscription(tmq_t *tmq, tmq_list_t **topic_list)`
|
||||
- **接口说明**：用于获取订阅的 topic 列表。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- topic_list：[出参] 指向一个 tmq_list_t 结构体指针的指针，用于接收当前订阅的主题列表。
|
||||
- **返回值**：`0`：成功。`非0`：失败，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
|
||||
- `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)`
|
||||
- `int32_t tmq_unsubscribe(tmq_t *tmq)`
|
||||
- `int32_t tmq_subscription(tmq_t *tmq, tmq_list_t **topic_list)`
|
||||
- `TAOS_RES *tmq_consumer_poll(tmq_t *tmq, int64_t timeout)`
|
||||
- `int32_t tmq_consumer_close(tmq_t *tmq)`
|
||||
|
||||
**功能说明**
|
||||
- tmq_consumer_new 接口用于创建一个 tmq_t 结构体，用于消费数据，消费完数据后需调用 tmq_consumer_close 关闭消费者。
|
||||
- tmq_subscribe 接口用于订阅 topic 列表，消费完数据后，需调用 tmq_subscribe 取消订阅。
|
||||
- tmq_unsubscribe 接口用于取消订阅的 topic 列表。需与 tmq_subscribe 配合使用。
|
||||
- tmq_subscription 接口用于获取订阅的 topic 列表。
|
||||
- tmq_consumer_poll 接口用于轮询消费数据，每一个消费者，只能单线程调用该接口。
|
||||
- tmq_consumer_close 接口用于关闭 tmq_t 结构体。需与 tmq_consumer_new 配合使用。
|
||||
- **接口说明**：用于轮询消费数据，每一个消费者，只能单线程调用该接口。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- timeout：[入参] 轮询的超时时间，单位为毫秒，负数表示默认超时1秒。
|
||||
- **返回值**：`非NULL`：成功，返回一个指向 TAOS_RES 结构体的指针，该结构体包含了接收到的消息。。`NULL`：失败，表示没有数据。TAOS_RES 结果和 taos_query 返回结果一致，可通过查询的各种接口获取 TAOS_RES 里的信息，比如 schema 等。
|
||||
|
||||
**参数说明**
|
||||
- conf: 参数用于配置消费参数
|
||||
- errstr: 错误信息存储在这个字符串中，需自定分配内存，释放内存由调用者负责
|
||||
- errstenLen: errstr 字符串的长度
|
||||
- tmq: tmq_consumer_new 函数返回的 tmq_t 结构体
|
||||
- topic_list: topic 列表
|
||||
- timeout: 超时时间，单位为毫秒，表示多久没数据的话自动返回 NULL，负数的话默认超时1秒
|
||||
- `int32_t tmq_consumer_close(tmq_t *tmq)`
|
||||
- **接口说明**：用于关闭 tmq_t 结构体。需与 tmq_consumer_new 配合使用。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- **返回值**：`0`：成功。`非0`：失败，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
**返回值**
|
||||
- tmq_consumer_new 返回 tmq_t 结构体，失败返回 NULL
|
||||
- tmq_subscribe 返回错误码，0 表示成功，非0表示失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息。
|
||||
- tmq_unsubscribe 返回错误码，0 表示成功，非0表示失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息。
|
||||
- tmq_subscription 返回错误码，0 表示成功，非0表示失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息。
|
||||
- tmq_consumer_poll 返回 TAOS_RES 结构体，NULL 表示没有数据，非 NULL 表示有数据，TAOS_RES 结果和 taos_query 返回结果一致，可通过查询的各种接口获取 TAOS_RES 里的信息，比如 schema 等。
|
||||
- tmq_consumer_close 返回错误码，0 表示成功，非0表示失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息。
|
||||
- `int32_t tmq_get_topic_assignment(tmq_t *tmq, const char *pTopicName, tmq_topic_assignment **assignment, int32_t *numOfAssignment)`
|
||||
- **接口说明**：返回当前 consumer 分配的 vgroup 的信息，每个 vgroup 的信息包括 vgId，wal 的最大最小 offset，以及当前消费到的 offset。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- pTopicName：[入参] 要查询分配信息的主题名称。
|
||||
- assignment：[出参] 指向一个 tmq_topic_assignment 结构体指针的指针，用于接收分配信息。数据大小为 numOfAssignment，需要通过 tmq_free_assignment 接口释放。
|
||||
- numOfAssignment：[出参] 指向一个整数指针，用于接收分配给该 consumer 有效的 vgroup 个数。
|
||||
- **返回值**：`0`：成功。`非0`：失败，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
- `void tmq_free_assignment(tmq_topic_assignment* pAssignment)`
|
||||
- **接口说明**：返回当前consumer分配的vgroup的信息，每个vgroup的信息包括vgId，wal的最大最小offset，以及当前消费到的offset。
|
||||
- pAssignment：[入参] 指向一个有效的 tmq_topic_assignment 结构体数组的指针，该数组包含了 vgroup 分配信息。
|
||||
|
||||
- `int32_t tmq_get_topic_assignment(tmq_t *tmq, const char *pTopicName, tmq_topic_assignment **assignment, int32_t *numOfAssignment)`
|
||||
- `void tmq_free_assignment(tmq_topic_assignment* pAssignment)`
|
||||
- `int64_t tmq_committed(tmq_t *tmq, const char *pTopicName, int32_t vgId)`
|
||||
- **接口说明**：获取 TMQ 消费者对象对特定 topic 和 vgroup 的已提交偏移量。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- pTopicName：[入参] 要查询已提交偏移量的主题名称。
|
||||
- assignment：[入参] vgroup 的 ID。
|
||||
- **返回值**：`>=0`：成功，返回一个 int64_t 类型的值，表示已提交的偏移量。`<0`：失败，返回值就是错误码，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
tmq_topic_assignment结构体定义如下：
|
||||
```c
|
||||
typedef struct tmq_topic_assignment {
|
||||
int32_t vgId;
|
||||
int64_t currentOffset;
|
||||
int64_t begin;
|
||||
int64_t end;
|
||||
} tmq_topic_assignment;
|
||||
```
|
||||
- `int32_t tmq_commit_sync(tmq_t *tmq, const TAOS_RES *msg)`
|
||||
- **接口说明**：同步提交 TMQ 消费者对象处理的消息偏移量。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- msg：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了已处理的消息。如果为 NULL，提交当前 consumer 所有消费的 vgroup 的当前进度。
|
||||
- **返回值**：`0`：成功，已经成功提交偏移量。`非0`：失败，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
**功能说明**
|
||||
- tmq_get_topic_assignment 接口返回当前consumer分配的vgroup的信息，每个vgroup的信息包括vgId，wal的最大最小offset，以及当前消费到的offset。
|
||||
- `void tmq_commit_async(tmq_t *tmq, const TAOS_RES *msg, tmq_commit_cb *cb, void *param)`
|
||||
- **接口说明**：异步提交 TMQ 消费者对象处理的消息偏移量。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- msg：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了已处理的消息。如果为 NULL，提交当前 consumer 所有消费的 vgroup 的当前进度。
|
||||
- cb：[入参] 一个回调函数指针，当提交完成时会被调用。
|
||||
- param：[入参] 一个用户自定义的参数，将在回调函数中传递给 cb。
|
||||
|
||||
**参数说明**
|
||||
- numOfAssignment ：分配给该consumer有效的vgroup个数。
|
||||
- assignment ：分配的信息，数据大小为numOfAssignment，需要通过 tmq_free_assignment 接口释放。
|
||||
- `int32_t tmq_commit_offset_sync(tmq_t *tmq, const char *pTopicName, int32_t vgId, int64_t offset)`
|
||||
- **接口说明**：同步提交 TMQ 消费者对象的特定主题和 vgroup 的偏移量。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- pTopicName：[入参] 要提交偏移量的主题名称。
|
||||
- **返回值**：`0`：成功，已经成功提交偏移量。`非0`：失败，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
**返回值**
|
||||
- 错误码，0成功，非0失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息。
|
||||
|
||||
|
||||
- `int64_t tmq_committed(tmq_t *tmq, const char *pTopicName, int32_t vgId)`
|
||||
|
||||
**功能说明**
|
||||
- 获取当前 consumer 在某个 topic 和 vgroup上的 commit 位置。
|
||||
|
||||
**返回值**
|
||||
- 当前commit的位置，-2147467247表示没有消费进度，其他小于0的值表示失败，错误码就是返回值
|
||||
|
||||
|
||||
- `int32_t tmq_commit_sync(tmq_t *tmq, const TAOS_RES *msg)`
|
||||
- `void tmq_commit_async(tmq_t *tmq, const TAOS_RES *msg, tmq_commit_cb *cb, void *param)`
|
||||
- `int32_t tmq_commit_offset_sync(tmq_t *tmq, const char *pTopicName, int32_t vgId, int64_t offset)`
|
||||
- `void tmq_commit_offset_async(tmq_t *tmq, const char *pTopicName, int32_t vgId, int64_t offset, tmq_commit_cb *cb, void *param)`
|
||||
|
||||
**功能说明**
|
||||
- `void tmq_commit_offset_async(tmq_t *tmq, const char *pTopicName, int32_t vgId, int64_t offset, tmq_commit_cb *cb, void *param)`
|
||||
- **接口说明**：异步提交 TMQ 消费者对象的特定主题和 vgroup 的偏移量。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- pTopicName：[入参] 要提交偏移量的主题名称。
|
||||
- vgId：[入参] 虚拟组 vgroup 的 ID。
|
||||
- offset：[入参] 要提交的偏移量。
|
||||
- cb：[入参] 一个回调函数指针，当提交完成时会被调用。
|
||||
- param：[入参] 一个用户自定义的参数，将在回调函数中传递给 cb。
|
||||
|
||||
**说明**
|
||||
- commit接口分为两种类型，每种类型有同步和异步接口：
|
||||
- 第一种类型：根据消息提交，提交消息里的进度，如果消息传NULL，提交当前consumer所有消费的vgroup的当前进度 : tmq_commit_sync/tmq_commit_async
|
||||
- 第二种类型：根据某个topic的某个vgroup的offset提交 : tmq_commit_offset_sync/tmq_commit_offset_async
|
||||
- 第一种类型：根据消息提交，提交消息里的进度，如果消息传 NULL，提交当前 consumer 所有消费的 vgroup 的当前进度 : tmq_commit_sync/tmq_commit_async
|
||||
- 第二种类型：根据某个 topic 的某个 vgroup 的 offset 提交 : tmq_commit_offset_sync/tmq_commit_offset_async
|
||||
|
||||
**参数说明**
|
||||
- msg：消费到的消息结构，如果msg传NULL，提交当前consumer所有消费的vgroup的当前进度
|
||||
|
||||
**返回值**
|
||||
- 错误码，0成功，非0失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息
|
||||
|
||||
|
||||
- `int64_t tmq_position(tmq_t *tmq, const char *pTopicName, int32_t vgId)`
|
||||
|
||||
**功能说明**
|
||||
- 获取当前消费位置，为消费到的数据位置的下一个位置
|
||||
|
||||
**返回值**
|
||||
- 消费位置，非0失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息
|
||||
|
||||
|
||||
- `int32_t tmq_offset_seek(tmq_t *tmq, const char *pTopicName, int32_t vgId, int64_t offset)`
|
||||
|
||||
**功能说明**
|
||||
- 设置 consumer 在某个topic的某个vgroup的 offset位置，开始消费
|
||||
|
||||
**返回值**
|
||||
- 错误码，0成功，非0失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息
|
||||
- `int64_t tmq_position(tmq_t *tmq, const char *pTopicName, int32_t vgId)`
|
||||
- **接口说明**：获取当前消费位置，即已消费到的数据位置的下一个位置.
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- pTopicName：[入参] 要查询当前位置的主题名称。
|
||||
- vgId：[入参] 虚拟组 vgroup 的 ID。
|
||||
- **返回值**：`>=0`：成功，返回一个 int64_t 类型的值，表示当前位置的偏移量。`<0`：失败，返回值就是错误码，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
- `int32_t tmq_offset_seek(tmq_t *tmq, const char *pTopicName, int32_t vgId, int64_t offset)`
|
||||
- **接口说明**：将 TMQ 消费者对象在某个特定 topic 和 vgroup 的偏移量设置到指定的位置。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- pTopicName：[入参] 要查询当前位置的主题名称。
|
||||
- vgId：[入参] 虚拟组 vgroup 的 ID。
|
||||
- offset：[入参] 虚拟组 vgroup 的 ID。
|
||||
- **返回值**：`0`：成功，`非0`：失败，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
- `int64_t tmq_get_vgroup_offset(TAOS_RES* res)`
|
||||
- **接口说明**：从 TMQ 消费者获取的消息结果中提取虚拟组（vgroup）的当前消费数据位置的偏移量。
|
||||
- res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
|
||||
- **返回值**：`>=0`：成功，返回一个 int64_t 类型的值，表示当前消费位置的偏移量。`<0`：失败，返回值就是错误码，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
- `int32_t tmq_get_vgroup_id(TAOS_RES *res)`
|
||||
- **接口说明**：从 TMQ 消费者获取的消息结果中提取所属虚拟组（vgroup）的 ID。
|
||||
- res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
|
||||
- **返回值**：`>=0`：成功，返回一个 int32_t 类型的值，表示虚拟组（vgroup）的 ID。`<0`：失败，返回值就是错误码，可调用函数 `char *tmq_err2str(int32_t code)` 获取更详细的错误信息。
|
||||
|
||||
**功能说明**
|
||||
- tmq_get_vgroup_offset 获取 poll 消费到的数据的起始offset
|
||||
- tmq_get_vgroup_id 获取 poll 消费到的数据的所属的vgrou id
|
||||
- `TAOS *tmq_get_connect(tmq_t *tmq)`
|
||||
- **接口说明**：从 TMQ 消费者对象中获取与 TDengine 数据库的连接句柄。
|
||||
- tmq：[入参] 指向一个有效的 tmq_t 结构体指针，该结构体代表一个 TMQ 消费者对象。
|
||||
- **返回值**：非NULL`：成功，返回一个 TAOS * 类型的指针，指向与 TDengine 数据库的连接句柄。`NULL`：失败，非法的输入参数。
|
||||
|
||||
**参数说明**
|
||||
- msg：消费到的消息结构
|
||||
|
||||
**返回值**
|
||||
- tmq_get_vgroup_offset 返回值为消费到的offset，非0失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息
|
||||
- tmq_get_vgroup_id 返回值为消费到的数据所属的vgrou id，非0失败，可通过 `char *tmq_err2str(int32_t code)` 函数获取错误信息
|
||||
|
||||
|
||||
- `TAOS *tmq_get_connect(tmq_t *tmq)`
|
||||
- `const char *tmq_get_table_name(TAOS_RES *res)`
|
||||
- `tmq_res_t tmq_get_res_type(TAOS_RES *res)`
|
||||
- `const char *tmq_get_topic_name(TAOS_RES *res)`
|
||||
- `const char *tmq_get_db_name(TAOS_RES *res)`
|
||||
- **接口说明**：从 TMQ 消费者获取的消息结果中获取所属的的表名。
|
||||
- res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
|
||||
- **返回值**：非NULL`：成功，返回一个 const char * 类型的指针，指向表名字符串。`NULL`：失败，非法的输入参数。
|
||||
|
||||
tmq_res_t 表示消费到的数据类型，定义如下：
|
||||
- `tmq_res_t tmq_get_res_type(TAOS_RES *res)`
|
||||
- **接口说明**：从 TMQ 消费者获取的消息结果中获取消息类型。
|
||||
- res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
|
||||
- **返回值**：返回一个 tmq_res_t 类型的枚举值，表示消息类型。
|
||||
- tmq_res_t 表示消费到的数据类型，定义如下：
|
||||
```
|
||||
typedef enum tmq_res_t {
|
||||
TMQ_RES_INVALID = -1, // invalid
|
||||
TMQ_RES_DATA = 1, // 数据
|
||||
TMQ_RES_TABLE_META = 2, // 元数据
|
||||
TMQ_RES_METADATA = 3 // 既有元数据又有数据，即自动建表
|
||||
TMQ_RES_INVALID = -1, // 无效
|
||||
TMQ_RES_DATA = 1, // 数据类型
|
||||
TMQ_RES_TABLE_META = 2, // 元数据类型
|
||||
TMQ_RES_METADATA = 3 // 既有元数据类型又有数据类型，即自动建表
|
||||
} tmq_res_t;
|
||||
```
|
||||
|
||||
**功能说明**
|
||||
- tmq_get_connect 创建consumer时，会自动建立链接保存在 tmq_t 结构体中，该接口用户获取 tmq_t 结构体中的链接信息，类似taos_connect
|
||||
- tmq_get_table_name 获取返回结果所属的的表名
|
||||
- tmq_get_res_type 获取返回结果的类型
|
||||
- tmq_get_topic_name 获取返回结果所属的topic名
|
||||
- tmq_get_db_name 获取返回结果所属的数据库名
|
||||
- `const char *tmq_get_topic_name(TAOS_RES *res)`
|
||||
- **接口说明**：从 TMQ 消费者获取的消息结果中获取所属的 topic 名称。
|
||||
- res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
|
||||
- **返回值**：非NULL`：成功，返回一个 const char * 类型的指针，指向 topic 名称字符串。`NULL`：失败，非法的输入参数。
|
||||
|
||||
**参数说明**
|
||||
- tmq：tmq_consumer_new 返回的消费者handle
|
||||
- res：tmq_consumer_poll 返回的消费到的消息
|
||||
|
||||
**返回值**
|
||||
- tmq_get_connect 返回值为tmq_t结构体中的链接连接，非 NULL 正常，NULL 失败
|
||||
- tmq_get_table_name 返回值为消费到的数据所属的表名，非 NULL 正常，NULL 失败
|
||||
- tmq_get_res_type 返回值为消费到的数据所属的类型，具体见上面 tmq_res_t 的注释说明
|
||||
- tmq_get_topic_name 返回值为消费到的数据所属的 topic 名，非 NULL 正常，NULL 失败
|
||||
- tmq_get_db_name 返回值为消费到的数据所属的数据库名，非 NULL 正常，NULL 失败
|
||||
- `const char *tmq_get_db_name(TAOS_RES *res)`
|
||||
- **接口说明**：从 TMQ 消费者获取的消息结果中获取所属的数据库名称。
|
||||
- res：[入参] 指向一个有效的 TAOS_RES 结构体指针，该结构体包含了从 TMQ 消费者轮询得到的消息。
|
||||
- **返回值**：非NULL`：成功，返回一个 const char * 类型的指针，指向数据库名称字符串。`NULL`：失败，非法的输入参数。
|
||||
Loading…
Reference in New Issue