C API

Overview

The C API provides a low-level interface to the GCode library using opaque handles and function pointers. This interface is suitable for direct C integration and for building bindings to other languages.

#include "gcode_api.h"

Types

GCodeHandle

typedef void* GCodeHandle;

Opaque handle to a GCode instance. Created by gcode_create() and destroyed by gcode_destroy().

GCodeResultHandle

typedef struct GCodeResult* GCodeResultHandle;

Opaque handle to a command result. Passed to the GCodeCommandResultCallback and used with the result accessor functions. This handle is only valid during the callback invocation.

Result Type Constants

#define GCODE_RESULT_NONE     0   /* No result data */
#define GCODE_RESULT_POSITION 1   /* Axis position data (e.g., M114) */

Result types identify the kind of data returned by a command. Check the type with gcode_result_get_type() to determine which keys are available.

Lifecycle Functions

gcode_create

GCodeHandle gcode_create(const char* license_key);

Creates a new GCode instance with the provided license key. Returns a handle on success, or NULL on failure (e.g., invalid or expired license key). Call gcode_get_last_error() to retrieve error details if creation fails.

Parameters:

license_key - Your license key string (provided by Galil)

gcode_destroy

void gcode_destroy(GCodeHandle handle);

Destroys a GCode instance and releases all associated resources. The handle is invalid after this call.

gcode_get_last_error

const char* gcode_get_last_error(void);

Returns a human-readable string describing the last error that occurred. Useful for debugging and logging.

Connection Functions

gcode_connect

int gcode_connect(GCodeHandle handle, const char* ip_address);

Connects to a Galil DMC controller at the specified IP address.

Parameters:

handle - GCode instance handle
ip_address - IP address of the controller (e.g., "192.168.1.100")

Returns:

GCODE_OK on success
GCODE_ERR_INVALID_HANDLE if handle is invalid
GCODE_ERR_ALREADY_CONNECTED if already connected
GCODE_ERR_CONNECTION_FAILED if connection fails

gcode_disconnect

void gcode_disconnect(GCodeHandle handle);

Disconnects from the controller. Safe to call even if not connected.

gcode_is_connected

int gcode_is_connected(GCodeHandle handle);

Returns 1 if connected to a controller, 0 otherwise.

Command Functions

gcode_add_command

int gcode_add_command(GCodeHandle handle, const char* gcode_string);

Adds a single G-code command to the execution queue.

Parameters:

handle - GCode instance handle
gcode_string - G-code command string (e.g., "G1 X10 Y20 F100")

Returns:

GCODE_OK on success
GCODE_ERR_NOT_CONNECTED if not connected
GCODE_ERR_PARSE_FAILED if the command cannot be parsed

gcode_add_file

int gcode_add_file(GCodeHandle handle, const char* file_path);

Loads and adds all G-code commands from a file to the execution queue.

Returns:

GCODE_OK on success
GCODE_ERR_NOT_CONNECTED if not connected
GCODE_ERR_FILE_NOT_FOUND if file does not exist
GCODE_ERR_FILE_READ_ERROR if file cannot be read
GCODE_ERR_PARSE_FAILED if a command cannot be parsed

gcode_get_queue_size

int gcode_get_queue_size(GCodeHandle handle);

Returns the number of commands currently in the queue. Returns -1 if handle is invalid.

gcode_clear_queue

int gcode_clear_queue(GCodeHandle handle);

Clears all pending commands from the queue. Does not affect the currently executing command.

Returns:

GCODE_OK on success
GCODE_ERR_INVALID_HANDLE if handle is invalid

Execution Functions

gcode_start

int gcode_start(GCodeHandle handle);

Starts or resumes processing the queued G-code commands on a background worker thread. This function is idempotent: calling it when already running is a no-op. If processing is paused (M0/M1 or error), it resumes from where it left off.

Returns:

GCODE_OK on success (including no-op when already running)
GCODE_ERR_NOT_CONNECTED if not connected

gcode_stop

int gcode_stop(GCodeHandle handle);

Stops processing G-code commands. The current command will complete before stopping. Call gcode_start() to resume processing.

Returns:

GCODE_OK on success

gcode_wait_for_queue_empty

int gcode_wait_for_queue_empty(GCodeHandle handle, int timeout_ms);

Blocks until all queued commands have been processed.

Parameters:

handle - GCode instance handle
timeout_ms - Maximum time to wait in milliseconds. Pass -1 for infinite wait.

Returns:

GCODE_OK when queue is empty
GCODE_ERR_TIMEOUT if timeout expires before queue is empty
GCODE_ERR_NOT_CONNECTED if not connected

Configuration Functions

Configuration functions must be called when the processor is not actively running. Calling these while processing is active will return GCODE_ERR_PROCESSING_ACTIVE.

gcode_configure_linear_axis

int gcode_configure_linear_axis(
    GCodeHandle handle,
    char gcode_axis,
    char dmc_axis,
    double counts_per_user_unit,
    double forward_limit
);

Configures the mapping between a G-code axis letter and a physical DMC controller axis.

Parameters:

gcode_axis - G-code axis letter ('X', 'Y', 'Z', etc.)
dmc_axis - DMC axis letter ('A' through 'H')
counts_per_user_unit - Encoder counts per user unit (inch or mm)
forward_limit - Maximum travel in user units. Use INFINITY for no limit.

Returns:

GCODE_OK on success
GCODE_ERR_PROCESSING_ACTIVE if called while processing
GCODE_ERR_INVALID_ARGUMENT if axis letters are invalid

gcode_configure_spindle

int gcode_configure_spindle(
    GCodeHandle handle,
    char dmc_axis,
    double counts_per_revolution
);

Configures the DMC axis that controls the spindle.

Parameters:

dmc_axis - DMC axis letter ('A' through 'H')
counts_per_revolution - Encoder counts per spindle revolution

Returns:

GCODE_OK on success
GCODE_ERR_PROCESSING_ACTIVE if called while processing

gcode_configure_extruder

int gcode_configure_extruder(
    GCodeHandle handle,
    char dmc_axis,
    double counts_per_user_unit
);

Configures the DMC axis that controls the extruder.

Parameters:

dmc_axis - DMC axis letter ('A' through 'H')
counts_per_user_unit - Conversion factor from user units to controller counts

Returns:

GCODE_OK on success
GCODE_ERR_PROCESSING_ACTIVE if called while processing

Callback Functions

See the Callbacks page for detailed documentation on setting up event callbacks.

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);

Result Functions

Result accessor functions allow you to read data returned by commands inside the GCodeCommandResultCallback. The GCodeResultHandle is only valid during the callback invocation.

gcode_result_get_type

int gcode_result_get_type(GCodeResultHandle result);

Returns the result type constant (e.g., GCODE_RESULT_NONE, GCODE_RESULT_POSITION). Returns GCODE_RESULT_NONE if result is NULL.

gcode_result_get_count

int gcode_result_get_count(GCodeResultHandle result);

Returns the number of key-value pairs stored in the result. Returns 0 if result is NULL.

gcode_result_get_double

int gcode_result_get_double(GCodeResultHandle result, const char* key, double* out);

Parameters:

result - Result handle from the callback
key - Key name (e.g., "X", "Y", "Z")
out - Pointer to receive the value

Returns:

GCODE_OK on success
GCODE_ERR_INVALID_ARGUMENT if any parameter is NULL
GCODE_ERR_NOT_FOUND if the key does not exist
GCODE_ERR_TYPE_MISMATCH if the key exists but is not a double

gcode_result_get_int

int gcode_result_get_int(GCodeResultHandle result, const char* key, int* out);

Parameters:

result - Result handle from the callback
key - Key name
out - Pointer to receive the value

Returns:

GCODE_OK on success
GCODE_ERR_INVALID_ARGUMENT if any parameter is NULL
GCODE_ERR_NOT_FOUND if the key does not exist
GCODE_ERR_TYPE_MISMATCH if the key exists but is not an int

gcode_result_get_string

int gcode_result_get_string(GCodeResultHandle result, const char* key, const char** out);

Parameters:

result - Result handle from the callback
key - Key name
out - Pointer to receive a C string pointer

Returns:

GCODE_OK on success
GCODE_ERR_INVALID_ARGUMENT if any parameter is NULL
GCODE_ERR_NOT_FOUND if the key does not exist
GCODE_ERR_TYPE_MISMATCH if the key exists but is not a string

Note: The returned string pointer uses thread-local storage and is valid until the next call to gcode_result_get_string() on the same thread. Copy the string if you need it longer.

Example

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

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

int main() {
    const char* key = getenv("GCODE_LICENSE_KEY");
    GCodeHandle h = gcode_create(key);
    if (!h) {
        printf("Failed to create: %s\n", gcode_get_last_error());
        return 1;
    }

    gcode_set_error_callback(h, on_error, NULL);

    if (gcode_connect(h, "192.168.1.100") != GCODE_OK) {
        printf("Connection failed: %s\n", gcode_get_last_error());
        gcode_destroy(h);
        return 1;
    }

    gcode_configure_linear_axis(h, 'X', 'A', 1000.0, 100.0);
    gcode_configure_linear_axis(h, 'Y', 'B', 1000.0, 100.0);

    gcode_add_command(h, "G1 X10 Y10 F100");
    gcode_add_command(h, "G1 X20 Y20");

    gcode_start(h);

    int result = gcode_wait_for_queue_empty(h, 30000);
    if (result == GCODE_ERR_TIMEOUT) {
        printf("Timeout waiting for commands\n");
    }

    gcode_disconnect(h);
    gcode_destroy(h);
    return 0;
}