openswmm_surface_ownership.h File Reference

Public C API for surface ownership assignments and validation. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_surface_ownership.h:

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

Go to the source code of this file.

Classes
struct	SWMM_SurfaceOwnerObject
struct	SWMM_SurfaceOwnerShare

Typedefs
typedef struct SWMM_SurfaceOwnerObject	SWMM_SurfaceOwnerObject
typedef struct SWMM_SurfaceOwnerShare	SWMM_SurfaceOwnerShare
typedef int(*	SWMM_SurfaceOwnerProgress) (int done, int total, void *user)
	Report surface-ownership preview work on the calling thread.

Functions
SWMM_ENGINE_API int	swmm_surface_owner_get (SWMM_Engine engine, int *rows, int capacity, int *count)
	Read the currently authored surface-owner subcatchment indices.
SWMM_ENGINE_API int	swmm_surface_owner_preview (SWMM_Engine engine, const int *rows, int count, SWMM_SurfaceOwnerObject *objects, int object_capacity, int *object_count, SWMM_SurfaceOwnerShare *shares, int share_capacity, int *share_count, double *mesh_weather_area, int cell_capacity, int *cell_count, int *valid, char *token, int token_capacity, char *diagnostics, int diagnostic_capacity, SWMM_SurfaceOwnerProgress progress, void *user)
	Resolve proposed surface ownership, overlap diagnostics and a revision token.
SWMM_ENGINE_API int	swmm_surface_owner_replace (SWMM_Engine engine, const int *rows, int count, const char *expected_token, char *diagnostics, int diagnostic_capacity)
	Atomically replace authored surface-owner rows after revision checking.

Detailed Description

Public C API for surface ownership assignments and validation.

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

Apache-2.0

Typedef Documentation

SWMM_SurfaceOwnerObject

typedef struct SWMM_SurfaceOwnerObject SWMM_SurfaceOwnerObject

SWMM_SurfaceOwnerProgress

typedef int(* SWMM_SurfaceOwnerProgress) (int done, int total, void *user)

Report surface-ownership preview work on the calling thread.

Must not throw or edit, close or destroy the engine. Callback/context pointers are borrowed only for the synchronous preview call.

Parameters

[in]	done	Number of work items completed so far.
[in]	total	Total work items for this preview stage.
[in]	user	Borrowed context passed through from swmm_surface_owner_preview(); may be NULL.

Returns

Nonzero to continue; zero to cancel.

SWMM_SurfaceOwnerShare

typedef struct SWMM_SurfaceOwnerShare SWMM_SurfaceOwnerShare

Function Documentation

swmm_surface_owner_get()

SWMM_ENGINE_API int swmm_surface_owner_get	(	SWMM_Engine	engine,
		int *	rows,
		int	capacity,
		int *	count )

Read the currently authored surface-owner subcatchment indices.

A size query does not allocate caller storage. A short buffer returns the required count without copying rows.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; exclusive access is required.
[out]	rows	Caller-owned array of capacity indices, or NULL with capacity=0 to query the count.
[in]	capacity	Nonnegative array capacity in records, not bytes.
[out]	count	Non-null required-row output; set before short-buffer refusal. Each returned row is the current subcatchment index or -1 if an authored name no longer resolves.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside editable states, or SWMM_ERR_BADPARAM for invalid count/capacity/buffer or insufficient capacity.

swmm_surface_owner_preview()

SWMM_ENGINE_API int swmm_surface_owner_preview	(	SWMM_Engine	engine,
		const int *	rows,
		int	count,
		SWMM_SurfaceOwnerObject *	objects,
		int	object_capacity,
		int *	object_count,
		SWMM_SurfaceOwnerShare *	shares,
		int	share_capacity,
		int *	share_count,
		double *	mesh_weather_area,
		int	cell_capacity,
		int *	cell_count,
		int *	valid,
		char *	token,
		int	token_capacity,
		char *	diagnostics,
		int	diagnostic_capacity,
		SWMM_SurfaceOwnerProgress	progress,
		void *	user )

Resolve proposed surface ownership, overlap diagnostics and a revision token.

Does not modify authored ownership. Counts, valid, token and diagnostics are published before cancellation/capacity refusal; object/share/area arrays are copied only after all capacity checks. Areas are m2; indices address engine cells/subcatchments.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; exclusive access is required.
[in]	rows	Borrowed array of count zero-based subcatchment indices forming the complete proposed SUBCATCH UNIFORM set; NULL is allowed when count=0 or -1.
[in]	count	-1 previews stored records and ignores rows; otherwise nonnegative proposal size.
[out]	objects	Optional caller-owned object array including unreviewed peers; NULL requests only its required count.
[in]	object_capacity	Nonnegative object-array capacity in records; checked only when objects is non-null.
[out]	object_count	Non-null required object count, updated after preview even on cancellation/short output.
[out]	shares	Optional caller-owned cell-share array; NULL queries its required count.
[in]	share_capacity	Nonnegative share capacity in records; checked only when shares is non-null.
[out]	share_count	Non-null required share count, updated after preview.
[out]	mesh_weather_area	Optional array of per-cell weather areas in m2; NULL queries its required count.
[in]	cell_capacity	Nonnegative mesh_weather_area capacity in cells.
[out]	cell_count	Non-null required per-cell area count, updated after preview.
[out]	valid	Non-null result: 1 only for a valid, uncancelled preview; 0 indicates blocking diagnostics or cancellation. Invalid ownership can still return SWMM_OK.
[out]	token	Non-null caller-owned revision-token buffer. Identifies current model inputs INCLUDING current authored records, independently of the proposal; NUL-terminated.
[in]	token_capacity	Token capacity in bytes; must be at least 17.
[out]	diagnostics	Optional caller-owned newline-separated diagnostic buffer, NUL-terminated and truncated when capacity is positive.
[in]	diagnostic_capacity	Diagnostic capacity including NUL; nonpositive suppresses text output.
[in]	progress	Optional synchronous callback; nonzero continues, zero cancels. Must not edit/destroy the engine.
[in]	user	Borrowed opaque progress context; may be NULL.

Returns

SWMM_OK for a completed preview even if valid=0; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside editable states, or SWMM_ERR_BADPARAM for invalid input, cancellation or short non-null arrays.

Here is the call graph for this function:

swmm_surface_owner_replace()

SWMM_ENGINE_API int swmm_surface_owner_replace	(	SWMM_Engine	engine,
		const int *	rows,
		int	count,
		const char *	expected_token,
		char *	diagnostics,
		int	diagnostic_capacity )

Atomically replace authored surface-owner rows after revision checking.

Recomputes the proposal and compares its current-input token before publishing. Nonempty invalid proposals and stale tokens preserve authored records. Empty proposals are permitted after revision checking. These are authoring records; publication does not itself activate recharge or initialize a source adapter.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; exclusive access is required.
[in]	rows	Borrowed array of count zero-based subcatchment indices forming the complete proposed SUBCATCH UNIFORM set; NULL is allowed when count=0 or -1.
[in]	count	Nonnegative complete replacement count; zero removes all authored records and restores legacy absence.
[in]	expected_token	Non-null NUL-terminated token from a preview of the current inputs; stale tokens are refused.
[out]	diagnostics	Optional caller-owned refusal text buffer; emptied on success, NUL-terminated/truncated when capacity is positive.
[in]	diagnostic_capacity	Diagnostic buffer capacity including NUL; nonpositive suppresses output.

Returns

SWMM_OK on replacement; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside editable states, or SWMM_ERR_BADPARAM for invalid proposal, indices or stale token.

Here is the call graph for this function: