C/C++ Connector
C/C++ 开发人员可以使用 TDengine 的客户端驱动,即 C/C++连接器 (以下都用 TDengine 客户端驱动表示),开发自己的应用来连接 TDengine 集群完成数据存储、查询以及其他功能。TDengine 客户端驱动的 API 类似于 MySQL 的 C API。应用程序使用时,需要包含 TDengine 头文件,里面列出了提供的 API 的函数原型;应用程序还要链接到所在平台上对应的动态库。
TDengine 的客户端驱动提供了 taosws 和 taos 两个动态库,分别支持 Websocket 连接和原生连接。 Websocket 连接和原生连接的区别是 Websocket 连接方式不要求客户端和服务端版本完全匹配,而原生连接要求,在性能上 Websocket 连接方式也接近于原生连接,一般我们推荐使用 Websocket 连接方式。
下面我们分开介绍两种连接方式的使用方法。
Websocket 连接方式
Websocket 连接方式需要使用 taosws.h 头文件和 taosws 动态库。
#include <taosws.h>
TDengine 服务端或客户端安装后,taosws.h
位于:
- Linux:
/usr/local/taos/include
- Windows:
C:\TDengine\include
- macOS:
/usr/local/include
TDengine 客户端驱动的动态库位于:
- Linux:
/usr/local/taos/driver/libtaosws.so
- Windows:
C:\TDengine\driver\taosws.dll
- macOS:
/usr/local/lib/libtaosws.dylib
支持的平台
请参考支持的平台列表
版本历史
TDengine 客户端版本 | 主要变化 | TDengine 版本 |
---|---|---|
3.3.3.0 | 首次发布,提供了 SQL执行,参数绑定,无模式写入和数据订阅等全面功能支持。 | 3.3.2.0及更高版本 |
错误码
在 C 接口的设计中,错误码采用整数类型表示,每个错误码都对应一个特定的错误状态。如未特别说明,当 API 的返回值是整数时,0 代表成功,其它是代表失败原因的错误码,当返回值是指针时, NULL 表示失败。
Websocket 连接方式单独的错误码在 taosws.h
中,
错误码 | 错误描述 | 可能的出错场景或者可能的原因 | 建议用户采取的措施 |
---|---|---|---|
0xE000 | DSN 错误 | DSN 不符合规范 | 检查 dsn 字符串是否符合规范 |
0xE001 | 内部错误 | 不确定 | 保留现场和日志,github上报issue |
0xE002 | 连接关闭 | 网络断开 | 请检查网络状况,查看 taosadapter 日志。 |
0xE003 | 发送超时 | 网络断开 | 请检查网络状况 |
0xE004 | 接收超时 | 慢查询,或者网络断开 | 排查 taosadapter 日志 |
其余错误码请参考同目录下 taoserror.h
文件,详细的原生连接错误码说明参考:错误码。
WebSocket 连接方式错误码只保留了原生连接错误码的后两个字节。
示例程序
本节展示了使用客户端驱动访问 TDengine 集群的常见访问方式的示例代码。
更多示例代码及下载请见 GitHub。
API 参考
以下分别介绍 TDengine 客户端驱动的 DSN、基础 API、同步查询 API、参数绑定 API、无模式写入 API 和 数据订阅订阅 API。
DSN
C/C++ Websocket 连接器通过 DSN 连接描述字符串来表示连接信息。 DSN 描述字符串基本结构如下:
<driver>[+<protocol>]://[[<username>:<password>@]<host>:<port>][/<database>][?<p1>=<v1>[&<p2>=<v2>]]
|------|------------|---|-----------|-----------|------|------|------------|-----------------------|
|driver| protocol | | username | password | host | port | database | params |
各部分意义见下表:
-
driver: 必须指定驱动名以便连接器选择何种方式创建连接,支持如下驱动名:
- taos: 默认驱动,支持 SQL 执行,参数绑定,无模式写入。
- tmq: 使用 TMQ 订阅数据。
-
protocol: 显示指定以何种方式建立连接,例如:
taos+ws://localhost:6041
指定以 Websocket 方式建立连接。- http/ws: 使用 Websocket 协议。
- https/wss: 在 Websocket 连接方式下显示启用 SSL/TLS 协议。
-
username/password: 用于创建连接的用户名及密码。
-
host/port: 指定创建连接的服务器及端口,当不指定服务器地址及端口时 Websocket 连接默认为
localhost:6041
。 -
database: 指定默认连接的数据库名,可选参数。
-
params:其他可选参数。
一个完整的 DSN 描述字符串示例如下:taos+ws://localhost:6041/test
, 表示使用 Websocket(ws
)方式通过 6041
端口连接服务器 localhost
,并指定默认数据库为 test
。
基础 API
基础 API 用于完成创建数据库连接等工作,为其它 API 的执行提供运行时环境。
-
char *ws_get_client_info()
- 接口说明:获取客户端版本信息。
- 返回值:返回客户端版本信息。
-
WS_TAOS *ws_connect(const char *dsn)
- 接口说明:创建数据库连接,初始化连接上下文。
- 参数说明:
- dsn:[入参] 连接信息,见上文 DSN 章节。
- 返回值:返回数据库连接,返回值为空表示失败。应用程序需要保存返回的参数,以便后续使用。
info同一进程可以根据不同的 dsn 连接多个 TDengine 集群
-
const char *ws_get_server_info(WS_TAOS *taos)