Start Print Workflow

This document describes how a client (App) integrating the C SDK starts printing: call sequence, retry/timeout semantics, return value meanings, and usage tips.

Document roles: App (client business layer integrating the SDK) and C SDK.

Start Print Call Sequence

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: Returning success does not mean the subscription is active<br/>(a time window exists before it takes effect)

    App->>SDK: ti_set_print_data(data, index, is_static)
    SDK-->>App: TI_OK
    Note over App: TI_OK only means the upload is complete<br/>it does not mean the print data is ready

    loop Retry every 1 second on START_PRINT failure, total timeout 10s
        App->>SDK: ti_print_control(cli, "START_PRINT")
        alt Rejected by the print service (e.g. insufficient print data)
            SDK-->>App: TI_ERR_SERVER
            Note over App: Wait 1 second before retrying
        else Accepted by the print service
            SDK-->>App: TI_OK
        end
    end

    Note over App: After START_PRINT returns TI_OK, wait for the print_started event, timeout 10s

    alt print_started received within 10s (success=true)
        Note over App: Successfully entered printable state
    else print_started received within 10s (success=false)
        Note over App: Start failed, event message contains the reason
    else No print_started within 10s
        Note over App: Timed out waiting for the start result
    end

Retry & Timeout Flow

flowchart TD
    A["Register and start event subscription"] --> B["set_print_data() uploads at least one print job"]
    B --> C{"Upload successful?"}
    C -->|"No"| C1["Upload failed, flow ends"]
    C -->|"Yes"| D["set_print_data returning OK does not mean data is ready"]

    D --> E["Start START_PRINT retry timer (10s)"]
    E --> F["print_control(START_PRINT)"]
    F --> G{"Returns TI_OK?"}
    G -->|"No"| H{"Total retry time reached 10s?"}
    H -->|"No"| I["Wait 1 second"]
    I --> F
    H -->|"Yes"| J["Start print failed (data preparation timeout)"]

    G -->|"Yes"| K["Wait for print_started event (timeout 10s)"]
    K --> L{"Result"}
    L -->|"success=true"| M["Successfully entered printable state"]
    L -->|"success=false"| N["Start failed (message contains reason)"]
    L -->|"Not received within 10s"| O["Timed out waiting for start result"]

Current Meaning of Return Values and Results

Event JSON Shape

The JSON shape and parsing rules of the print_started event are described in the C SDK event subscription.

Known Issues & Usage Tips

1. ti_print_control() keys are case-sensitive and only uppercase forms are accepted (e.g. "START_PRINT"); lowercase forms return TI_ERR_INVALID_ARG.
2. When ti_set_print_data() returns TI_OK, the print data may still be processed in the background; this cannot be used to determine that at least one data set is ready.
3. print_started depends on the event subscription being established; without a valid subscription, the start result cannot be obtained.
4. After ti_start_event_subscription() returns success, the subscription does not take effect immediately — there is a time window between “returned success” and “events can be received”.