开启打印流程

本文档描述集成 C SDK 的客户端（App）如何开启打印：调用时序、重试/超时语义、返回值含义与使用提示。

文档角色：App（集成 SDK 的客户端业务层）与 C SDK。

开启打印调用时序

sequenceDiagram
    autonumber
    participant App as App
    participant SDK as C SDK

    App->>SDK: ti_set_event_callback(callback, user_data)
    App->>SDK: ti_start_event_subscription()
    SDK-->>App: TI_OK
    Note over App,SDK: 返回成功不代表事件订阅已生效<br/>（订阅建立存在时间窗口）

    App->>SDK: ti_set_print_data(data, index, is_static)
    SDK-->>App: TI_OK
    Note over App: 返回 OK 仅表示上传已完成<br/>不表示打印数据已就绪

    loop START_PRINT 返回失败时每 1 秒重试，总超时 10 秒
        App->>SDK: ti_print_control(cli, "START_PRINT")
        alt 被打印服务拒绝（如打印数据不足）
            SDK-->>App: TI_ERR_SERVER
            Note over App: 等待 1 秒后重试
        else 被打印服务接受
            SDK-->>App: TI_OK
        end
    end

    Note over App: START_PRINT 返回 TI_OK 后，开始等待 print_started 事件，超时 10 秒

    alt 10 秒内收到 print_started（success=true）
        Note over App: 成功进入可喷印状态
    else 10 秒内收到 print_started（success=false）
        Note over App: 开启失败，事件 message 含失败原因
    else 10 秒内未收到 print_started
        Note over App: 等待开启结果超时
    end

重试与超时流程

flowchart TD
    A["注册并启动事件订阅"] --> B["set_print_data() 上传至少一份打印数据"]
    B --> C{"上传是否成功？"}
    C -->|"否"| C1["上传失败，流程结束"]
    C -->|"是"| D["set_print_data 返回 OK 不代表数据已就绪"]

    D --> E["开始 START_PRINT 重试计时（10 秒）"]
    E --> F["print_control(START_PRINT)"]
    F --> G{"是否返回 TI_OK？"}
    G -->|"否"| H{"重试总时间是否达到 10 秒？"}
    H -->|"否"| I["等待 1 秒"]
    I --> F
    H -->|"是"| J["开启打印失败（数据准备超时）"]

    G -->|"是"| K["等待 print_started 事件（超时 10 秒）"]
    K --> L{"等待结果"}
    L -->|"success=true"| M["成功进入可喷印状态"]
    L -->|"success=false"| N["开启失败（message 含原因）"]
    L -->|"10 秒内未收到"| O["等待开启结果超时"]

返回值与结果的当前含义

事件 JSON 形状

print_started 事件的 JSON 形状与解析规则见 C SDK 事件订阅。

已知问题与使用提示

1. ti_print_control() 的 key 仅支持大写形式（如 "START_PRINT"），小写会返回 TI_ERR_INVALID_ARG。
2. ti_set_print_data() 返回 TI_OK 时，打印数据可能仍在后台处理，不能据此判断至少一份数据已经就绪。
3. print_started 依赖事件订阅已经建立；没有有效订阅时，无法获得开启结果。
4. ti_start_event_subscription() 返回成功后，事件订阅不会立即生效——从"返回成功"到"可以收到事件"之间存在时间窗口。