The Connector section of the official website reconstructs the C language interface description

2024-08-02 09:32:05 +08:00 · 2024-08-02 09:32:05 +08:00 · d92554ff50
parent 779c46b85f
commit d92554ff50
6 changed files with 371 additions and 0 deletions
--- a/docs/examples/c/CCreateDBDemo.c
+++ b/docs/examples/c/CCreateDBDemo.c
@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2019 TAOS Data, Inc. <jhtao@taosdata.com>
+ *
+ * This program is free software: you can use, redistribute, and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3
+ * or later ("AGPL"), as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+// TAOS standard API example. The same syntax as MySQL, but only a subset
+// to compile: gcc -o CCreateDBDemo CCreateDBDemo.c -ltaos
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "taos.h"
+
+
+static int DemoCreateDB() {
+// ANCHOR: create_db_and_table
+  int         ret_code  = -1;
+  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;
+  }
+
+  // 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
+  taos_close(taos);
+  taos_cleanup();
+  return ret_code;
+// ANCHOR_END: create_db_and_table
+}
+
+int main(int argc, char *argv[]) {
+  return DemoCreateDB();
+}
--- a/docs/examples/c/CInsertDataDemo.c
+++ b/docs/examples/c/CInsertDataDemo.c
@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2019 TAOS Data, Inc. <jhtao@taosdata.com>
+ *
+ * This program is free software: you can use, redistribute, and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3
+ * or later ("AGPL"), as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+// TAOS standard API example. The same syntax as MySQL, but only a subset
+// to compile: gcc -o CInsertDataDemo CInsertDataDemo.c -ltaos
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "taos.h"
+
+static int DemoInsertData() {
+// ANCHOR: insert_data
+  int         ret_code  = -1;
+  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;
+  }
+
+  // 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
+  taos_close(taos);
+  taos_cleanup();
+  return ret_code;
+// ANCHOR_END: insert_data
+}
+
+int main(int argc, char *argv[]) {
+  return DemoInsertData();
+}
--- a/docs/examples/c/CQueryDataDemo.c
+++ b/docs/examples/c/CQueryDataDemo.c
@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2019 TAOS Data, Inc. <jhtao@taosdata.com>
+ *
+ * This program is free software: you can use, redistribute, and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3
+ * or later ("AGPL"), as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+// TAOS standard API example. The same syntax as MySQL, but only a subset
+// to compile: gcc -o CQueryDataDemo CQueryDataDemo.c -ltaos
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "taos.h"
+
+
+static int DemoQueryData() {
+// ANCHOR: query_data
+  int         ret_code  = -1;
+  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;
+  }
+
+  // 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
+  taos_close(taos);
+  taos_cleanup();
+  return ret_code;
+// ANCHOR_END: query_data
+}
+
+int main(int argc, char *argv[]) {
+  return DemoQueryData();
+}
--- a/docs/examples/c/CWithReqIdDemo.c
+++ b/docs/examples/c/CWithReqIdDemo.c
@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2019 TAOS Data, Inc. <jhtao@taosdata.com>
+ *
+ * This program is free software: you can use, redistribute, and/or modify
+ * it under the terms of the GNU Affero General Public License, version 3
+ * or later ("AGPL"), as published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+// TAOS standard API example. The same syntax as MySQL, but only a subset
+// to compile: gcc -o CWithReqIdDemo CWithReqIdDemo.c -ltaos
+
+#include <inttypes.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "taos.h"
+
+
+static int DemoWithReqId() {
+// ANCHOR: with_reqid
+  int         ret_code  = -1;
+  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;
+  }
+
+  // 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;
+  }
+  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;
+// ANCHOR_END: with_reqid
+}
+
+int main(int argc, char *argv[]) {
+  return DemoWithReqId();
+}
--- a/docs/zh/08-develop/01-connect/index.md
+++ b/docs/zh/08-develop/01-connect/index.md
@ -337,6 +337,34 @@ properties 中的配置参数如下：
    <TabItem label="R" value="r">
    </TabItem>
    <TabItem label="C" value="c">
+使用客户端驱动访问 TDengine 集群的基本过程为：建立连接、查询和写入、关闭连接、清除资源。
+
+下面为建立连接的示例代码，其中省略了查询和写入部分，展示了如何建立连接、关闭连接以及清除资源。
+
+```c
+  TAOS *taos = taos_connect("localhost:6030", "root", "taosdata", NULL, 0);
+  if (taos == NULL) {
+    printf("failed to connect to server, reason:%s\n", "null taos" /*taos_errstr(taos)*/);
+    exit(1);
+  }
+
+  /* put your code here for read and write */
+
+  taos_close(taos);
+  taos_cleanup();
+```
+
+在上面的示例代码中， `taos_connect()` 建立到客户端程序所在主机的 6030 端口的连接，`taos_close()`关闭当前连接，`taos_cleanup()`清除客户端驱动所申请和使用的资源。
+
+:::note
+
+- 如未特别说明，当 API 的返回值是整数时，_0_ 代表成功，其它是代表失败原因的错误码，当返回值是指针时， _NULL_ 表示失败。
+- 所有的错误码以及对应的原因描述在 `taoserror.h` 文件中。
+
+:::
+
+
+
    </TabItem>
    <TabItem label="PHP" value="php">
    </TabItem>
--- a/docs/zh/08-develop/02-sql.md
+++ b/docs/zh/08-develop/02-sql.md
@ -35,6 +35,10 @@ TDengine 对 SQL 语言提供了全面的支持，允许用户以熟悉的 SQL
 <TabItem label="R" value="r">
 </TabItem>
 <TabItem label="C" value="c">
+```c
+{{#include docs/examples/c/CCreateDBDemo.c:create_db_and_table}}
+```
+> **注意**：如果不使用 `USE power` 指定数据库，则后续对表的操作都需要增加数据库名称作为前缀，如 power.meters。
 </TabItem>
 <TabItem label="PHP" value="php">
 </TabItem>
@ -65,6 +69,12 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW
 <TabItem label="R" value="r">
 </TabItem>
 <TabItem label="C" value="c">
+```c
+{{#include docs/examples/c/CInsertDataDemo.c:insert_data}}
+```
+
+**Note**
+NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW + 1s 代表客户端当前时间往后加 1 秒，数字后面代表时间单位：a（毫秒），s（秒），m（分），h（小时），d（天），w（周），n（月），y（年）。
 </TabItem>
 <TabItem label="PHP" value="php">
 </TabItem>
@ -95,6 +105,9 @@ NOW 为系统内部函数，默认为客户端所在计算机当前时间。 NOW
 <TabItem label="R" value="r">
 </TabItem>
 <TabItem label="C" value="c">
+```c
+{{#include docs/examples/c/CQueryDataDemo.c:query_data}}
+```
 </TabItem>
 <TabItem label="PHP" value="php">
 </TabItem>
@ -133,6 +146,9 @@ reqId 可用于请求链路追踪，reqId 就像分布式系统中的 traceId
 <TabItem label="R" value="r">
 </TabItem>
 <TabItem label="C" value="c">
+```c
+{{#include docs/examples/c/CWithReqIdDemo.c:with_reqid}}
+```
 </TabItem>
 <TabItem label="PHP" value="php">
 </TabItem>