TiJet gRPC SDK 参考手册

版本 1.0.0 | 基于 proto 契约 tincore.TinCore 服务

架构总览

$$proto/tincore.proto ← 唯一契约源 │ ├── sdk/c/ libtijet_c.so ← C ABI（C/C++/嵌入式 → 解决 ABI 兼容） │ ├── include/tijet_core.h 19 个 C 函数，完整 Doxygen │ └── src/tijet_core.cpp gRPC C++ 内部实现 │ ├── sdk/python/tijet_grpc/ ← Python（原生 grpcio） │ └── client.py TinCore 类，18 个方法 │ ├── sdk/java/ ← Java（原生 grpc-java + Netty） │ └── com.tijet.grpc.TinCore TinCore 类，18 个方法 │ ├── sdk/csharp/TiJet.Grpc/ ← C#（原生 Grpc.Net.Client） │ └── TinCore.cs TinCore 类，18 个方法 │ └── sdk/cpp/ ← C++ 轻封装（header-only） └── include/tijet_core.h 基于 C ABI 的 RAII 封装$$

核心原则：每一层都使用该语言原生的 gRPC 库（不绕 C FFI），但 API 形状保持一致。

API 对照表

#	功能	C	Python	Java	C#
1	创建	`tijet_client_create()`	`TinCore()`	`new TinCore()`	`new TinCore()`
2	销毁	`tijet_client_destroy()`	`close()` / `with`	`close()` / try-with	`Dispose()` / `using`
3	连接	`tijet_client_connect(a)`	`connect(a)`	`connect(a)`	`Connect(a)`
4	断开	`tijet_client_disconnect()`	`disconnect()`	`disconnect()`	`Disconnect()`
5	连接状态	`tijet_client_is_connected()`	`is_connected`	`isConnected()`	`IsConnected`
6	网络配置	`tijet_client_network_config()`	`network_config()`	`networkConfig()`	`NetworkConfig()`
7	设置参数	`tijet_client_set_parameter()`	`set_parameter()`	`setParameter()`	`SetParameter()`
8	获取参数	`tijet_client_get_parameter()`	`get_parameter()`	`getParameter()`	`GetParameter()`
9	设置驱动板参数	`tijet_client_set_driver_board_parameter()`	`set_driver_board_parameter()`	`setDriverBoardParameter()`	`SetDriverBoardParameter()`
10	获取驱动板参数	`tijet_client_get_driver_board_parameter()`	`get_driver_board_parameter()`	`getDriverBoardParameter()`	`GetDriverBoardParameter()`
11	发送打印数据	`tijet_client_set_print_data()`	`set_print_data()`	`setPrintData()`	`SetPrintData()`
12	注册事件回调	`tijet_client_set_event_callback()`	`set_event_callback()`	`setEventCallback()`	`SetEventCallback()`
13	启动事件订阅	`tijet_client_start_event_subscription()`	`start_event_subscription()`	`startEventSubscription()`	`StartEventSubscription()`
14	停止事件订阅	`tijet_client_stop_event_subscription()`	`stop_event_subscription()`	`stopEventSubscription()`	`StopEventSubscription()`
15	注册日志回调	`tijet_client_set_log_callback()`	`set_log_callback()`	`setLogCallback()`	`SetLogCallback()`
16	启动日志订阅	`tijet_client_start_log_subscription()`	`start_log_subscription()`	`startLogSubscription()`	`StartLogSubscription()`
17	停止日志订阅	`tijet_client_stop_log_subscription()`	`stop_log_subscription()`	`stopLogSubscription()`	`StopLogSubscription()`
18	错误信息	`tijet_client_last_error()`	`last_error`	`getLastError()`	`LastError`
19	SDK 版本	`tijet_client_version()`	`version()`	`version()`	`Version`

语言惯用差异（不影响语义）

特性	C	Python	Java	C#
错误处理	`int` 返回码	异常 `TiJetError`	异常 `TiJetError`	异常 `TiJetError`
空参数	`NULL` / `""`	`None` / `""`	`null` / `""`	`null` / `""`
二进制数据	`const uint8_t*` + `size_t`	`bytes`	`byte[]`	`byte[]`
回调类型	函数指针 + `void*`	`Callable[[str], None]`	`Consumer<String>`	`Action<string>`
命名风格	`snake_case`	`snake_case`	`camelCase`	`PascalCase`

C SDK

快速开始

#include "tijet_core.h"

int main(void) {
    tijet_client_t *cli = tijet_client_create();

    if (tijet_client_connect(cli, NULL) != TIJET_OK) {
        fprintf(stderr, "连接失败: %s\n", tijet_client_last_error(cli));
        tijet_client_destroy(cli);
        return 1;
    }

    // 设置参数
    tijet_client_set_parameter(cli, "print_speed", "100");

    // 获取参数（两次调用模式）
    size_t size = 0;
    tijet_client_get_parameter(cli, "print_speed", NULL, &size);
    char *val = malloc(size);
    tijet_client_get_parameter(cli, "print_speed", val, &size);
    printf("print_speed = %s\n", val);
    free(val);

    // 发送打印数据
    uint8_t data[] = { 0x1B, 0x40 };
    char checksum[65] = {0};
    size_t csum_len = sizeof(checksum);
    tijet_client_set_print_data(cli, data, sizeof(data), 0, 0,
                                checksum, &csum_len);

    tijet_client_disconnect(cli);
    tijet_client_destroy(cli);
    return 0;
}

构建

cmake .. -DBUILD_C_SDK=ON
make tijet_c
# 产物: build/sdk/c/libtijet_c.so.1.0.0

头文件

#include "tijet_core.h" — 19 个 C 函数，零语言依赖（仅需 stddef.h + stdint.h）。

Doxygen 文档：doxygen Doxyfile → 含 @mainpage、@defgroup 分组、@code 示例。

Python SDK

安装

pip install grpcio protobuf
# 从源码:
#   PYTHONPATH=sdk/python python3 -c "from tijet_grpc import TinCore"

快速开始

from tijet_grpc import TinCore

with TinCore() as client:
    client.connect()
    client.set_parameter("print_speed", "100")
    speed = client.get_parameter("print_speed")
    print(f"print_speed = {speed}")

    checksum = client.set_print_data(b"\x1B\x40", index=0)
    print(f"SHA-256: {checksum}")

事件订阅

def on_event(event_json: str):
    print(f"事件: {event_json}")

client.set_event_callback(on_event)
client.start_event_subscription()
# 事件在后台线程异步回调...
client.stop_event_subscription()

异常层次

$$TiJetError (基类, code 属性) ├── InvalidArgumentError (code = -1) ├── NotConnectedError (code = -2) ├── TimeoutError (code = -3) ├── ServerError (code = -5) └── InternalError (code = -6)$$

类型别名

EventCallback = Callable[[str], None]
LogCallback   = Callable[[str], None]

Java SDK

依赖

// build.gradle
dependencies {
    implementation 'io.grpc:grpc-netty-shaded:1.82.0'
    implementation 'io.grpc:grpc-protobuf:1.82.0'
    implementation 'com.google.protobuf:protobuf-java:4.35.1'
    implementation 'com.google.protobuf:protobuf-java-util:4.35.1'
}

快速开始

import com.tijet.grpc.TinCore;

try (TinCore client = new TinCore()) {
    client.connect(null);  // 默认 UDS

    client.setParameter("print_speed", "100");
    String speed = client.getParameter("print_speed");
    System.out.println("print_speed = " + speed);

    byte[] data = { 0x1B, 0x40 };
    String checksum = client.setPrintData(data, 0, false);
    System.out.println("SHA-256: " + checksum);
}

事件订阅

client.setEventCallback(json -> {
    System.out.println("事件: " + json);
});
client.startEventSubscription();
// 事件在后台 daemon 线程异步回调...
client.stopEventSubscription();

异常层次

$$TiJetError (RuntimeException, int code) ├── InvalidArgumentError ├── NotConnectedError ├── TimeoutError ├── ServerError └── InternalError$$

构建

./gradlew build          # 需要 Gradle Wrapper
# 或直接生成 proto:
scripts/gen_proto.sh java

C# SDK

依赖

<!-- TiJet.Grpc.csproj -->
<PackageReference Include="Google.Protobuf" Version="3.28.0" />
<PackageReference Include="Grpc.Net.Client" Version="2.66.0" />
<PackageReference Include="Grpc.Tools" Version="2.66.0" />

快速开始

using TiJet.Grpc;

using var client = new TinCore();
client.Connect(null);  // 默认 UDS

client.SetParameter("print_speed", "100");
string speed = client.GetParameter("print_speed");
Console.WriteLine($"print_speed = {speed}");

byte[] data = { 0x1B, 0x40 };
string checksum = client.SetPrintData(data, index: 0);
Console.WriteLine($"SHA-256: {checksum}");

事件订阅

client.SetEventCallback(json => Console.WriteLine($"事件: {json}"));
client.StartEventSubscription();
// 事件在后台 Task 异步回调...
client.StopEventSubscription();

异常层次

$$TiJetError (Exception, int Code) ├── InvalidArgumentError ├── NotConnectedError ├── TimeoutError ├── ServerError └── InternalError$$

构建

dotnet build                                        # 需要 .NET 8 SDK
# 或先独立生成 proto:
scripts/gen_proto.sh csharp    # 需要 grpc_csharp_plugin

C++ 轻封装

使用

#include "tijet_core.h"  // C ABI 头文件

#include <string>
#include <memory>

// header-only RAII 封装（sdk/cpp/include/tijet_core.h 提供）
// 或直接调用 C API：
auto *cli = tijet_client_create();
tijet_client_connect(cli, nullptr);
tijet_client_set_parameter(cli, "key", "value");
tijet_client_destroy(cli);

Qt 集成示例

// Qt 调用 C API — 仅需 QString ↔ const char* 转换
bool MyWidget::connectToDevice() {
    handle_ = tijet_client_create();
    QByteArray addr = ui->addressEdit->text().toUtf8();
    return tijet_client_connect(handle_, addr.constData()) == TIJET_OK;
}

错误码

所有语言共享同一套错误码语义（C 返回 int，其他语言映射为异常）：

宏	值	含义
`TIJET_OK`	0	成功
`TIJET_ERR_INVALID_ARG`	-1	参数无效（NULL、越界、非法格式）
`TIJET_ERR_NOT_CONNECTED`	-2	尚未连接到服务器
`TIJET_ERR_TIMEOUT`	-3	操作超时
`TIJET_ERR_BUFFER_TOO_SMALL`	-4	缓冲区不足（仅 C API 使用）
`TIJET_ERR_SERVER`	-5	服务端返回错误
`TIJET_ERR_INTERNAL`	-6	内部错误（内存不足、线程错误）

构建与生成

代码生成

# 生成所有语言的 proto/gRPC 代码
./scripts/gen_proto.sh all

# 生成单个语言
./scripts/gen_proto.sh cpp
./scripts/gen_proto.sh python
./scripts/gen_proto.sh java
./scripts/gen_proto.sh csharp    # 需要 grpc_csharp_plugin

# 支持的平台:
#   cpp, csharp, python, go, java, rust, nodejs

C SDK 构建

cmake .. -DBUILD_C_SDK=ON
make tijet_c
# 产物: build/sdk/c/libtijet_c.so.1.0.0
# 导出: 19 个 tijet_client_* 符号，零 C++ 符号泄露

Java 构建

cd sdk/java
./gradlew build

C# 构建

cd sdk/csharp/TiJet.Grpc
dotnet build

当前状态

SDK	实现	测试	文档
C	✅ 完整 gRPC 对接	—	Doxygen (tijet_core.h)
Python	✅ 完整 gRPC 对接	—	docstring + 本文档
Java	✅ 完整源码	—	Javadoc + 本文档
C#	✅ 完整源码	—	XML doc + 本文档
C++ wrapper	✅ header-only 示范	—	—

待完成

WatchLogs RPC：proto 尚无 rpc WatchLogs 定义，所有 SDK 的日志订阅为存根
TLS 支持：当前使用明文连接（InsecureChannelCredentials）
单元测试：需要 mock gRPC 服务端或真实设备

TiJet gRPC SDK 参考手册

目录

架构总览

API 对照表

语言惯用差异（不影响语义）

C SDK

快速开始

构建

头文件

Python SDK

安装

快速开始

事件订阅

异常层次

类型别名

Java SDK

依赖

快速开始

事件订阅

异常层次

构建

C# SDK

依赖

快速开始

事件订阅

异常层次

构建

C++ 轻封装

使用

Qt 集成示例

错误码

构建与生成

代码生成

C SDK 构建

Java 构建

C# 构建

当前状态

待完成