ApiSurfaceOwnership.cpp File Reference

C API implementation for surface ownership assignments. More...

#include <openswmm/engine/openswmm_surface_ownership.h>
#include "../../core/SWMMEngine.hpp"
#include "../subsurface/SurfaceOwnership.hpp"
#include <algorithm>
#include <cstring>

Include dependency graph for ApiSurfaceOwnership.cpp:

Functions
int	swmm_surface_owner_get (SWMM_Engine handle, int *rows, int capacity, int *count)
	Read the currently authored surface-owner subcatchment indices.
int	swmm_surface_owner_preview (SWMM_Engine handle, const int *rows, int count, SWMM_SurfaceOwnerObject *objects, int oc, int *on, SWMM_SurfaceOwnerShare *shares, int sc, int *sn, double *areas, int ac, int *an, int *valid, char *token, int tc, char *diag, int dc, SWMM_SurfaceOwnerProgress progress, void *user)
	Resolve proposed surface ownership, overlap diagnostics and a revision token.
int	swmm_surface_owner_replace (SWMM_Engine handle, const int *rows, int count, const char *expected, char *diag, int dc)
	Atomically replace authored surface-owner rows after revision checking.

Detailed Description

C API implementation for surface ownership assignments.

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

Function Documentation

swmm_surface_owner_get()

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

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

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: