C API — [PROCESS_COMPONENTS] registrations (E-C3 subset of the transport IO plan §5): enumerate, find, register, remove. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_process_components.h:

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

Go to the source code of this file.

Classes
struct	SWMM_ComponentLibraryInfo
	One discovered (or refused) component library. Strings are NUL-terminated and truncated to their field size. More...

Typedefs
typedef struct SWMM_ComponentLibraryInfo	SWMM_ComponentLibraryInfo
	One discovered (or refused) component library. Strings are NUL-terminated and truncated to their field size.

Functions
SWMM_ENGINE_API int	swmm_process_component_count (SWMM_Engine engine)
	Count stored model process-component registrations.

SWMM_ENGINE_API int	swmm_process_component_get (SWMM_Engine engine, int idx, char id_buf, int id_len, char config_buf, int config_len, char *resolved_buf, int resolved_len)
	Copy one process-component registration and its last resolved config path.

SWMM_ENGINE_API int	swmm_process_component_find (SWMM_Engine engine, const char *id)
	Find a model registration by exact component ID.

SWMM_ENGINE_API int	swmm_process_component_register (SWMM_Engine engine, const char id, const char config_path)
	Append an editable process-component registration.

SWMM_ENGINE_API int	swmm_process_component_remove (SWMM_Engine engine, int idx)
	Remove a model registration and shift later indices down.

SWMM_ENGINE_API int	swmm_process_component_known_count (void)
	Count process-global built-in catalogue entries.

SWMM_ENGINE_API int	swmm_process_component_known_get (int idx, char id_buf, int id_len, char desc_buf, int desc_len, int *implemented)
	Read one process-global built-in catalogue entry.

SWMM_ENGINE_API int	swmm_component_search_path_add (const char *dir)
	Scan an additional directory for HydroCouple component libraries.

SWMM_ENGINE_API int	swmm_component_library_count (void)
	Count recognized discovered component libraries, including refused candidates.

SWMM_ENGINE_API int	swmm_component_library_get (int idx, SWMM_ComponentLibraryInfo *info)
	Copy metadata for one recognized component-library candidate.

Detailed Description

C API — [PROCESS_COMPONENTS] registrations (E-C3 subset of the transport IO plan §5): enumerate, find, register, remove.

The GUI's file-binding surface: an editor locates its component's config path here, and the "create component + config file" flow registers first, then writes the file (registration with a not-yet-existing config path is legal — resolve reads it at the next open).

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_ComponentLibraryInfo

typedef struct SWMM_ComponentLibraryInfo SWMM_ComponentLibraryInfo

One discovered (or refused) component library. Strings are NUL-terminated and truncated to their field size.

Function Documentation

◆ swmm_component_library_count()

SWMM_ENGINE_API int swmm_component_library_count ( void )

Count recognized discovered component libraries, including refused candidates.

Triggers normal initial discovery when required. No engine handle is needed; this count is distinct from model process-component registrations.

Returns: Nonnegative process-global catalogue size; zero when no component libraries are recognized (including builds without HydroCouple).

Here is the call graph for this function:

◆ swmm_component_library_get()

SWMM_ENGINE_API int swmm_component_library_get	(	int	idx,
		SWMM_ComponentLibraryInfo *	info )

Copy metadata for one recognized component-library candidate.

May trigger initial discovery. Inspect load_error before treating the ID/caption/version as an accepted usable library; a returned catalogue entry can represent an ABI refusal.

Parameters

[in]	idx	Zero-based index in [0,swmm_component_library_count()).
[out]	info	Non-null caller-owned fixed-size metadata destination. All string fields are NUL-terminated and silently truncated to their own array capacity.

Returns: SWMM_OK; SWMM_ERR_BADPARAM for null info or SWMM_ERR_BADINDEX for invalid idx.

Here is the call graph for this function:

◆ swmm_component_search_path_add()

SWMM_ENGINE_API int swmm_component_search_path_add ( const char * dir )

Scan an additional directory for HydroCouple component libraries.

Discovery can load recognized shared libraries to inspect their component ABI. Recognized refused libraries remain in the catalogue with load_error; successful scanning does not imply every library was accepted. See the header discovery/stamp contract.

Parameters

[in] dir Non-null, nonempty NUL-terminated directory path, copied into the process-global search configuration.

Returns: SWMM_OK on accepted scan; SWMM_ERR_BADPARAM for null/empty/invalid directory, or SWMM_ERR_PLUGIN when built without HydroCouple.

Here is the call graph for this function:

◆ swmm_process_component_count()

SWMM_ENGINE_API int swmm_process_component_count ( SWMM_Engine engine )

Count stored model process-component registrations.

Counts authoring entries, not discovered libraries or initialized runtime instances.

Parameters

[in] engine Non-null live engine with exclusive caller access.

Returns: Nonnegative registration count, or -1 for null engine.

◆ swmm_process_component_find()

SWMM_ENGINE_API int swmm_process_component_find	(	SWMM_Engine	engine,
		const char *	id )

Find a model registration by exact component ID.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	id	Non-null NUL-terminated ID, matched case-sensitively.

Returns: Zero-based registration index, or -1 for absent ID/null engine/null ID.

Here is the caller graph for this function:

◆ swmm_process_component_get()

SWMM_ENGINE_API int swmm_process_component_get	(	SWMM_Engine	engine,
		int	idx,
		char *	id_buf,
		int	id_len,
		char *	config_buf,
		int	config_len,
		char *	resolved_buf,
		int	resolved_len )

Copy one process-component registration and its last resolved config path.

This is metadata retrieval only; it does not load the component or reread its configuration.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	idx	Zero-based registration index.
[out]	id_buf	Non-null caller-owned component-ID buffer, NUL-terminated and silently truncated to id_len-1 bytes.
[in]	id_len	Positive ID capacity in bytes including NUL.
[out]	config_buf	Non-null caller-owned authored config-path buffer; empty is allowed, NUL-terminated/truncated.
[in]	config_len	Positive config capacity including NUL.
[out]	resolved_buf	Non-null caller-owned resolved effective path buffer; empty until resolution, NUL-terminated/truncated.
[in]	resolved_len	Positive resolved-path capacity including NUL.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid idx, or SWMM_ERR_BADPARAM for a null/nonpositive-capacity buffer.

◆ swmm_process_component_known_count()

SWMM_ENGINE_API int swmm_process_component_known_count ( void )

Count process-global built-in catalogue entries.

Independent of any model handle and does not scan disk.

Returns: Number of known built-ins, including entries with no apply hook.

Here is the call graph for this function:

◆ swmm_process_component_known_get()

SWMM_ENGINE_API int swmm_process_component_known_get	(	int	idx,
		char *	id_buf,
		int	id_len,
		char *	desc_buf,
		int	desc_len,
		int *	implemented )

Read one process-global built-in catalogue entry.

Optional outputs may all be suppressed; this does not validate whether a particular model/config can activate the built-in.

Parameters

[in]	idx	Zero-based index in [0,swmm_process_component_known_count()).
[out]	id_buf	Optional caller-owned ID buffer, NUL-terminated/truncated when id_len>0.
[in]	id_len	ID capacity including NUL; nonpositive suppresses ID output.
[out]	desc_buf	Optional caller-owned description buffer, NUL-terminated/truncated when desc_len>0.
[in]	desc_len	Description capacity including NUL; nonpositive suppresses description output.
[out]	implemented	Optional destination: 1 when an apply hook is present in this build, 0 for a placeholder.

Returns: SWMM_OK; SWMM_ERR_BADINDEX for invalid idx or SWMM_ERR_INTERNAL for an inconsistent registry entry.

Here is the call graph for this function:

◆ swmm_process_component_register()

SWMM_ENGINE_API int swmm_process_component_register	(	SWMM_Engine	engine,
		const char *	id,
		const char *	config_path )

Append an editable process-component registration.

Does not resolve the ID against a catalogue or initialize/read the config immediately. Normal model resolution at a subsequent open consumes the registration; no automatic config file is created.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	id	Non-null, nonempty NUL-terminated component ID to copy; an exact existing ID is refused.
[in]	config_path	Optional copied config path token; NULL means no config argument. The file need not exist yet.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside BUILDING/OPENED, or SWMM_ERR_BADPARAM for null/empty/duplicate ID.

Here is the call graph for this function:

◆ swmm_process_component_remove()

SWMM_ENGINE_API int swmm_process_component_remove	(	SWMM_Engine	engine,
		int	idx )

Remove a model registration and shift later indices down.

Does not delete its config file or independently unload a runtime instance.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	idx	Zero-based existing registration index.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside BUILDING/OPENED, or SWMM_ERR_BADINDEX for invalid idx.

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SWMM_ComponentLibraryInfo

Function Documentation

◆ swmm_component_library_count()

◆ swmm_component_library_get()

◆ swmm_component_search_path_add()

◆ swmm_process_component_count()

◆ swmm_process_component_find()

◆ swmm_process_component_get()

◆ swmm_process_component_known_count()

◆ swmm_process_component_known_get()

◆ swmm_process_component_register()

◆ swmm_process_component_remove()