Crate geopackage_ffi

Expand description

A C ABI for the geopackage crate.

Rust code should use geopackage directly: it is safe and has a larger API. Every function here is unsafe extern "C".

The header, include/geopackage.h, is generated by cbindgen and checked in, so the documentation of each item below also appears beside its C declaration. cargo cinstall -p geopackage-ffi installs the header, a versioned library, and a pkg-config file named geopackage.

§Opening a file

Every function that can fail takes an optional gpkg_error_t *. On failure it receives a status code and a message. gpkg_error_clear frees the message and resets the code, so a program can reuse one error variable.

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

int main(void) {
    gpkg_error_t error = {GPKG_STATUS_OK, NULL};

    gpkg_t *gpkg = gpkg_open_read_only("places.gpkg", &error);
    if (!gpkg) {
        fprintf(stderr, "open failed (%d): %s\n", (int)error.code,
                error.message ? error.message : "(no message)");
        gpkg_error_clear(&error);
        return 1;
    }

    char *version = gpkg_version(gpkg, &error);
    if (version) {
        printf("GeoPackage %s\n", version);
        gpkg_string_free(version);
    }

    if (gpkg_close(gpkg, &error) != GPKG_STATUS_OK) {
        fprintf(stderr, "close failed: %s\n",
                error.message ? error.message : "(no message)");
        gpkg_error_clear(&error);
        return 1;
    }
    return 0;
}

§Examples

The examples directory contains five complete programs. CI compiles them against the committed header and runs them, so they stay in sync with the ABI.

smoke.c: Open a file, list its layers, read one as an Arrow stream, and check that closing fails while the stream is open
inspect.c: Open a file leniently and read-only, then check everything before writing: open warnings, layers and tile pyramids, extensions and their support levels, and validation findings
query.c: Open a layer with only the columns it needs, resolve its CRS, and read by bounding box, by bounding box and WHERE clause with a bound parameter, and by feature ID
roundtrip.c: Create a layer from another layer’s Arrow schema, and copy the rows in one transaction
tilepipe.c: Create a Web Mercator tile pyramid, fill it, and copy it tile by tile with a cursor

§Editing a file

A typical program opens an existing file, inspects it, appends to it, and closes it. Here the new rows come from rows_to_append, which stands in for any producer of the Arrow C Data Interface, such as another layer’s gpkg_layer_read_arrow.

#include <stdio.h>
#include <string.h>
#include "geopackage.h"

// The rows to append, from any Arrow C Data Interface producer.
extern void rows_to_append(struct ArrowArrayStream *out);

static int fail(const char *what, gpkg_error_t *error) {
    fprintf(stderr, "%s: code=%d message=%s\n", what, (int)error->code,
            error->message ? error->message : "(none)");
    gpkg_error_clear(error);
    return 1;
}

int main(void) {
    gpkg_error_t error = {GPKG_STATUS_OK, NULL};

    gpkg_t *gpkg = gpkg_open("places.gpkg", &error);   // read-write
    if (!gpkg) {
        return fail("gpkg_open", &error);
    }
    gpkg_layer_t *layer = gpkg_layer_open(gpkg, "points", &error);
    if (!layer) {
        return fail("gpkg_layer_open", &error);
    }

    uint64_t rows = 0;
    if (gpkg_layer_count(layer, &rows, &error) != GPKG_STATUS_OK) {
        return fail("gpkg_layer_count", &error);
    }
    printf("points: %llu rows\n", (unsigned long long)rows);

    // Another program may have written this file. Repair fixes a stale or
    // legacy index, and leaves a current or missing one alone.
    char *index_state = gpkg_layer_spatial_index_status(layer, &error);
    if (!index_state) {
        return fail("gpkg_layer_spatial_index_status", &error);
    }
    printf("spatial index: %s\n", index_state);
    gpkg_string_free(index_state);
    if (gpkg_layer_repair_spatial_index(layer, &error) != GPKG_STATUS_OK) {
        return fail("gpkg_layer_repair_spatial_index", &error);
    }

    struct ArrowArrayStream new_rows;
    memset(&new_rows, 0, sizeof(new_rows));
    rows_to_append(&new_rows);

    if (gpkg_begin(gpkg, &error) != GPKG_STATUS_OK) {
        return fail("gpkg_begin", &error);
    }
    uint64_t written = 0;
    if (gpkg_layer_write_arrow(layer, &new_rows, 0, &written, &error)
        != GPKG_STATUS_OK) {
        gpkg_rollback(gpkg, NULL);
        return fail("gpkg_layer_write_arrow", &error);
    }
    if (gpkg_commit(gpkg, &error) != GPKG_STATUS_OK) {
        return fail("gpkg_commit", &error);
    }
    printf("appended %llu rows\n", (unsigned long long)written);

    gpkg_layer_free(layer);   // children before the container
    if (gpkg_close(gpkg, &error) != GPKG_STATUS_OK) {
        return fail("gpkg_close", &error);
    }
    return 0;
}

Writes made through this library keep the spatial index up to date, so check the index once when a file arrives, not on every write.
There is no save function. gpkg_commit commits the transaction, and without gpkg_begin each write is committed when its call returns.
gpkg_layer_write_arrow only appends. To update or delete existing rows, use a gpkg_writer_t from gpkg_layer_writer; its changes are committed together by gpkg_writer_commit.

§Conventions

Strings are NUL-terminated UTF-8. Strings returned by this library belong to the caller, who frees them with gpkg_string_free. Strings passed in are borrowed only for the duration of the call.
Errors are reported through an optional gpkg_error_t *; pass NULL to ignore them. A filled-in error owns its message, so clear it before reusing the variable, or the first message leaks.
Failure is NULL from a function that returns a pointer, and a status other than GPKG_STATUS_OK from a function that returns Status. The status is a broad category to branch on; the message has the details.
Handles are opaque, and each is freed by exactly one function. Using a handle after freeing it is undefined behaviour.

Handle	Created by	Freed by
`gpkg_t`	`gpkg_open`, `gpkg_open_read_only`, `gpkg_create`	`gpkg_close`
`gpkg_layer_t`	`gpkg_layer_open`, `gpkg_attributes_open`, and their `_with_columns` variants	`gpkg_layer_free`
`gpkg_tiles_t`	`gpkg_tiles_open`, `gpkg_tiles_create`, `gpkg_tiles_create_web_mercator`	`gpkg_tiles_free`
`gpkg_tile_cursor_t`	`gpkg_tiles_cursor`, `gpkg_tiles_cursor_at`, `gpkg_tiles_cursor_in`	`gpkg_tile_cursor_free`
`gpkg_findings_t`	`gpkg_validate`	`gpkg_findings_free`
`gpkg_writer_t`	`gpkg_layer_writer`	`gpkg_writer_commit` (keeps changes) or `gpkg_writer_free` (discards them)

§Handle lifetimes

Layers, tiles handles, writers, tile cursors and Arrow streams all borrow the container they came from. While any of them exists, gpkg_close returns GPKG_STATUS_HANDLE_IN_USE and leaves the container open and usable, so free them first. A tile cursor counts separately, and can outlive the tiles handle it came from. gpkg_findings_t is the exception: it borrows nothing, never blocks a close, and remains readable afterwards.

gpkg_error_t error = {GPKG_STATUS_OK, NULL};
gpkg_t *gpkg = gpkg_open_read_only("places.gpkg", &error);
gpkg_layer_t *layer = gpkg_layer_open(gpkg, "points", &error);

struct ArrowArrayStream stream;
memset(&stream, 0, sizeof(stream));
gpkg_layer_read_arrow(layer, &stream, &error);

// Fails while either child is alive, and nothing is torn down.
if (gpkg_close(gpkg, &error) == GPKG_STATUS_HANDLE_IN_USE) {
    gpkg_error_clear(&error);
}

stream.release(&stream);
gpkg_layer_free(layer);
gpkg_close(gpkg, &error);  // now it succeeds

In Rust, the compiler enforces this rule: close takes self, and a live Layer borrows it. The handle module explains how the C API checks the same rule at runtime, and why that is sound.

§Modules

container: Open and close files, read the declared version and any lenient-open warnings, look up a spatial reference system (gpkg_srs), and manage transactions (gpkg_begin, gpkg_commit, gpkg_rollback, gpkg_in_transaction)
layer: Open feature and attribute layers by name, optionally limited to some columns; list feature layers; count rows
schema: A layer’s columns and types, geometry column, spatial reference system, extent and spatial index
extensions: The gpkg_extensions table, with this library’s support level for each row, so a program can fail before it writes rather than partway through
validate: Every check the library has, as findings with a severity and repair advice
stream: Read and write layers as Arrow record batches through the C Data Interface, optionally filtered by bounding box, WHERE clause, or both; create a layer from an Arrow schema
tiles: Create, list, read and iterate over tile pyramids. Payloads are the stored bytes, never decoded
writer: Insert, update and delete individual features, with geometry as WKB and values as gpkg_value_t
error, util: Status codes, the error out-parameter, and gpkg_string_free. gpkg_bytes_free is in tiles, the only module that returns owned buffers

Features are read only through Arrow. There is no row-by-row reader, because it would duplicate the Arrow path; to read a single row, filter on fid = ?1. Writing has both forms because they do different things: gpkg_layer_write_arrow appends in bulk, and a gpkg_writer_t changes existing rows.

Metadata, related tables and tiled gridded coverages aren’t available through the C API yet. They are ordinary tables, so a program that needs them can query them with SQLite directly.

§Threading

A container and every handle taken from it (layers, tiles handles, writers, tile cursors and Arrow streams) must be used from one thread at a time. They share the container’s SQLite connection, and rusqlite::Connection is Send but not Sync. The whole set may move to another thread together, but you must not use a child on one thread while its container, or another child of the same container, is in use on another. This includes freeing a child. A gpkg_findings_t is the exception: it borrows nothing from its container, so it can move to another thread on its own.

There is no internal locking. For concurrent access, open the file once per thread. Reading through separate connections is safe, and is how the library’s multithreaded Arrow reader works.

Re-exports§

pub use container::gpkg_begin;
pub use container::gpkg_close;
pub use container::gpkg_commit;
pub use container::gpkg_create;
pub use container::gpkg_in_transaction;
pub use container::gpkg_open;
pub use container::gpkg_open_read_only;
pub use container::gpkg_open_warning;
pub use container::gpkg_open_warning_count;
pub use container::gpkg_rollback;
pub use container::gpkg_srs;
pub use container::gpkg_t;
pub use container::gpkg_version;
pub use error::Status;
pub use error::gpkg_error_clear;
pub use error::gpkg_error_t;
pub use extensions::gpkg_extension_at;
pub use extensions::gpkg_extensions_count;
pub use layer::gpkg_attributes_open;
pub use layer::gpkg_attributes_open_with_columns;
pub use layer::gpkg_layer_count;
pub use layer::gpkg_layer_free;
pub use layer::gpkg_layer_name;
pub use layer::gpkg_layer_name_at;
pub use layer::gpkg_layer_names_count;
pub use layer::gpkg_layer_open;
pub use layer::gpkg_layer_open_with_columns;
pub use layer::gpkg_layer_t;
pub use schema::gpkg_layer_column_count;
pub use schema::gpkg_layer_column_is_primary_key;
pub use schema::gpkg_layer_column_name;
pub use schema::gpkg_layer_column_type;
pub use schema::gpkg_layer_create_spatial_index;
pub use schema::gpkg_layer_drop_spatial_index;
pub use schema::gpkg_layer_extent;
pub use schema::gpkg_layer_geometry_column;
pub use schema::gpkg_layer_geometry_type;
pub use schema::gpkg_layer_has_spatial_index;
pub use schema::gpkg_layer_kind;
pub use schema::gpkg_layer_repair_spatial_index;
pub use schema::gpkg_layer_spatial_index_status;
pub use schema::gpkg_layer_srs_id;
pub use stream::gpkg_add_epsg_srs;
pub use stream::gpkg_create_layer_from_arrow_schema;
pub use stream::gpkg_layer_read_arrow;
pub use stream::gpkg_layer_read_arrow_filtered;
pub use stream::gpkg_layer_read_arrow_in;
pub use stream::gpkg_layer_write_arrow;
pub use tiles::gpkg_bytes_free;
pub use tiles::gpkg_tile_cursor_free;
pub use tiles::gpkg_tile_cursor_next;
pub use tiles::gpkg_tile_cursor_t;
pub use tiles::gpkg_tiles_count;
pub use tiles::gpkg_tiles_count_at;
pub use tiles::gpkg_tiles_create;
pub use tiles::gpkg_tiles_create_web_mercator;
pub use tiles::gpkg_tiles_cursor;
pub use tiles::gpkg_tiles_cursor_at;
pub use tiles::gpkg_tiles_cursor_in;
pub use tiles::gpkg_tiles_delete;
pub use tiles::gpkg_tiles_extent;
pub use tiles::gpkg_tiles_free;
pub use tiles::gpkg_tiles_get;
pub use tiles::gpkg_tiles_get_into;
pub use tiles::gpkg_tiles_has;
pub use tiles::gpkg_tiles_matrix_at;
pub use tiles::gpkg_tiles_name;
pub use tiles::gpkg_tiles_name_at;
pub use tiles::gpkg_tiles_names_count;
pub use tiles::gpkg_tiles_open;
pub use tiles::gpkg_tiles_put;
pub use tiles::gpkg_tiles_t;
pub use tiles::gpkg_tiles_zoom_level_count;
pub use util::gpkg_string_free;
pub use validate::gpkg_finding_at;
pub use validate::gpkg_findings_count;
pub use validate::gpkg_findings_free;
pub use validate::gpkg_findings_t;
pub use validate::gpkg_validate;
pub use value::ValueKind;
pub use value::gpkg_blob_t;
pub use value::gpkg_date_t;
pub use value::gpkg_datetime_t;
pub use value::gpkg_value_payload;
pub use value::gpkg_value_t;
pub use writer::gpkg_layer_writer;
pub use writer::gpkg_writer_commit;
pub use writer::gpkg_writer_delete;
pub use writer::gpkg_writer_free;
pub use writer::gpkg_writer_insert;
pub use writer::gpkg_writer_t;
pub use writer::gpkg_writer_update;
pub use writer::gpkg_writer_update_column;

Modules§

container: Open, create and close a gpkg_t, and read what the file declares.
error: Status codes (gpkg_status) and the error out-parameter (gpkg_error_t).
extensions: The gpkg_extensions catalogue, and this library’s support for each entry.
handle: Handle representation, and the one place the crate erases a lifetime.
layer: gpkg_layer_t: a handle onto one layer of an open GeoPackage.
schema: Schema introspection and the spatial index, for gpkg_layer_t.
stream: Read and write layers through the Arrow C Data Interface.
tiles: gpkg_tiles_t: a handle onto one tile pyramid.
util: Helpers for passing strings across the C API.
validate: Run the library’s file checks from C with gpkg_validate.
value: gpkg_value_t: one cell of a row, passed by value.
writer: gpkg_writer_t: insert, update and delete features one row at a time.