C API implementation for GeoPackage I/O. More...

#include <openswmm/engine/openswmm_geopackage.h>
#include "GpkgUtils.hpp"
#include "GeoPackageSchema.hpp"
#include "GeoPackagePluginInfo.hpp"
#include <string>
#include <cstring>

Include dependency graph for openswmm_geopackage_impl.cpp:

Classes
struct	GpkgHandle

Functions
SWMM_ENGINE_API SWMM_Gpkg	swmm_gpkg_open (const char *path)
	Open an existing GeoPackage file.

SWMM_ENGINE_API void	swmm_gpkg_close (SWMM_Gpkg gpkg)
	Close the GeoPackage and free all resources.

SWMM_ENGINE_API const char *	swmm_gpkg_last_error (SWMM_Gpkg gpkg)
	Get the last error message.

SWMM_ENGINE_API int	swmm_gpkg_begin (SWMM_Gpkg gpkg)
	Begin a transaction for bulk operations.

SWMM_ENGINE_API int	swmm_gpkg_commit (SWMM_Gpkg gpkg)
	Commit the current transaction.

SWMM_ENGINE_API int	swmm_gpkg_rollback (SWMM_Gpkg gpkg)
	Roll back the current transaction.

SWMM_ENGINE_API int	swmm_gpkg_register (const char license_key, const char organization, const char contact_email, const char deployment_id)
	Register the GeoPackage plugin.

SWMM_ENGINE_API int	swmm_gpkg_is_registered (void)
	Check whether the GeoPackage plugin is registered.

SWMM_ENGINE_API int	swmm_gpkg_simulation_count (SWMM_Gpkg gpkg)
	Get the number of simulation runs in the GeoPackage.

SWMM_ENGINE_API int	swmm_gpkg_simulation_id (SWMM_Gpkg gpkg, int index, char *buf, int bufsz)
	Get the simulation_id at the given index.

SWMM_ENGINE_API int	swmm_gpkg_node_count (SWMM_Gpkg gpkg, const char *sim_id)

SWMM_ENGINE_API int	swmm_gpkg_link_count (SWMM_Gpkg gpkg, const char *sim_id)

SWMM_ENGINE_API int	swmm_gpkg_subcatch_count (SWMM_Gpkg gpkg, const char *sim_id)

SWMM_ENGINE_API int	swmm_gpkg_gage_count (SWMM_Gpkg gpkg, const char *sim_id)

SWMM_ENGINE_API int	swmm_gpkg_topology_edge_count (SWMM_Gpkg gpkg, const char *sim_id)

SWMM_ENGINE_API int	swmm_gpkg_variable_count (SWMM_Gpkg gpkg)

SWMM_ENGINE_API int	swmm_gpkg_result_ts_count (SWMM_Gpkg gpkg, const char simulation_id, const char object_type, const char object_id, const char variable_name)
	Get the number of result timeseries records for a query.

SWMM_ENGINE_API int	swmm_gpkg_read_result_ts (SWMM_Gpkg gpkg, const char simulation_id, const char object_type, const char object_id, const char variable_name, double times, double values, int max_count)
	Read a result timeseries for one object and variable.

SWMM_ENGINE_API int	swmm_gpkg_read_summary (SWMM_Gpkg gpkg, const char simulation_id, const char object_type, const char object_id, const char variable_name, double *value)
	Read a single summary statistic value.

SWMM_ENGINE_API int	swmm_gpkg_create_observed_series (SWMM_Gpkg gpkg, const char name, const char variable_name, const char object_type, const char object_id, const char source, const char units)
	Create an observed data series.

SWMM_ENGINE_API int	swmm_gpkg_write_observed_value (SWMM_Gpkg gpkg, int series_id, const char timestamp, double value, const char quality_flag)
	Write a single observed data point.

SWMM_ENGINE_API int	swmm_gpkg_write_observed_values (SWMM_Gpkg gpkg, int series_id, const char *timestamps, const double values, const char **quality_flags, int count)
	Bulk-write a vector of observed data points to a series.

SWMM_ENGINE_API int	swmm_gpkg_observed_series_count (SWMM_Gpkg gpkg)
	Get the number of observed series in the GeoPackage.

SWMM_ENGINE_API int	swmm_gpkg_observed_value_count (SWMM_Gpkg gpkg, int series_id)
	Get the number of values in an observed series.

SWMM_ENGINE_API int	swmm_gpkg_read_observed_values (SWMM_Gpkg gpkg, int series_id, char timestamps, int ts_buf_len, double values, int max_count)
	Read observed timeseries values into caller-supplied arrays.

SWMM_ENGINE_API int	swmm_gpkg_query_int (SWMM_Gpkg gpkg, const char *sql)
	Execute a read-only SQL query and get the first integer result.

SWMM_ENGINE_API int	swmm_gpkg_query_double (SWMM_Gpkg gpkg, const char sql, double result)
	Execute a read-only SQL query and get the first double result.

Detailed Description

C API implementation for GeoPackage I/O.

Model definitions and simulation results are read-only. Only observed/sensor timeseries data is writable through this API.

Function Documentation

◆ swmm_gpkg_begin()

SWMM_ENGINE_API int swmm_gpkg_begin ( SWMM_Gpkg gpkg )

Begin a transaction for bulk operations.

Wrapping multiple observed data inserts in a single transaction dramatically improves performance (SQLite commits per-statement by default, which is slow for bulk inserts).

Parameters

gpkg	GeoPackage handle.

Returns: SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_close()

SWMM_ENGINE_API void swmm_gpkg_close ( SWMM_Gpkg gpkg )

Close the GeoPackage and free all resources.

Rolls back any uncommitted transaction. NULL-safe.

Parameters

gpkg	GeoPackage handle.

◆ swmm_gpkg_commit()

SWMM_ENGINE_API int swmm_gpkg_commit ( SWMM_Gpkg gpkg )

Commit the current transaction.

Parameters

gpkg	GeoPackage handle.

Returns: SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_create_observed_series()

SWMM_ENGINE_API int swmm_gpkg_create_observed_series	(	SWMM_Gpkg	gpkg,
		const char *	name,
		const char *	variable_name,
		const char *	object_type,
		const char *	object_id,
		const char *	source,
		const char *	units
	)

Create an observed data series.

Associates the series with a model object for sim-vs-observed comparison. Pass NULL for object_type/object_id to create an unlinked series.

Parameters

gpkg	GeoPackage handle.
name	Unique series name (e.g., "USGS_01585200_flow").
variable_name	Variable being measured (e.g., "flow", "depth").
object_type	Model object type ("NODE", "LINK", "SUBCATCH"), or NULL.
object_id	Model object ID, or NULL.
source	Data source description (e.g., "USGS NWIS"), or NULL.
units	Measurement units (e.g., "CMS"), or NULL.

Returns: Series ID (>= 0) on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_gage_count()

SWMM_ENGINE_API int swmm_gpkg_gage_count	(	SWMM_Gpkg	gpkg,
		const char *	sim_id
	)

◆ swmm_gpkg_is_registered()

SWMM_ENGINE_API int swmm_gpkg_is_registered ( void )

Check whether the GeoPackage plugin is registered.

Returns: 1 if registered, 0 otherwise.

Here is the call graph for this function:

◆ swmm_gpkg_last_error()

SWMM_ENGINE_API const char * swmm_gpkg_last_error ( SWMM_Gpkg gpkg )

Get the last error message.

Parameters

gpkg	GeoPackage handle.

Returns: Null-terminated error message, or empty string if no error.

◆ swmm_gpkg_link_count()

SWMM_ENGINE_API int swmm_gpkg_link_count	(	SWMM_Gpkg	gpkg,
		const char *	sim_id
	)

◆ swmm_gpkg_node_count()

SWMM_ENGINE_API int swmm_gpkg_node_count	(	SWMM_Gpkg	gpkg,
		const char *	sim_id
	)

◆ swmm_gpkg_observed_series_count()

SWMM_ENGINE_API int swmm_gpkg_observed_series_count ( SWMM_Gpkg gpkg )

Get the number of observed series in the GeoPackage.

Parameters

gpkg	GeoPackage handle.

Returns: Series count (>= 0), or SWMM_GPKG_ERR on error.

◆ swmm_gpkg_observed_value_count()

SWMM_ENGINE_API int swmm_gpkg_observed_value_count	(	SWMM_Gpkg	gpkg,
		int	series_id
	)

Get the number of values in an observed series.

Parameters

gpkg	GeoPackage handle.
series_id	Series ID.

Returns: Value count (>= 0), or SWMM_GPKG_ERR on error.

Here is the call graph for this function:

◆ swmm_gpkg_open()

SWMM_ENGINE_API SWMM_Gpkg swmm_gpkg_open ( const char * path )

Open an existing GeoPackage file.

Opens the database in read-write mode. Model definitions and simulation results are read-only by convention — only the observed data tables are writable through this API.

Parameters

path	Path to the .gpkg file (must exist).

Returns: Opaque handle, or NULL on failure.

Here is the call graph for this function:

◆ swmm_gpkg_query_double()

SWMM_ENGINE_API int swmm_gpkg_query_double	(	SWMM_Gpkg	gpkg,
		const char *	sql,
		double *	result
	)

Execute a read-only SQL query and get the first double result.

Parameters

	gpkg	GeoPackage handle.
	sql	SELECT query string.
[out]	result	Pointer to receive the double result.

Returns: SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_query_int()

SWMM_ENGINE_API int swmm_gpkg_query_int	(	SWMM_Gpkg	gpkg,
		const char *	sql
	)

Execute a read-only SQL query and get the first integer result.

Parameters

gpkg	GeoPackage handle.
sql	SELECT query string.

Returns: Integer result, or SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_read_observed_values()

SWMM_ENGINE_API int swmm_gpkg_read_observed_values	(	SWMM_Gpkg	gpkg,
		int	series_id,
		char *	timestamps,
		int	ts_buf_len,
		double *	values,
		int	max_count
	)

Read observed timeseries values into caller-supplied arrays.

Parameters

	gpkg	GeoPackage handle.
	series_id	Series ID.
[out]	timestamps	Array to receive timestamp strings (each must be at least 32 chars). Pass NULL to skip timestamps.
	ts_buf_len	Length of each timestamp buffer (e.g., 32).
[out]	values	Array to receive values. Must hold max_count doubles.
	max_count	Maximum number of values to read.

Returns: Number of values read (>= 0), or SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_read_result_ts()

SWMM_ENGINE_API int swmm_gpkg_read_result_ts	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id,
		const char *	object_type,
		const char *	object_id,
		const char *	variable_name,
		double *	times,
		double *	values,
		int	max_count
	)

Read a result timeseries for one object and variable.

Fills the caller-supplied arrays with elapsed_time and value pairs, ordered by time. Returns the number of values actually read (may be less than max_count if fewer results exist).

Parameters

	gpkg	GeoPackage handle.
	simulation_id	Simulation run identifier.
	object_type	"NODE", "LINK", "SUBCATCH", or "SYSTEM".
	object_id	Object identifier (e.g., "J1").
	variable_name	Variable name (e.g., "depth", "flow").
[out]	times	Array to receive elapsed times (seconds). Must hold max_count doubles.
[out]	values	Array to receive result values. Must hold max_count doubles.
	max_count	Maximum number of values to read.

Returns: Number of values read (>= 0), or SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_read_summary()

SWMM_ENGINE_API int swmm_gpkg_read_summary	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id,
		const char *	object_type,
		const char *	object_id,
		const char *	variable_name,
		double *	value
	)

Read a single summary statistic value.

Parameters

	gpkg	GeoPackage handle.
	simulation_id	Simulation run identifier.
	object_type	"NODE", "LINK", or "SUBCATCH".
	object_id	Object identifier.
	variable_name	Variable name (e.g., "max_depth", "max_flow").
[out]	value	Pointer to receive the statistic value.

Returns: SWMM_GPKG_OK on success, SWMM_GPKG_ERR if not found.

Here is the call graph for this function:

◆ swmm_gpkg_register()

SWMM_ENGINE_API int swmm_gpkg_register	(	const char *	license_key,
		const char *	organization,
		const char *	contact_email,
		const char *	deployment_id
	)

Register the GeoPackage plugin.

Parameters

license_key	License key or activation token (may be NULL).
organization	Registering organization name (may be NULL).
contact_email	Contact email (may be NULL).
deployment_id	Deployment identifier (may be NULL).

Returns: 1 if registration succeeded, 0 otherwise.

Here is the call graph for this function:

◆ swmm_gpkg_result_ts_count()

SWMM_ENGINE_API int swmm_gpkg_result_ts_count	(	SWMM_Gpkg	gpkg,
		const char *	simulation_id,
		const char *	object_type,
		const char *	object_id,
		const char *	variable_name
	)

Get the number of result timeseries records for a query.

Use this to pre-allocate arrays before calling swmm_gpkg_read_result_ts().

Parameters

gpkg	GeoPackage handle.
simulation_id	Simulation run identifier.
object_type	"NODE", "LINK", "SUBCATCH", or "SYSTEM".
object_id	Object identifier.
variable_name	Variable name.

Returns: Record count (>= 0), or SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_rollback()

SWMM_ENGINE_API int swmm_gpkg_rollback ( SWMM_Gpkg gpkg )

Roll back the current transaction.

Parameters

gpkg	GeoPackage handle.

Returns: SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_simulation_count()

SWMM_ENGINE_API int swmm_gpkg_simulation_count ( SWMM_Gpkg gpkg )

Get the number of simulation runs in the GeoPackage.

Parameters

gpkg	GeoPackage handle.

Returns: Simulation count, or -1 on error.

◆ swmm_gpkg_simulation_id()

SWMM_ENGINE_API int swmm_gpkg_simulation_id	(	SWMM_Gpkg	gpkg,
		int	index,
		char *	buf,
		int	bufsz
	)

Get the simulation_id at the given index.

Parameters

gpkg	GeoPackage handle.
index	Zero-based index (ordered by creation time).
buf	Buffer to receive the null-terminated simulation_id.
bufsz	Size of the buffer.

Returns: SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_subcatch_count()

SWMM_ENGINE_API int swmm_gpkg_subcatch_count	(	SWMM_Gpkg	gpkg,
		const char *	sim_id
	)

◆ swmm_gpkg_topology_edge_count()

SWMM_ENGINE_API int swmm_gpkg_topology_edge_count	(	SWMM_Gpkg	gpkg,
		const char *	sim_id
	)

◆ swmm_gpkg_variable_count()

SWMM_ENGINE_API int swmm_gpkg_variable_count ( SWMM_Gpkg gpkg )

◆ swmm_gpkg_write_observed_value()

SWMM_ENGINE_API int swmm_gpkg_write_observed_value	(	SWMM_Gpkg	gpkg,
		int	series_id,
		const char *	timestamp,
		double	value,
		const char *	quality_flag
	)

Write a single observed data point.

Parameters

gpkg	GeoPackage handle.
series_id	Series ID from swmm_gpkg_create_observed_series().
timestamp	ISO 8601 timestamp (e.g., "2026-01-15T08:30:00Z").
value	Measured value.
quality_flag	Quality flag ("A", "P", "E"), or NULL.

Returns: SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

◆ swmm_gpkg_write_observed_values()

SWMM_ENGINE_API int swmm_gpkg_write_observed_values	(	SWMM_Gpkg	gpkg,
		int	series_id,
		const char **	timestamps,
		const double *	values,
		const char **	quality_flags,
		int	count
	)

Bulk-write a vector of observed data points to a series.

Inserts count timestamp/value pairs in a single prepared-statement loop. For best performance, wrap in a transaction:

swmm_gpkg_begin(gpkg);
swmm_gpkg_write_observed_values(gpkg, sid, times, vals, flags, 10000);
swmm_gpkg_commit(gpkg);

Parameters

gpkg	GeoPackage handle.
series_id	Series ID from swmm_gpkg_create_observed_series().
timestamps	Array of ISO 8601 timestamp strings (count elements).
values	Array of measured values (count elements).
quality_flags	Array of quality flag strings (count elements), or NULL to omit quality flags for all values.
count	Number of data points to write.

Returns: SWMM_GPKG_OK on success, SWMM_GPKG_ERR on failure.

Here is the call graph for this function:

Classes

Functions

Detailed Description

Function Documentation

◆ swmm_gpkg_begin()

◆ swmm_gpkg_close()

◆ swmm_gpkg_commit()

◆ swmm_gpkg_create_observed_series()

◆ swmm_gpkg_gage_count()

◆ swmm_gpkg_is_registered()

◆ swmm_gpkg_last_error()

◆ swmm_gpkg_link_count()

◆ swmm_gpkg_node_count()

◆ swmm_gpkg_observed_series_count()

◆ swmm_gpkg_observed_value_count()

◆ swmm_gpkg_open()

◆ swmm_gpkg_query_double()

◆ swmm_gpkg_query_int()

◆ swmm_gpkg_read_observed_values()

◆ swmm_gpkg_read_result_ts()

◆ swmm_gpkg_read_summary()

◆ swmm_gpkg_register()

◆ swmm_gpkg_result_ts_count()

◆ swmm_gpkg_rollback()

◆ swmm_gpkg_simulation_count()

◆ swmm_gpkg_simulation_id()

◆ swmm_gpkg_subcatch_count()

◆ swmm_gpkg_topology_edge_count()

◆ swmm_gpkg_variable_count()

◆ swmm_gpkg_write_observed_value()

◆ swmm_gpkg_write_observed_values()