Callbacks

Overview

The GCode API provides callbacks to notify your application of events during G-code execution. Callbacks allow you to monitor progress, handle errors, and respond to state changes without polling.

Note: Most callbacks run on a background worker thread. For GUI applications, do not update UI elements directly from these callbacks - use your framework's thread synchronization (e.g., Invoke, PostMessage, Qt::QueuedConnection).

Callback Types

GCodeErrorCallback

typedef void (*GCodeErrorCallback)(
    int error_code,
    const char* command,
    void* user_data
);

Parameters:

error_code - The error code (see Error Codes)
command - The G-code command that caused the error (may be NULL)
user_data - User-provided context pointer

GCodeCommandResultCallback

typedef void (*GCodeCommandResultCallback)(
    const char* command,
    GCodeResultHandle result,
    void* user_data
);

Parameters:

command - The G-code command string that produced the result
result - Opaque handle to the command's result data. Use the result accessor functions to read values. Valid only during this callback invocation.
user_data - User-provided context pointer

Result Payloads: Some commands (e.g., M114, M118) return data via the result handle. Check the result type with gcode_result_get_type(). See Result Functions for the full accessor API.

GCodeEventCallback

typedef void (*GCodeEventCallback)(
    void* user_data
);

Parameters:

user_data - User-provided context pointer

Available Callbacks

Callback	Type	When Invoked
OnError	GCodeErrorCallback	When an error occurs during command execution
OnCommandResult	GCodeCommandResultCallback	When a command produces result data (e.g., M114, M118)
OnStopped	GCodeEventCallback	When execution stops (M0/M1, error, or explicit Stop())
OnStarted	GCodeEventCallback	When execution starts or resumes

Setting Callbacks

C API

void gcode_set_error_callback(GCodeHandle handle, GCodeErrorCallback callback, void* user_data);
void gcode_set_command_result_callback(GCodeHandle handle, GCodeCommandResultCallback callback, void* user_data);
void gcode_set_stopped_callback(GCodeHandle handle, GCodeEventCallback callback, void* user_data);
void gcode_set_started_callback(GCodeHandle handle, GCodeEventCallback callback, void* user_data);

C++ API

void SetOnError(GCodeErrorCallback cb, void* data = nullptr);
void SetOnStopped(GCodeEventCallback cb, void* data = nullptr);
void SetOnStarted(GCodeEventCallback cb, void* data = nullptr);

Pass NULL (C) or nullptr (C++) as the callback to disable it.

Example

C — Basic Callbacks with Result Handling

#include "gcode_api.h"
#include <stdio.h>

void on_error(int code, const char* cmd, void* data) {
    printf("Error %d: %s\n", code, cmd ? cmd : "(no command)");
}

void on_result(const char* cmd, GCodeResultHandle result, void* data) {
    /* Check if this command returned position data (e.g., M114) */
    if (gcode_result_get_type(result) == GCODE_RESULT_POSITION) {
        printf("Position from %s:\n", cmd);
        double x, y, z;
        if (gcode_result_get_double(result, "X", &x) == GCODE_OK)
            printf("  X = %.3f\n", x);
        if (gcode_result_get_double(result, "Y", &y) == GCODE_OK)
            printf("  Y = %.3f\n", y);
        if (gcode_result_get_double(result, "Z", &z) == GCODE_OK)
            printf("  Z = %.3f\n", z);
    }
}

int main() {
    const char* key = getenv("GCODE_LICENSE_KEY");
    GCodeHandle h = gcode_create(key);

    gcode_set_error_callback(h, on_error, NULL);
    gcode_set_command_result_callback(h, on_result, NULL);

    /* ... connect, configure axes, add commands ... */

    gcode_add_command(h, "G1 X10 Y20 F500");
    gcode_add_command(h, "M114");  /* Reports current position via result */

    gcode_start(h);
    gcode_wait_for_queue_empty(h, 30000);

    gcode_destroy(h);
    return 0;
}