Session: session-c interface

example/client-c-example/README.md

@@ -0,0 +1,68 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+
+# How to get a complete C client demo project (SessionC)
+
+Pure **C** examples for the IoTDB Session **C API** (`SessionC.h`): **tree model** (`tree_example`) and **table model** (`table_example`). Default connection: `127.0.0.1:6667`, user `root` / password `root` (edit the macros at the top of each `.c` file).
+
+## Get a project
+
+Using Maven to build this example project (requires **Boost**, same as the C++ client; on Windows see [`iotdb-client/client-cpp/README.md`](../../iotdb-client/client-cpp/README.md)):
+
+* `cd` the root path of the whole project
+* run  
+  `mvn package -DskipTests -P with-cpp -pl example/client-c-example -am`  
+  (use `mvn clean package ...` when no other process holds files under `iotdb-client/client-cpp/target`; on Windows add Boost paths, e.g.  
+  `-D"boost.include.dir=C:\local\boost_1_87_0" -D"boost.library.dir=C:\local\boost_1_87_0\lib64-msvc-14.2"`)
+* `cd example/client-c-example/target`
+
+After a successful build you should have:
+
+* Unpacked C++ client headers and libraries under `client/` and Thrift under `thrift/` (same layout as [client-cpp-example](../client-cpp-example/README.md))
+* CMake-generated binaries, for example on Windows MSVC:  
+  `Release/tree_example.exe`, `Release/table_example.exe`  
+  (exact path depends on the CMake generator)
+
+## Run
+
+Start IoTDB first, then:
+
+```text
+# Windows (example)
+Release\tree_example.exe
+Release\table_example.exe
+```
+
+On failure, the programs print to `stderr` and you can inspect `ts_get_last_error()`.
+
+## Source layout
+
+```
+example/client-c-example/
++-- README.md
++-- pom.xml
++-- src/
+|   +-- CMakeLists.txt
+|   +-- tree_example.c
+|   +-- table_example.c
+```
+
+The Maven build copies `src/*.c` and `src/CMakeLists.txt` into `target/` next to the unpacked `client/` and `thrift/` trees, then runs CMake to compile the two executables.

example/client-c-example/pom.xml

@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>org.apache.iotdb</groupId>
+        <artifactId>iotdb-examples</artifactId>
+        <version>2.0.7-SNAPSHOT</version>
+    </parent>
+    <artifactId>client-c-example</artifactId>
+    <name>IoTDB: Example: C Client (SessionC)</name>
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.iotdb</groupId>
+            <artifactId>client-cpp</artifactId>
+            <version>${project.version}</version>
+            <type>pom</type>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>com.coderplus.maven.plugins</groupId>
+                <artifactId>copy-rename-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>copy-c-sources-and-cmake</id>
+                        <goals>
+                            <goal>copy</goal>
+                        </goals>
+                        <configuration>
+                            <fileSets>
+                                <fileSet>
+                                    <sourceFile>${project.basedir}/src/tree_example.c</sourceFile>
+                                    <destinationFile>${project.build.directory}/tree_example.c</destinationFile>
+                                </fileSet>
+                                <fileSet>
+                                    <sourceFile>${project.basedir}/src/table_example.c</sourceFile>
+                                    <destinationFile>${project.build.directory}/table_example.c</destinationFile>
+                                </fileSet>
+                                <fileSet>
+                                    <sourceFile>${project.basedir}/src/CMakeLists.txt</sourceFile>
+                                    <destinationFile>${project.build.directory}/CMakeLists.txt</destinationFile>
+                                </fileSet>
+                            </fileSets>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-dependency-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>unpack-client</id>
+                        <goals>
+                            <goal>unpack</goal>
+                        </goals>
+                        <phase>generate-sources</phase>
+                        <configuration>
+                            <artifactItems>
+                                <artifactItem>
+                                    <groupId>org.apache.iotdb</groupId>
+                                    <artifactId>client-cpp</artifactId>
+                                    <version>${project.version}</version>
+                                    <type>zip</type>
+                                    <classifier>cpp-${os.classifier}</classifier>
+                                    <overWrite>true</overWrite>
+                                </artifactItem>
+                            </artifactItems>
+                            <outputDirectory>${project.build.directory}/client</outputDirectory>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>unpack-thrift</id>
+                        <goals>
+                            <goal>unpack</goal>
+                        </goals>
+                        <phase>generate-sources</phase>
+                        <configuration>
+                            <artifactItems>
+                                <artifactItem>
+                                    <groupId>org.apache.iotdb.tools</groupId>
+                                    <artifactId>iotdb-tools-thrift</artifactId>
+                                    <version>${iotdb-tools-thrift.version}</version>
+                                    <classifier>${os.classifier}</classifier>
+                                    <type>zip</type>
+                                    <overWrite>true</overWrite>
+                                    <outputDirectory>${project.build.directory}/thrift</outputDirectory>
+                                </artifactItem>
+                            </artifactItems>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+            <plugin>
+                <groupId>io.github.cmake-maven-plugin</groupId>
+                <artifactId>cmake-maven-plugin</artifactId>
+                <executions>
+                    <execution>
+                        <id>cmake-generate</id>
+                        <goals>
+                            <goal>generate</goal>
+                        </goals>
+                        <phase>compile</phase>
+                        <configuration>
+                            <generator>${cmake.generator}</generator>
+                            <sourcePath>${project.build.directory}</sourcePath>
+                            <projectDirectory>${project.build.directory}</projectDirectory>
+                            <options>
+                                <option>-DBOOST_INCLUDEDIR=${boost.include.dir}</option>
+                            </options>
+                        </configuration>
+                    </execution>
+                    <execution>
+                        <id>cmake-compile</id>
+                        <goals>
+                            <goal>compile</goal>
+                        </goals>
+                        <phase>compile</phase>
+                        <configuration>
+                            <config>${cmake.build.type}</config>
+                            <projectDirectory>${project.build.directory}</projectDirectory>
+                        </configuration>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+    </build>
+</project>

example/client-c-example/src/table_example.c

@@ -0,0 +1,152 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/*
+ * Table model: CREATE DATABASE/TABLE, insert rows via Tablet, SELECT, DROP DATABASE.
+ * Requires IoTDB table-SQL support. Edit HOST / PORT / credentials below.
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "SessionC.h"
+
+#define HOST "127.0.0.1"
+#define PORT 6667
+#define USER "root"
+#define PASS "root"
+
+#define DB_NAME "cdemo_db"
+#define TABLE_NAME "cdemo_t0"
+
+static void fail(const char* ctx, CTableSession* s) {
+    fprintf(stderr, "[table_example] %s failed: %s\n", ctx, ts_get_last_error());
+    if (s) {
+        ts_table_session_close(s);
+        ts_table_session_destroy(s);
+    }
+    exit(1);
+}
+
+int main(void) {
+    /* Last arg: default database name; empty string leaves it unset (we USE "cdemo_db" via SQL below). */
+    CTableSession* session = ts_table_session_new(HOST, PORT, USER, PASS, "");
+    if (!session) {
+        fprintf(stderr, "[table_example] ts_table_session_new returned NULL: %s\n", ts_get_last_error());
+        return 1;
+    }
+    if (ts_table_session_open(session) != TS_OK) {
+        fail("ts_table_session_open", session);
+    }
+
+    char sql[512];
+    snprintf(sql, sizeof(sql), "DROP DATABASE IF EXISTS %s", DB_NAME);
+    (void)ts_table_session_execute_non_query(session, sql);
+
+    snprintf(sql, sizeof(sql), "CREATE DATABASE %s", DB_NAME);
+    if (ts_table_session_execute_non_query(session, sql) != TS_OK) {
+        fail("CREATE DATABASE", session);
+    }
+
+    snprintf(sql, sizeof(sql), "USE \"%s\"", DB_NAME);
+    if (ts_table_session_execute_non_query(session, sql) != TS_OK) {
+        fail("USE DATABASE", session);
+    }
+
+    const char* ddl =
+        "CREATE TABLE " TABLE_NAME " ("
+        "tag1 string tag,"
+        "attr1 string attribute,"
+        "m1 double field)";
+    if (ts_table_session_execute_non_query(session, ddl) != TS_OK) {
+        fail("CREATE TABLE", session);
+    }
+
+    const char* columnNames[] = {"tag1", "attr1", "m1"};
+    TSDataType_C dataTypes[] = {TS_TYPE_STRING, TS_TYPE_STRING, TS_TYPE_DOUBLE};
+    TSColumnCategory_C colCategories[] = {TS_COL_TAG, TS_COL_ATTRIBUTE, TS_COL_FIELD};
+
+    CTablet* tablet = ts_tablet_new_with_category(TABLE_NAME, 3, columnNames, dataTypes, colCategories, 100);
+    if (!tablet) {
+        fail("ts_tablet_new_with_category", session);
+    }
+
+    int i;
+    for (i = 0; i < 5; i++) {
+        if (ts_tablet_add_timestamp(tablet, i, (int64_t)i) != TS_OK) {
+            ts_tablet_destroy(tablet);
+            fail("ts_tablet_add_timestamp", session);
+        }
+        if (ts_tablet_add_value_string(tablet, 0, i, "device_A") != TS_OK) {
+            ts_tablet_destroy(tablet);
+            fail("ts_tablet_add_value_string tag", session);
+        }
+        if (ts_tablet_add_value_string(tablet, 1, i, "attr_val") != TS_OK) {
+            ts_tablet_destroy(tablet);
+            fail("ts_tablet_add_value_string attr", session);
+        }
+        if (ts_tablet_add_value_double(tablet, 2, i, (double)i * 1.5) != TS_OK) {
+            ts_tablet_destroy(tablet);
+            fail("ts_tablet_add_value_double", session);
+        }
+    }
+    if (ts_tablet_set_row_count(tablet, 5) != TS_OK) {
+        ts_tablet_destroy(tablet);
+        fail("ts_tablet_set_row_count", session);
+    }
+
+    if (ts_table_session_insert(session, tablet) != TS_OK) {
+        ts_tablet_destroy(tablet);
+        fail("ts_table_session_insert", session);
+    }
+    ts_tablet_destroy(tablet);
+
+    CSessionDataSet* dataSet = NULL;
+    if (ts_table_session_execute_query(session, "SELECT * FROM " TABLE_NAME, &dataSet) != TS_OK) {
+        fail("ts_table_session_execute_query", session);
+    }
+    if (!dataSet) {
+        fprintf(stderr, "[table_example] dataSet is NULL\n");
+        ts_table_session_close(session);
+        ts_table_session_destroy(session);
+        return 1;
+    }
+    ts_dataset_set_fetch_size(dataSet, 1024);
+
+    int count = 0;
+    while (ts_dataset_has_next(dataSet)) {
+        CRowRecord* record = ts_dataset_next(dataSet);
+        if (!record) {
+            break;
+        }
+        printf("[table_example] row %d: time=%lld\n", count, (long long)ts_row_record_get_timestamp(record));
+        ts_row_record_destroy(record);
+        count++;
+    }
+    ts_dataset_destroy(dataSet);
+    printf("[table_example] SELECT returned %d row(s).\n", count);
+
+    snprintf(sql, sizeof(sql), "DROP DATABASE IF EXISTS %s", DB_NAME);
+    (void)ts_table_session_execute_non_query(session, sql);
+
+    ts_table_session_close(session);
+    ts_table_session_destroy(session);
+    return 0;
+}