OpenSWMM Engine — Model building and options C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_model.h:

This graph shows which files directly or indirectly include this file:

Typedefs
typedef enum SWMM_FilePathRole	SWMM_FilePathRole
	Identifies a single external-file slot on the model.

Enumerations
enum	SWMM_FilePathRole { SWMM_FILE_RAINFALL = 1 , SWMM_FILE_RUNOFF = 2 , SWMM_FILE_RDII = 3 , SWMM_FILE_INFLOWS = 4 , SWMM_FILE_OUTFLOWS = 5 , SWMM_FILE_HOTSTART_USE = 6 , SWMM_FILE_CLIMATE_TEMP = 7 , SWMM_FILE_HOTSTART_SAVE = 8 , SWMM_FILE_RAINGAGE_DATA = 9 , SWMM_FILE_TIMESERIES_DATA = 10 }
	Identifies a single external-file slot on the model. More...

Functions
SWMM_ENGINE_API SWMM_Engine	swmm_engine_new (void)
	Create an empty engine in BUILDING state (no .inp file required).

SWMM_ENGINE_API int	swmm_validate_model (SWMM_Engine engine)
	Validate model topology without changing state.

SWMM_ENGINE_API int	swmm_finalize_model (SWMM_Engine engine)
	Finalise a programmatically-built model.

SWMM_ENGINE_API int	swmm_model_write (SWMM_Engine engine, const char *new_inp_path)
	Write the current model state to a SWMM input (.inp) file.

SWMM_ENGINE_API int	swmm_model_write_with_plugin (SWMM_Engine engine, const char new_path, const char output_plugin_id)
	Write the current model state via a named writer plugin.

SWMM_ENGINE_API int	swmm_plugins_count (SWMM_Engine engine, int *count)
	Number of [PLUGINS] entries currently registered on the engine.

SWMM_ENGINE_API int	swmm_plugin_get (SWMM_Engine engine, int idx, char path_buf, int path_buf_sz, char args_buf, int args_buf_sz)
	Read one [PLUGINS] row by index.

SWMM_ENGINE_API int	swmm_plugin_set (SWMM_Engine engine, const char path_or_id, const char args)
	Add or replace a [PLUGINS] row keyed by `path_or_id`.

SWMM_ENGINE_API int	swmm_plugin_remove (SWMM_Engine engine, const char *path_or_id)
	Remove the [PLUGINS] row matching `path_or_id`.

SWMM_ENGINE_API int	swmm_files_get (SWMM_Engine engine, const char key, char buf, int buflen)
	Read one [FILES] field by key.

SWMM_ENGINE_API int	swmm_files_set (SWMM_Engine engine, const char key, const char value)
	Write one [FILES] field by key.

SWMM_ENGINE_API int	swmm_file_path_get (SWMM_Engine engine, SWMM_FilePathRole role, const char owner, char absolute_buf, int absolute_buflen, char *original_buf, int original_buflen)
	Read both strings from an external-file slot.

SWMM_ENGINE_API int	swmm_file_path_set (SWMM_Engine engine, SWMM_FilePathRole role, const char owner, const char new_path)
	Set the original token for an external-file slot; clears the cached absolute resolution.

SWMM_ENGINE_API int	swmm_title_get_count (SWMM_Engine engine, int *count)
	Get the number of title/note lines in the [TITLE] section.

SWMM_ENGINE_API int	swmm_title_get_line (SWMM_Engine engine, int index, char *buf, int buflen)
	Get a specific title/note line by index.

SWMM_ENGINE_API int	swmm_title_add_line (SWMM_Engine engine, const char *line)
	Add a new line to the end of the [TITLE] section.

SWMM_ENGINE_API int	swmm_title_set (SWMM_Engine engine, const char *text)
	Replace all title/note lines with a single block of text.

SWMM_ENGINE_API int	swmm_title_clear (SWMM_Engine engine)
	Remove all lines from the [TITLE] section.

SWMM_ENGINE_API int	swmm_options_get (SWMM_Engine engine, const char key, char buf, int buflen)
	Retrieve a standard OPTIONS value as a string.

SWMM_ENGINE_API int	swmm_options_set (SWMM_Engine engine, const char key, const char value)
	Set a standard OPTIONS value.

SWMM_ENGINE_API int	swmm_options_get_ext (SWMM_Engine engine, const char key, char buf, int buflen)
	Retrieve an extension OPTIONS value (keys unknown to standard SWMM).

SWMM_ENGINE_API int	swmm_options_set_ext (SWMM_Engine engine, const char key, const char value)
	Set (or create) an extension OPTIONS value.

SWMM_ENGINE_API int	swmm_get_crs (SWMM_Engine engine, char *buf, int buflen)
	Retrieve the CRS string (e.g., "EPSG:4326" or PROJ string).

SWMM_ENGINE_API int	swmm_options_get_start_date (SWMM_Engine engine, double *value)
	Retrieve the simulation start date/time as an OADate.

SWMM_ENGINE_API int	swmm_options_set_start_date (SWMM_Engine engine, double value)
	Set the simulation start date/time from an OADate.

SWMM_ENGINE_API int	swmm_options_get_end_date (SWMM_Engine engine, double *value)
	Retrieve the simulation end date/time as an OADate.

SWMM_ENGINE_API int	swmm_options_set_end_date (SWMM_Engine engine, double value)
	Set the simulation end date/time from an OADate.

SWMM_ENGINE_API int	swmm_options_get_report_start (SWMM_Engine engine, double *value)
	Retrieve the report start date/time as an OADate.

SWMM_ENGINE_API int	swmm_options_set_report_start (SWMM_Engine engine, double value)
	Set the report start date/time from an OADate.

SWMM_ENGINE_API int	swmm_userflag_get_bool (SWMM_Engine engine, const char name, int value)
	Get the value of a BOOLEAN user flag (schema-level).

SWMM_ENGINE_API int	swmm_userflag_get_int (SWMM_Engine engine, const char name, int value)
	Get the value of an INTEGER user flag.

SWMM_ENGINE_API int	swmm_userflag_get_real (SWMM_Engine engine, const char name, double value)
	Get the value of a REAL user flag.

SWMM_ENGINE_API int	swmm_userflag_set_bool (SWMM_Engine engine, const char *name, int value)
	Set a BOOLEAN user flag at runtime.

SWMM_ENGINE_API int	swmm_userflag_set_int (SWMM_Engine engine, const char *name, int value)
	Set an INTEGER user flag at runtime.

SWMM_ENGINE_API int	swmm_userflag_set_real (SWMM_Engine engine, const char *name, double value)
	Set a REAL user flag at runtime.

SWMM_ENGINE_API int	swmm_userflag_def_count (SWMM_Engine engine, int *count)
	Number of user-flag schema definitions.

SWMM_ENGINE_API int	swmm_userflag_def_get (SWMM_Engine engine, int index, char name_buf, int name_buflen, int type, char *desc_buf, int desc_buflen)
	Retrieve a user-flag schema definition by index (insertion order).

SWMM_ENGINE_API int	swmm_userflag_define (SWMM_Engine engine, const char name, int type, const char description)
	Define (or redefine) a user flag.

SWMM_ENGINE_API int	swmm_userflag_undefine (SWMM_Engine engine, const char *name)
	Remove a user-flag definition and all per-object values assigned to it.

SWMM_ENGINE_API int	swmm_userflag_value_get (SWMM_Engine engine, const char obj_type, const char obj_name, const char flag_name, char buf, int buflen, int *found)
	Read the flag value assigned to a specific object, as a string.

SWMM_ENGINE_API int	swmm_userflag_value_set (SWMM_Engine engine, const char obj_type, const char obj_name, const char flag_name, const char value)
	Assign a flag value to a specific object from a string.

SWMM_ENGINE_API int	swmm_userflag_value_clear (SWMM_Engine engine, const char obj_type, const char obj_name, const char *flag_name)
	Remove the flag value assigned to a specific object (mark unset).

Detailed Description

OpenSWMM Engine — Model building and options C API.

Covers:

Programmatic model construction (swmm_engine_new, object add)
Model finalisation and validation
Serialisation to .inp file
Standard and extension OPTIONS
CRS access
User flags

Note: Include this header independently or get it via openswmm_engine.h.

See also: openswmm_engine.h — lifecycle and error codes

Author: Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright: Copyright (c) 2026 Caleb Buahin. All rights reserved.

License\n MIT License

Typedef Documentation

◆ SWMM_FilePathRole

typedef enum SWMM_FilePathRole SWMM_FilePathRole

Identifies a single external-file slot on the model.

Vector slots (per-gage data, per-timeseries data, per-hot-start save entry) require an owner key to disambiguate; scalar slots ignore the owner argument.

Enumeration Type Documentation

◆ SWMM_FilePathRole

enum SWMM_FilePathRole

Identifies a single external-file slot on the model.

Vector slots (per-gage data, per-timeseries data, per-hot-start save entry) require an owner key to disambiguate; scalar slots ignore the owner argument.

Enumerator
SWMM_FILE_RAINFALL	ctx.files.rainfall_path
SWMM_FILE_RUNOFF	ctx.files.runoff_path
SWMM_FILE_RDII	ctx.files.rdii_path
SWMM_FILE_INFLOWS	ctx.files.inflows_path
SWMM_FILE_OUTFLOWS	ctx.files.outflows_path
SWMM_FILE_HOTSTART_USE	ctx.files.hotstart_use_path
SWMM_FILE_CLIMATE_TEMP	ctx.options.temp_file
SWMM_FILE_HOTSTART_SAVE	ctx.files.hotstart_saves[i], `owner` is decimal index "0".."N-1"
SWMM_FILE_RAINGAGE_DATA	ctx.gages.file_path[i], `owner` is the gage id
SWMM_FILE_TIMESERIES_DATA	ctx.tables.tables[i].file_path, `owner` is the series id

Function Documentation

◆ swmm_engine_new()

SWMM_ENGINE_API SWMM_Engine swmm_engine_new ( void )

Create an empty engine in BUILDING state (no .inp file required).

Use this instead of swmm_engine_create() + swmm_engine_open() when building a model entirely through the API. Objects may be added via swmm_node_add(), swmm_link_add(), etc. while in BUILDING state. Call swmm_finalize_model() to transition to INITIALIZED.

Returns: Opaque engine handle in SWMM_STATE_BUILDING, or NULL on failure.

◆ swmm_file_path_get()

SWMM_ENGINE_API int swmm_file_path_get	(	SWMM_Engine	engine,
		SWMM_FilePathRole	role,
		const char *	owner,
		char *	absolute_buf,
		int	absolute_buflen,
		char *	original_buf,
		int	original_buflen )

Read both strings from an external-file slot.

Parameters

engine	Engine handle.
role	Which slot to read.
owner	Owner key for vector slots; NULL/"" for scalar slots.
absolute_buf	[out] UTF-8 absolute path (NUL-terminated, truncated at `absolute_buflen - 1`). May be empty if the slot was set programmatically and never resolved.
absolute_buflen	Size of `absolute_buf` in bytes.
original_buf	[out] UTF-8 original token as authored. May be empty.
original_buflen	Size of `original_buf` in bytes.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM when role is unknown, when owner is required but NULL/missing in the model, or when buffer arguments are NULL.

◆ swmm_file_path_set()

SWMM_ENGINE_API int swmm_file_path_set	(	SWMM_Engine	engine,
		SWMM_FilePathRole	role,
		const char *	owner,
		const char *	new_path )

Set the original token for an external-file slot; clears the cached absolute resolution.

For vector slots, an owner that is not yet present in the model results in SWMM_ERR_BADPARAM — callers must add the owning gage / timeseries / hot-start save row first.

Pass an empty new_path to clear the slot.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM otherwise.

◆ swmm_files_get()

SWMM_ENGINE_API int swmm_files_get	(	SWMM_Engine	engine,
		const char *	key,
		char *	buf,
		int	buflen )

Read one [FILES] field by key.

Parameters

engine	Engine handle.
key	Field key (see header comment for recognised values).
buf	[out] UTF-8 result; NUL-terminated and truncated at `buflen` - 1 if too small.
buflen	Size of `buf` in bytes (including NUL).

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM when key is NULL, unknown, or buf args are invalid.

◆ swmm_files_set()

SWMM_ENGINE_API int swmm_files_set	(	SWMM_Engine	engine,
		const char *	key,
		const char *	value )

Write one [FILES] field by key.

Pass an empty value to clear a path slot. Pass an empty value to a *_MODE key to clear the mode (slot becomes inactive). The engine re-emits [FILES] on the next swmm_model_write* call.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM when key is NULL, unknown, or value is NULL.

◆ swmm_finalize_model()

SWMM_ENGINE_API int swmm_finalize_model ( SWMM_Engine engine )

Finalise a programmatically-built model.

Runs full topology validation, builds CSR connectivity arrays, allocates all SoA state arrays, and transitions the engine to SWMM_STATE_INITIALIZED. Equivalent to swmm_engine_open() + swmm_engine_initialize() for file-based models.

Parameters

engine Engine handle (must be in SWMM_STATE_BUILDING).

Returns: SWMM_OK on success; SWMM_ERR_* on failure.

Here is the call graph for this function:

◆ swmm_get_crs()

SWMM_ENGINE_API int swmm_get_crs	(	SWMM_Engine	engine,
		char *	buf,
		int	buflen )

Retrieve the CRS string (e.g., "EPSG:4326" or PROJ string).

Parameters

engine	Engine handle.
buf	Caller-allocated buffer.
buflen	Buffer size.

Returns: SWMM_OK; SWMM_ERR_CRS if no CRS was specified in [OPTIONS].

◆ swmm_model_write()

SWMM_ENGINE_API int swmm_model_write	(	SWMM_Engine	engine,
		const char *	new_inp_path )

Write the current model state to a SWMM input (.inp) file.

Serializes the entire SimulationContext back to SWMM .inp format. The output is a valid SWMM input file that can be re-opened. Includes all modified objects, user flags, CRS, plugin specs, and extension options.

Parameters

engine	Engine handle (SWMM_STATE_OPENED or later).
new_inp_path	Path where the new .inp file should be written.

Returns: SWMM_OK on success; SWMM_ERR_* on failure.

Here is the call graph for this function:

◆ swmm_model_write_with_plugin()

SWMM_ENGINE_API int swmm_model_write_with_plugin	(	SWMM_Engine	engine,
		const char *	new_path,
		const char *	output_plugin_id )

Write the current model state via a named writer plugin.

Routes the in-memory SimulationContext through the IInputPlugin::write() method of the plugin matching output_plugin_id. Lets a host (e.g., the GUI's Save As dialog) pick a non-.inp container — GeoPackage, HDF5, GeoJSON, …— at write time without touching the rest of the engine API.

Pass NULL or an empty string for output_plugin_id to use the built-in .inp writer (equivalent to swmm_model_write).

output_plugin_id is resolved via the engine's PluginFactory::find_component() — accepts a plugin id (e.g., "org.hydrocouple.openswmm.plugins.geopackage"), an id:version pair, or a shared-library path. The resolved plugin must advertise input capability (IPluginComponentInfo::has_input() returns true), since model write is delegated through IInputPlugin::write().

The chosen plugin is instantiated transiently for the call: create → initialize(args=empty) → write → finalize → delete. The engine's primary input plugin is not disturbed so the model can be re-saved later with a different writer.

Parameters

engine	Engine handle (SWMM_STATE_OPENED or later).
new_path	Path where the new model file should be written.
output_plugin_id	Writer plugin id, version pair, or library path; or NULL/empty for default `.inp` writer.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM when new_path is NULL or the plugin id does not resolve; SWMM_ERR_PLUGIN when the resolved plugin has no input capability or its initialize/write/finalize fails.

See also: swmm_model_write — built-in .inp writer (this function with NULL plugin id is functionally equivalent).

Here is the call graph for this function:

◆ swmm_options_get()

SWMM_ENGINE_API int swmm_options_get	(	SWMM_Engine	engine,
		const char *	key,
		char *	buf,
		int	buflen )

Retrieve a standard OPTIONS value as a string.

Parameters

engine	Engine handle.
key	Option name (e.g., "FLOW_UNITS", "ROUTING_MODEL", "LINK_OFFSETS", "CRS").
buf	Caller-allocated buffer for the value string.
buflen	Size of buf in bytes.

Returns: SWMM_OK if key found; SWMM_ERR_BADPARAM if not a standard key.

Encoding is symmetric with swmm_options_set: the returned string is one that swmm_options_set accepts for the same key. Enum keys return their canonical token (e.g. "CMS", "DYNWAVE", "ELEVATION"), never the underlying int.

Here is the call graph for this function:

◆ swmm_options_get_end_date()

SWMM_ENGINE_API int swmm_options_get_end_date	(	SWMM_Engine	engine,
		double *	value )

Retrieve the simulation end date/time as an OADate.

Parameters

engine	Engine handle.
value	[out] OADate (decimal days since 1899-12-30).

Returns: SWMM_OK; SWMM_ERR_BADPARAM on null engine/value.

◆ swmm_options_get_ext()

SWMM_ENGINE_API int swmm_options_get_ext	(	SWMM_Engine	engine,
		const char *	key,
		char *	buf,
		int	buflen )

Retrieve an extension OPTIONS value (keys unknown to standard SWMM).

Parameters

engine	Engine handle.
key	Extension option key.
buf	Caller-allocated buffer.
buflen	Buffer size.

Returns: SWMM_OK or SWMM_ERR_BADPARAM if key not found.

Here is the call graph for this function:

◆ swmm_options_get_report_start()

SWMM_ENGINE_API int swmm_options_get_report_start	(	SWMM_Engine	engine,
		double *	value )

Retrieve the report start date/time as an OADate.

Parameters

engine	Engine handle.
value	[out] OADate (decimal days since 1899-12-30).

Returns: SWMM_OK; SWMM_ERR_BADPARAM on null engine/value.

◆ swmm_options_get_start_date()

SWMM_ENGINE_API int swmm_options_get_start_date	(	SWMM_Engine	engine,
		double *	value )

Retrieve the simulation start date/time as an OADate.

Parameters

engine	Engine handle.
value	[out] OADate (decimal days since 1899-12-30).

Returns: SWMM_OK; SWMM_ERR_BADPARAM on null engine/value.

◆ swmm_options_set()

SWMM_ENGINE_API int swmm_options_set	(	SWMM_Engine	engine,
		const char *	key,
		const char *	value )

Set a standard OPTIONS value.

Parameters

engine	Engine handle (valid before swmm_engine_start()).
key	Option name.
value	New value string (parsed by the engine).

Returns: SWMM_OK or SWMM_ERR_BADPARAM.

Here is the call graph for this function:

◆ swmm_options_set_end_date()

SWMM_ENGINE_API int swmm_options_set_end_date	(	SWMM_Engine	engine,
		double	value )

Set the simulation end date/time from an OADate.

Parameters

engine	Engine handle.
value	OADate (decimal days since 1899-12-30).

Returns: SWMM_OK; SWMM_ERR_BADPARAM on null engine.

◆ swmm_options_set_ext()

SWMM_ENGINE_API int swmm_options_set_ext	(	SWMM_Engine	engine,
		const char *	key,
		const char *	value )

Set (or create) an extension OPTIONS value.

Parameters

engine	Engine handle.
key	Extension option key.
value	New value string.

Returns: SWMM_OK or error code.

Here is the call graph for this function:

◆ swmm_options_set_report_start()

SWMM_ENGINE_API int swmm_options_set_report_start	(	SWMM_Engine	engine,
		double	value )

Set the report start date/time from an OADate.

Parameters

engine	Engine handle.
value	OADate (decimal days since 1899-12-30).

Returns: SWMM_OK; SWMM_ERR_BADPARAM on null engine.

◆ swmm_options_set_start_date()

SWMM_ENGINE_API int swmm_options_set_start_date	(	SWMM_Engine	engine,
		double	value )

Set the simulation start date/time from an OADate.

Parameters

engine	Engine handle.
value	OADate (decimal days since 1899-12-30).

Returns: SWMM_OK; SWMM_ERR_BADPARAM on null engine.

◆ swmm_plugin_get()

SWMM_ENGINE_API int swmm_plugin_get	(	SWMM_Engine	engine,
		int	idx,
		char *	path_buf,
		int	path_buf_sz,
		char *	args_buf,
		int	args_buf_sz )

Read one [PLUGINS] row by index.

Either output buffer may be NULL (caller doesn't want that field). When non-NULL, the buffer is NUL-terminated and truncated at path_buf_sz - 1 / args_buf_sz - 1 if too small (no error returned). The args string is reconstructed by joining the row's init_args vector with single spaces.

Parameters

engine	Engine handle.
idx	Index in [0, count).
path_buf	[out] UTF-8 plugin path / id; may be NULL.
path_buf_sz	Size of path_buf in bytes (incl. NUL).
args_buf	[out] UTF-8 space-joined args; may be NULL.
args_buf_sz	Size of args_buf in bytes (incl. NUL).

Returns: SWMM_OK on success; SWMM_ERR_BADINDEX when idx is out of range.

◆ swmm_plugin_remove()

SWMM_ENGINE_API int swmm_plugin_remove	(	SWMM_Engine	engine,
		const char *	path_or_id )

Remove the [PLUGINS] row matching path_or_id.

Idempotent: returns SWMM_OK even when no row matches.

Parameters

engine	Engine handle.
path_or_id	Library path, plugin id, or `id:version` string.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM when path_or_id is NULL.

◆ swmm_plugin_set()

SWMM_ENGINE_API int swmm_plugin_set	(	SWMM_Engine	engine,
		const char *	path_or_id,
		const char *	args )

Add or replace a [PLUGINS] row keyed by path_or_id.

If a row with the same path_or_id exists, its args are replaced. Otherwise a new row is appended. The engine re-serialises the [PLUGINS] section on the next swmm_model_write* call.

Parameters

engine	Engine handle.
path_or_id	Library path, plugin id, or `id:version` string.
args	Space-separated argument tokens; may be NULL or empty for "no arguments".

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM when path_or_id is NULL or empty.

◆ swmm_plugins_count()

SWMM_ENGINE_API int swmm_plugins_count	(	SWMM_Engine	engine,
		int *	count )

Number of [PLUGINS] entries currently registered on the engine.

Parameters

count [out] Number of entries. Always set on SWMM_OK return.

◆ swmm_title_add_line()

SWMM_ENGINE_API int swmm_title_add_line	(	SWMM_Engine	engine,
		const char *	line )

Add a new line to the end of the [TITLE] section.

Parameters

engine	Engine handle.
line	Null-terminated string to append.

Returns: SWMM_OK on success.

◆ swmm_title_clear()

SWMM_ENGINE_API int swmm_title_clear ( SWMM_Engine engine )

Remove all lines from the [TITLE] section.

Parameters

engine Engine handle.

Returns: SWMM_OK on success.

◆ swmm_title_get_count()

SWMM_ENGINE_API int swmm_title_get_count	(	SWMM_Engine	engine,
		int *	count )

Get the number of title/note lines in the [TITLE] section.

Parameters

engine	Engine handle.
count	[out] Number of title lines.

Returns: SWMM_OK on success.

◆ swmm_title_get_line()

SWMM_ENGINE_API int swmm_title_get_line	(	SWMM_Engine	engine,
		int	index,
		char *	buf,
		int	buflen )

Get a specific title/note line by index.

Parameters

engine	Engine handle.
index	Zero-based line index.
buf	Caller-allocated buffer for the line text.
buflen	Size of buf in bytes.

Returns: SWMM_OK on success; SWMM_ERR_BADPARAM if index out of range.

◆ swmm_title_set()

SWMM_ENGINE_API int swmm_title_set	(	SWMM_Engine	engine,
		const char *	text )

Replace all title/note lines with a single block of text.

The text is split on newline characters ('\n') to form individual title lines. Any existing title lines are cleared.

Parameters

engine	Engine handle.
text	Null-terminated text (may contain '\n' separators).

Returns: SWMM_OK on success.

◆ swmm_userflag_def_count()

SWMM_ENGINE_API int swmm_userflag_def_count	(	SWMM_Engine	engine,
		int *	count )

Number of user-flag schema definitions.

Parameters

engine	Engine handle.
count	[out] Definition count.

Returns: SWMM_OK; SWMM_ERR_BADPARAM on null count.

◆ swmm_userflag_def_get()

SWMM_ENGINE_API int swmm_userflag_def_get	(	SWMM_Engine	engine,
		int	index,
		char *	name_buf,
		int	name_buflen,
		int *	type,
		char *	desc_buf,
		int	desc_buflen )

Retrieve a user-flag schema definition by index (insertion order).

Parameters

engine	Engine handle.
index	Zero-based definition index.
name_buf	[out] Flag name (NUL-terminated, truncated to fit). May be NULL.
name_buflen	Size of name_buf in bytes.
type	[out] Flag type (0=BOOLEAN, 1=INTEGER, 2=REAL, 3=STRING). May be NULL.
desc_buf	[out] Description (empty string if none). May be NULL.
desc_buflen	Size of desc_buf in bytes.

Returns: SWMM_OK; SWMM_ERR_BADINDEX if index out of range.

◆ swmm_userflag_define()

SWMM_ENGINE_API int swmm_userflag_define	(	SWMM_Engine	engine,
		const char *	name,
		int	type,
		const char *	description )

Define (or redefine) a user flag.

Parameters

engine	Engine handle.
name	Flag name (stored uppercase).
type	Flag type (0=BOOLEAN, 1=INTEGER, 2=REAL, 3=STRING).
description	Optional description (may be NULL or empty).

Returns: SWMM_OK; SWMM_ERR_BADPARAM on null/empty name or invalid type.

Redefining an existing name overwrites its definition; previously assigned per-object values are kept as-is.

◆ swmm_userflag_get_bool()

SWMM_ENGINE_API int swmm_userflag_get_bool	(	SWMM_Engine	engine,
		const char *	name,
		int *	value )

Get the value of a BOOLEAN user flag (schema-level).

Parameters

engine	Engine handle.
name	Flag name (as defined in [USER_FLAGS]).
value	[out] 1 = YES/TRUE, 0 = NO/FALSE.

Returns: SWMM_OK; SWMM_ERR_BADPARAM if flag not found or wrong type.

◆ swmm_userflag_get_int()

SWMM_ENGINE_API int swmm_userflag_get_int	(	SWMM_Engine	engine,
		const char *	name,
		int *	value )

Get the value of an INTEGER user flag.

Parameters

engine	Engine handle.
name	Flag name.
value	[out] Integer value.

Returns: SWMM_OK; SWMM_ERR_BADPARAM if not found or wrong type.

◆ swmm_userflag_get_real()

SWMM_ENGINE_API int swmm_userflag_get_real	(	SWMM_Engine	engine,
		const char *	name,
		double *	value )

Get the value of a REAL user flag.

Parameters

engine	Engine handle.
name	Flag name.
value	[out] Double value.

Returns: SWMM_OK; SWMM_ERR_BADPARAM if not found or wrong type.

◆ swmm_userflag_set_bool()

SWMM_ENGINE_API int swmm_userflag_set_bool	(	SWMM_Engine	engine,
		const char *	name,
		int	value )

Set a BOOLEAN user flag at runtime.

◆ swmm_userflag_set_int()

SWMM_ENGINE_API int swmm_userflag_set_int	(	SWMM_Engine	engine,
		const char *	name,
		int	value )

Set an INTEGER user flag at runtime.

◆ swmm_userflag_set_real()

SWMM_ENGINE_API int swmm_userflag_set_real	(	SWMM_Engine	engine,
		const char *	name,
		double	value )

Set a REAL user flag at runtime.

◆ swmm_userflag_undefine()

SWMM_ENGINE_API int swmm_userflag_undefine	(	SWMM_Engine	engine,
		const char *	name )

Remove a user-flag definition and all per-object values assigned to it.

Parameters

engine	Engine handle.
name	Flag name (case-insensitive).

Returns: SWMM_OK; SWMM_ERR_BADPARAM if the flag is not defined.

◆ swmm_userflag_value_clear()

SWMM_ENGINE_API int swmm_userflag_value_clear	(	SWMM_Engine	engine,
		const char *	obj_type,
		const char *	obj_name,
		const char *	flag_name )

Remove the flag value assigned to a specific object (mark unset).

Parameters

engine	Engine handle.
obj_type	Object type token.
obj_name	Object identifier (case-preserved).
flag_name	Flag name (case-insensitive).

Returns: SWMM_OK (idempotent: clearing an unassigned value succeeds); SWMM_ERR_BADPARAM on null arguments.

◆ swmm_userflag_value_get()

SWMM_ENGINE_API int swmm_userflag_value_get	(	SWMM_Engine	engine,
		const char *	obj_type,
		const char *	obj_name,
		const char *	flag_name,
		char *	buf,
		int	buflen,
		int *	found )

Read the flag value assigned to a specific object, as a string.

Parameters

engine	Engine handle.
obj_type	Object type token (e.g. "NODE", "LINK", "SUBCATCHMENT").
obj_name	Object identifier (case-preserved).
flag_name	Flag name (case-insensitive).
buf	[out] Value string (empty when not assigned).
buflen	Size of buf in bytes.
found	[out] 1 if a value is assigned, 0 otherwise.

Returns: SWMM_OK; SWMM_ERR_BADPARAM on null arguments.

◆ swmm_userflag_value_set()

SWMM_ENGINE_API int swmm_userflag_value_set	(	SWMM_Engine	engine,
		const char *	obj_type,
		const char *	obj_name,
		const char *	flag_name,
		const char *	value )

Assign a flag value to a specific object from a string.

Parameters

engine	Engine handle.
obj_type	Object type token (e.g. "NODE", "LINK", "SUBCATCHMENT").
obj_name	Object identifier (case-preserved).
flag_name	Flag name; must already be defined (its declared type drives parsing).
value	Value string: BOOLEAN accepts YES/NO/TRUE/FALSE/1/0; INTEGER a decimal integer; REAL a decimal number; STRING is stored verbatim.

Returns: SWMM_OK; SWMM_ERR_BADPARAM on null arguments, undefined flag, or a value that does not parse as the declared type.

Here is the call graph for this function:

◆ swmm_validate_model()

SWMM_ENGINE_API int swmm_validate_model ( SWMM_Engine engine )

Validate model topology without changing state.

Checks connectivity (no orphaned links, at least one outfall, no duplicate IDs). Emits warnings via the registered warning callback. Does NOT change state — safe to call multiple times.

Parameters

engine Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).

Returns: SWMM_OK if validation passes; SWMM_ERR_* on fatal topology error.

Here is the caller graph for this function:

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ SWMM_FilePathRole

Enumeration Type Documentation

◆ SWMM_FilePathRole

Function Documentation

◆ swmm_engine_new()

◆ swmm_file_path_get()

◆ swmm_file_path_set()

◆ swmm_files_get()

◆ swmm_files_set()

◆ swmm_finalize_model()

◆ swmm_get_crs()

◆ swmm_model_write()

◆ swmm_model_write_with_plugin()

◆ swmm_options_get()

◆ swmm_options_get_end_date()

◆ swmm_options_get_ext()

◆ swmm_options_get_report_start()

◆ swmm_options_get_start_date()

◆ swmm_options_set()

◆ swmm_options_set_end_date()

◆ swmm_options_set_ext()

◆ swmm_options_set_report_start()

◆ swmm_options_set_start_date()

◆ swmm_plugin_get()

◆ swmm_plugin_remove()

◆ swmm_plugin_set()

◆ swmm_plugins_count()

◆ swmm_title_add_line()

◆ swmm_title_clear()

◆ swmm_title_get_count()

◆ swmm_title_get_line()

◆ swmm_title_set()

◆ swmm_userflag_def_count()

◆ swmm_userflag_def_get()

◆ swmm_userflag_define()

◆ swmm_userflag_get_bool()

◆ swmm_userflag_get_int()

◆ swmm_userflag_get_real()

◆ swmm_userflag_set_bool()

◆ swmm_userflag_set_int()

◆ swmm_userflag_set_real()

◆ swmm_userflag_undefine()

◆ swmm_userflag_value_clear()

◆ swmm_userflag_value_get()

◆ swmm_userflag_value_set()

◆ swmm_validate_model()