OpenSWMM Engine — Link (conduit/pump/orifice/weir/outlet) C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_links.h:

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

Typedefs
typedef enum SWMM_LinkType	SWMM_LinkType
	Link type classification.

typedef enum SWMM_XSectShape	SWMM_XSectShape
	Cross-section shape codes for conduit links.

typedef enum SWMM_OrificeType	SWMM_OrificeType
	Orifice flow-attack classification.

typedef enum SWMM_WeirType	SWMM_WeirType
	Weir-flow classification.

typedef enum SWMM_OutletRatingType	SWMM_OutletRatingType
	Outlet rating-curve classification.

Enumerations
enum	SWMM_LinkType { SWMM_LINK_CONDUIT = 0 , SWMM_LINK_PUMP = 1 , SWMM_LINK_ORIFICE = 2 , SWMM_LINK_WEIR = 3 , SWMM_LINK_OUTLET = 4 }
	Link type classification. More...

enum	SWMM_XSectShape { SWMM_XSECT_CIRCULAR = 0 , SWMM_XSECT_FILLED_CIRCULAR , SWMM_XSECT_RECT_CLOSED , SWMM_XSECT_RECT_OPEN , SWMM_XSECT_TRAPEZOIDAL , SWMM_XSECT_TRIANGULAR , SWMM_XSECT_PARABOLIC , SWMM_XSECT_POWER , SWMM_XSECT_MOD_BASKET , SWMM_XSECT_EGGSHAPED = 9 , SWMM_XSECT_HORSESHOE = 10 , SWMM_XSECT_GOTHIC = 11 , SWMM_XSECT_CATENARY = 12 , SWMM_XSECT_SEMIELLIPTICAL = 13 , SWMM_XSECT_BASKETHANDLE = 14 , SWMM_XSECT_SEMICIRCULAR = 15 , SWMM_XSECT_RECT_TRIANG , SWMM_XSECT_RECT_ROUND , SWMM_XSECT_HORIZ_ELLIPSE , SWMM_XSECT_VERT_ELLIPSE , SWMM_XSECT_ARCH = 20 , SWMM_XSECT_IRREGULAR = 21 , SWMM_XSECT_CUSTOM , SWMM_XSECT_FORCE_MAIN , SWMM_XSECT_STREET = 24 , SWMM_XSECT_DUMMY = 25 }
	Cross-section shape codes for conduit links. More...

enum	SWMM_OrificeType { SWMM_ORIFICE_SIDE = 0 , SWMM_ORIFICE_BOTTOM = 1 }
	Orifice flow-attack classification. More...

enum	SWMM_WeirType { SWMM_WEIR_TRANSVERSE = 0 , SWMM_WEIR_SIDEFLOW = 1 , SWMM_WEIR_VNOTCH = 2 , SWMM_WEIR_TRAPEZOIDAL = 3 , SWMM_WEIR_ROADWAY = 4 }
	Weir-flow classification. More...

enum	SWMM_OutletRatingType { SWMM_OUTLET_FUNCTIONAL_HEAD = 0 , SWMM_OUTLET_FUNCTIONAL_DEPTH = 1 , SWMM_OUTLET_TABULAR_HEAD = 2 , SWMM_OUTLET_TABULAR_DEPTH = 3 }
	Outlet rating-curve classification. More...

Functions
SWMM_ENGINE_API int	swmm_link_count (SWMM_Engine engine)
	Get the total number of links in the model.

SWMM_ENGINE_API int	swmm_link_index (SWMM_Engine engine, const char *id)
	Look up a link's zero-based index by its string identifier.

SWMM_ENGINE_API const char *	swmm_link_id (SWMM_Engine engine, int idx)
	Get the string identifier of a link by index.

SWMM_ENGINE_API int	swmm_link_add (SWMM_Engine engine, const char *id, int type)
	Add a new link to the model.

SWMM_ENGINE_API int	swmm_link_pop_last (SWMM_Engine engine, const char *id)
	Remove the most recently added link (undo-of-add).

SWMM_ENGINE_API int	swmm_link_set_nodes (SWMM_Engine engine, int idx, int from_node_idx, int to_node_idx)
	Set the upstream and downstream nodes of a link.

SWMM_ENGINE_API int	swmm_link_get_from_node (SWMM_Engine engine, int idx, int *node_idx)
	Get the upstream (inlet) node index of a link.

SWMM_ENGINE_API int	swmm_link_get_to_node (SWMM_Engine engine, int idx, int *node_idx)
	Get the downstream (outlet) node index of a link.

SWMM_ENGINE_API int	swmm_links_restore_authored_orientation (SWMM_Engine engine, int *count)
	Restore authored From/To orientation on every conduit the parser reversed for adverse slope (DYNWAVE/FV routing).

SWMM_ENGINE_API int	swmm_link_set_length (SWMM_Engine engine, int idx, double length)
	Set the conduit length.

SWMM_ENGINE_API int	swmm_link_set_roughness (SWMM_Engine engine, int idx, double n)
	Set the Manning's roughness coefficient.

SWMM_ENGINE_API int	swmm_link_set_offset_up (SWMM_Engine engine, int idx, double offset)
	Set the upstream (inlet) offset above the upstream node invert.

SWMM_ENGINE_API int	swmm_link_set_offset_dn (SWMM_Engine engine, int idx, double offset)
	Set the downstream (outlet) offset above the downstream node invert.

SWMM_ENGINE_API int	swmm_link_set_initial_flow (SWMM_Engine engine, int idx, double flow)
	Set the initial flow in a link at simulation start.

SWMM_ENGINE_API int	swmm_link_set_max_flow (SWMM_Engine engine, int idx, double flow)
	Set the maximum allowable flow in a link.

SWMM_ENGINE_API int	swmm_link_get_initial_flow (SWMM_Engine engine, int idx, double *flow)
	Get the initial flow in a link at simulation start.

SWMM_ENGINE_API int	swmm_link_get_max_flow (SWMM_Engine engine, int idx, double *flow)
	Get the maximum allowable flow in a link.

SWMM_ENGINE_API int	swmm_link_set_orifice_type (SWMM_Engine engine, int idx, int type)
	Set the orifice flow-attack classification (SIDE / BOTTOM).

SWMM_ENGINE_API int	swmm_link_get_orifice_type (SWMM_Engine engine, int idx, int *type)
	Get the orifice flow-attack classification.

SWMM_ENGINE_API int	swmm_link_set_weir_type (SWMM_Engine engine, int idx, int type)
	Set the weir flow classification.

SWMM_ENGINE_API int	swmm_link_get_weir_type (SWMM_Engine engine, int idx, int *type)
	Get the weir flow classification.

SWMM_ENGINE_API int	swmm_link_set_outlet_rating_type (SWMM_Engine engine, int idx, int type)
	Set the outlet rating selector on an editable outlet link.

SWMM_ENGINE_API int	swmm_link_get_outlet_rating_type (SWMM_Engine engine, int idx, int *type)
	Read the outlet rating selector.

SWMM_ENGINE_API int	swmm_link_set_outlet_expon (SWMM_Engine engine, int idx, double expon)
	Set the outlet functional-rating exponent on an editable outlet link.

SWMM_ENGINE_API int	swmm_link_get_outlet_expon (SWMM_Engine engine, int idx, double *expon)
	Read the outlet functional-rating exponent.

SWMM_ENGINE_API int	swmm_link_set_pump_startup_depth (SWMM_Engine engine, int idx, double depth)
	Set the pump startup depth on an editable pump link.

SWMM_ENGINE_API int	swmm_link_get_pump_startup_depth (SWMM_Engine engine, int idx, double *depth)
	Read the pump startup depth.

SWMM_ENGINE_API int	swmm_link_set_pump_shutoff_depth (SWMM_Engine engine, int idx, double depth)
	Set the pump shutoff depth on an editable pump link.

SWMM_ENGINE_API int	swmm_link_get_pump_shutoff_depth (SWMM_Engine engine, int idx, double *depth)
	Read the pump shutoff depth.

SWMM_ENGINE_API int	swmm_link_set_orifice_open_close_rate (SWMM_Engine engine, int idx, double rate)
	Set the orifice open/close rate on an editable orifice link.

SWMM_ENGINE_API int	swmm_link_get_orifice_open_close_rate (SWMM_Engine engine, int idx, double *rate)
	Read the orifice open/close rate.

SWMM_ENGINE_API int	swmm_link_set_xsect (SWMM_Engine engine, int idx, int shape, double geom1, double geom2, double geom3, double geom4)
	Set the cross-section geometry for a conduit link.

SWMM_ENGINE_API int	swmm_link_get_xsect (SWMM_Engine engine, int idx, int shape, double geom1, double geom2, double geom3, double *geom4)
	Get the cross-section geometry for a conduit link.

SWMM_ENGINE_API int	swmm_link_get_type (SWMM_Engine engine, int idx, int *type)
	Get the type of a link.

SWMM_ENGINE_API int	swmm_link_get_length (SWMM_Engine engine, int idx, double *length)
	Get the conduit length.

SWMM_ENGINE_API int	swmm_link_get_roughness (SWMM_Engine engine, int idx, double *n)
	Get the Manning's roughness coefficient.

SWMM_ENGINE_API int	swmm_link_get_flow (SWMM_Engine engine, int idx, double *flow)
	Get the current flow rate in a link.

SWMM_ENGINE_API int	swmm_link_set_flow (SWMM_Engine engine, int idx, double flow)
	Set the flow rate in a link (runtime override).

SWMM_ENGINE_API int	swmm_link_get_depth (SWMM_Engine engine, int idx, double *depth)
	Get the current water depth in a link.

SWMM_ENGINE_API int	swmm_link_get_velocity (SWMM_Engine engine, int idx, double *velocity)
	Get the current flow velocity in a link.

SWMM_ENGINE_API int	swmm_link_get_capacity (SWMM_Engine engine, int idx, double *capacity)
	Get the current flow capacity utilization (depth / full depth).

SWMM_ENGINE_API int	swmm_link_get_volume (SWMM_Engine engine, int idx, double *volume)
	Get the current water volume stored in a link.

SWMM_ENGINE_API int	swmm_link_get_slot_volume (SWMM_Engine engine, int idx, double *volume)
	Get the portion of a link's stored volume held in the Preissmann slot.

SWMM_ENGINE_API int	swmm_link_set_control_setting (SWMM_Engine engine, int idx, double setting)
	Assign a link current control setting directly during a run.

SWMM_ENGINE_API int	swmm_link_get_control_setting (SWMM_Engine engine, int idx, double *setting)
	Read the stored link current control setting.

SWMM_ENGINE_API int	swmm_link_set_target_setting (SWMM_Engine engine, int idx, double setting)
	Assign a link target control setting directly during a run.

SWMM_ENGINE_API int	swmm_link_get_target_setting (SWMM_Engine engine, int idx, double *setting)
	Read the stored link target control setting.

SWMM_ENGINE_API int	swmm_link_set_closed (SWMM_Engine engine, int idx, int closed)
	Open or close a link.

SWMM_ENGINE_API int	swmm_link_get_closed (SWMM_Engine engine, int idx, int *closed)
	Read the current link closed/open flag.

SWMM_ENGINE_API int	swmm_link_set_pump_curve (SWMM_Engine engine, int idx, int curve_idx)
	Assign a pump curve to a pump link.

SWMM_ENGINE_API int	swmm_link_get_pump_curve (SWMM_Engine engine, int idx, int *curve_idx)
	Get the pump curve index assigned to a pump link.

SWMM_ENGINE_API int	swmm_link_set_pump_init_state (SWMM_Engine engine, int idx, int on)
	Set the initial on/off state of a pump at simulation start.

SWMM_ENGINE_API int	swmm_link_get_pump_init_state (SWMM_Engine engine, int idx, int *on)
	Get the initial on/off state of a pump.

SWMM_ENGINE_API int	swmm_link_set_crest_height (SWMM_Engine engine, int idx, double h)
	Set the crest height for a weir link.

SWMM_ENGINE_API int	swmm_link_get_crest_height (SWMM_Engine engine, int idx, double *h)
	Get the crest height for a weir link.

SWMM_ENGINE_API int	swmm_link_set_discharge_coeff (SWMM_Engine engine, int idx, double cd)
	Set the discharge coefficient for a weir link.

SWMM_ENGINE_API int	swmm_link_get_discharge_coeff (SWMM_Engine engine, int idx, double *cd)
	Get the discharge coefficient for a weir link.

SWMM_ENGINE_API int	swmm_link_set_end_contractions (SWMM_Engine engine, int idx, double n)
	Set the number of end contractions for a weir link.

SWMM_ENGINE_API int	swmm_link_get_end_contractions (SWMM_Engine engine, int idx, double *n)
	Get the number of end contractions for a weir link.

SWMM_ENGINE_API int	swmm_link_set_loss_coeff (SWMM_Engine engine, int idx, double inlet, double outlet, double avg)
	Set entry, exit, and average loss coefficients for a conduit.

SWMM_ENGINE_API int	swmm_link_get_loss_coeff (SWMM_Engine engine, int idx, double inlet, double outlet, double *avg)
	Get entry, exit, and average loss coefficients for a conduit.

SWMM_ENGINE_API int	swmm_link_set_flap_gate (SWMM_Engine engine, int idx, int has_gate)
	Set whether a flap gate exists on a link.

SWMM_ENGINE_API int	swmm_link_get_flap_gate (SWMM_Engine engine, int idx, int *has_gate)
	Get whether a flap gate exists on a link.

SWMM_ENGINE_API int	swmm_link_set_seep_rate (SWMM_Engine engine, int idx, double rate)
	Set the seepage loss rate for a conduit.

SWMM_ENGINE_API int	swmm_link_get_seep_rate (SWMM_Engine engine, int idx, double *rate)
	Get the seepage loss rate for a conduit.

SWMM_ENGINE_API int	swmm_link_set_culvert_code (SWMM_Engine engine, int idx, int code)
	Set the FHWA culvert inlet geometry code.

SWMM_ENGINE_API int	swmm_link_get_culvert_code (SWMM_Engine engine, int idx, int *code)
	Get the FHWA culvert inlet geometry code.

SWMM_ENGINE_API int	swmm_link_set_barrels (SWMM_Engine engine, int idx, int n)
	Set the number of parallel barrels in a conduit.

SWMM_ENGINE_API int	swmm_link_get_barrels (SWMM_Engine engine, int idx, int *n)
	Get the number of parallel barrels in a conduit.

SWMM_ENGINE_API int	swmm_link_get_slope (SWMM_Engine engine, int idx, double *slope)
	Get the computed slope of a conduit.

SWMM_ENGINE_API int	swmm_link_get_offset_up (SWMM_Engine engine, int idx, double *offset)
	Get the upstream (inlet) offset.

SWMM_ENGINE_API int	swmm_link_get_offset_dn (SWMM_Engine engine, int idx, double *offset)
	Get the downstream (outlet) offset.

SWMM_ENGINE_API int	swmm_link_get_stat_max_flow (SWMM_Engine engine, int idx, double *val)
	Get the maximum flow recorded in a link during the simulation.

SWMM_ENGINE_API int	swmm_link_get_stat_max_velocity (SWMM_Engine engine, int idx, double *val)
	Get the maximum velocity recorded in a link.

SWMM_ENGINE_API int	swmm_link_get_stat_max_filling (SWMM_Engine engine, int idx, double *val)
	Get the maximum depth/full-depth ratio (filling) in a link.

SWMM_ENGINE_API int	swmm_link_get_stat_peak_slot_share (SWMM_Engine engine, int idx, double *val)
	Read a link peak instantaneous numerical-slot storage share.

SWMM_ENGINE_API int	swmm_link_get_stat_slot_share (SWMM_Engine engine, int idx, double *val)
	Read a link time-integrated numerical-slot storage share.

SWMM_ENGINE_API int	swmm_link_get_stat_vol_flow (SWMM_Engine engine, int idx, double *val)
	Get the total volume conveyed through a link.

SWMM_ENGINE_API int	swmm_link_get_stat_surcharge_time (SWMM_Engine engine, int idx, double *val)
	Get the total surcharge duration for a link.

SWMM_ENGINE_API int	swmm_link_get_quality (SWMM_Engine engine, int link_idx, int pollutant_idx, double *conc)
	Get the pollutant concentration in a link.

SWMM_ENGINE_API int	swmm_link_get_flows_bulk (SWMM_Engine engine, double *buf, int count)
	Get flow rates for all links in a single call.

SWMM_ENGINE_API int	swmm_link_get_depths_bulk (SWMM_Engine engine, double *buf, int count)
	Get water depths for all links in a single call.

SWMM_ENGINE_API int	swmm_link_set_flows_bulk (SWMM_Engine engine, const double *buf, int count)
	Set flow rates for all links in a single call (runtime override).

SWMM_ENGINE_API int	swmm_link_get_quality_bulk (SWMM_Engine engine, int pollutant_idx, double *buf, int count)
	Get pollutant concentrations for all links for one pollutant.

SWMM_ENGINE_API int	swmm_link_get_velocities_bulk (SWMM_Engine engine, double *buf, int count)
	Evaluate conveyance velocities for a prefix of links.

SWMM_ENGINE_API int	swmm_link_get_capacities_bulk (SWMM_Engine engine, double *buf, int count)
	Copy signed capacity ratios for a prefix of the link table.

SWMM_ENGINE_API int	swmm_link_get_volumes_bulk (SWMM_Engine engine, double *buf, int count)
	Copy current stored water volumes for a prefix of the link table.

SWMM_ENGINE_API int	swmm_link_get_control_settings_bulk (SWMM_Engine engine, double *buf, int count)
	Copy current control settings for a prefix of the link table.

SWMM_ENGINE_API int	swmm_link_get_target_settings_bulk (SWMM_Engine engine, double *buf, int count)
	Copy target control settings for a prefix of the link table.

SWMM_ENGINE_API int	swmm_link_get_hyd_powers_bulk (SWMM_Engine engine, double *buf, int count)
	Copy hydraulic head-change power magnitudes for a prefix of the link table.

SWMM_ENGINE_API int	swmm_link_get_ids_bulk (SWMM_Engine engine, char *buf, int stride, int count)
	Get link IDs for all links in a single call (stride-packed UTF-8).

SWMM_ENGINE_API int	swmm_link_get_stat_pump_cycles (SWMM_Engine engine, int idx, int *cycles)
	Read a link recorded pump on/off cycle count.

SWMM_ENGINE_API int	swmm_link_get_stat_pump_on_time (SWMM_Engine engine, int idx, double *seconds)
	Read a link recorded pump on-duration.

SWMM_ENGINE_API int	swmm_link_get_stat_pump_volume (SWMM_Engine engine, int idx, double *volume)
	Read a link recorded pumped water volume.

SWMM_ENGINE_API int	swmm_link_get_pump_stats_bulk (SWMM_Engine engine, int cycles, double on_time, double *volume, int count)
	Get pump utilization statistics for all links in a single call.

SWMM_ENGINE_API int	swmm_link_get_hyd_power (SWMM_Engine engine, int idx, double *power)
	Read a link hydraulic head-change power magnitude.

SWMM_ENGINE_API int	swmm_link_rename (SWMM_Engine engine, int idx, const char *newId)
	Rename an editable link in its name index.

SWMM_ENGINE_API int	swmm_link_get_tag (SWMM_Engine engine, int idx, char *buf, int buflen)
	Copy a link free-form tag.

SWMM_ENGINE_API int	swmm_link_set_tag (SWMM_Engine engine, int idx, const char *tag)
	Copy or clear a link free-form tag.

Detailed Description

OpenSWMM Engine — Link (conduit/pump/orifice/weir/outlet) C API.

Link add (BUILDING state), geometry/cross-section setters, connectivity, state get/set, control setting injection, bulk access.

See also: openswmm_engine.h

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_LinkType

typedef enum SWMM_LinkType SWMM_LinkType

Link type classification.

Every link in a SWMM model belongs to one of these types. The type determines which property setters are valid (e.g., pump curves only apply to SWMM_LINK_PUMP).

◆ SWMM_OrificeType

typedef enum SWMM_OrificeType SWMM_OrificeType

Orifice flow-attack classification.

Used with swmm_link_set_orifice_type and swmm_link_get_orifice_type. Order matches the legacy SWMM-GUI combo (SWMM-GUI/Epaswmm5/objprops.txt:862).

Since: 6.0.0 (engine gap BN-LINK-02, added 2026-05-25)

◆ SWMM_OutletRatingType

typedef enum SWMM_OutletRatingType SWMM_OutletRatingType

Outlet rating-curve classification.

Used with swmm_link_set_outlet_rating_type and swmm_link_get_outlet_rating_type. Numeric encoding matches the legacy LinksHandler::handle_outlets convention (src/engine/input/handlers/LinksHandler.cpp:214-221) and the legacy SWMM-GUI combo order at SWMM-GUI/Epaswmm5/objprops.txt:913.

FUNCTIONAL types use the cd (coefficient) and the outlet exponent (see swmm_link_set_outlet_expon) to define the rating curve; TABULAR types use the curve assigned via swmm_link_set_pump_curve (the engine shares the curve-index slot between pumps and tabular outlets).

Since: 6.0.0 (engine gap BN-LINK-04, added 2026-05-25)

◆ SWMM_WeirType

typedef enum SWMM_WeirType SWMM_WeirType

Weir-flow classification.

Used with swmm_link_set_weir_type and swmm_link_get_weir_type. Numeric order matches the legacy WeirType enum in legacy/engine/enums.h:925 and the legacy SWMM-GUI combo (SWMM-GUI/Epaswmm5/objprops.txt:160).

The companion "Shape" attribute in the legacy GUI is derived from the weir type (see objprops.txt:162 for the mapping) and need not be stored separately; clients that want the shape should consult swmm_link_get_xsect.

Since: 6.0.0 (engine gap BN-LINK-03, added 2026-05-25)

◆ SWMM_XSectShape

typedef enum SWMM_XSectShape SWMM_XSectShape

Cross-section shape codes for conduit links.

Used with swmm_link_set_xsect() and swmm_link_get_xsect(). The interpretation of geom1–geom4 depends on the shape; see the SWMM 5.2 reference manual for cross-section geometry definitions.

Warning: Renumbered in 6.0. These codes are the engine's own storage codes (openswmm::XsectShape). Prior to 6.0 every constant from 8 upward named a different shape than the one the engine stored, so e.g. SWMM_XSECT_IRREGULAR silently produced a vertical ellipse. Code that passed these constants symbolically and is recompiled against this header is corrected automatically; code that hard-coded the old integers must be renumbered. swmm_xsect_shape_name() is provided to check a code at runtime.

Note: These are NOT the legacy SWMM 5 XsectType codes (which put DUMMY at 0 and are used internally by the geometry kernels); the engine translates between the two at its own boundary.

Enumeration Type Documentation

◆ SWMM_LinkType

enum SWMM_LinkType

Link type classification.

Every link in a SWMM model belongs to one of these types. The type determines which property setters are valid (e.g., pump curves only apply to SWMM_LINK_PUMP).

Enumerator
SWMM_LINK_CONDUIT	Closed or open conduit conveying flow by gravity.
SWMM_LINK_PUMP	Pump link (flow determined by pump curve).
SWMM_LINK_ORIFICE	Orifice (circular or rectangular opening).
SWMM_LINK_WEIR	Weir (transverse/side/V-notch/trapezoidal).
SWMM_LINK_OUTLET	Flow-vs-head outlet structure.

◆ SWMM_OrificeType

enum SWMM_OrificeType

Orifice flow-attack classification.

Used with swmm_link_set_orifice_type and swmm_link_get_orifice_type. Order matches the legacy SWMM-GUI combo (SWMM-GUI/Epaswmm5/objprops.txt:862).

Since: 6.0.0 (engine gap BN-LINK-02, added 2026-05-25)

Enumerator
SWMM_ORIFICE_SIDE	Orifice opens on the side of the upstream node.
SWMM_ORIFICE_BOTTOM	Orifice opens through the bottom of the upstream node.

◆ SWMM_OutletRatingType

enum SWMM_OutletRatingType

Outlet rating-curve classification.

Used with swmm_link_set_outlet_rating_type and swmm_link_get_outlet_rating_type. Numeric encoding matches the legacy LinksHandler::handle_outlets convention (src/engine/input/handlers/LinksHandler.cpp:214-221) and the legacy SWMM-GUI combo order at SWMM-GUI/Epaswmm5/objprops.txt:913.

FUNCTIONAL types use the cd (coefficient) and the outlet exponent (see swmm_link_set_outlet_expon) to define the rating curve; TABULAR types use the curve assigned via swmm_link_set_pump_curve (the engine shares the curve-index slot between pumps and tabular outlets).

Since: 6.0.0 (engine gap BN-LINK-04, added 2026-05-25)

Enumerator
SWMM_OUTLET_FUNCTIONAL_HEAD	Q = Cd · H^expon (head above invert).
SWMM_OUTLET_FUNCTIONAL_DEPTH	Q = Cd · y^expon (depth at upstream node).
SWMM_OUTLET_TABULAR_HEAD	Q from rating curve indexed by head.
SWMM_OUTLET_TABULAR_DEPTH	Q from rating curve indexed by depth.

◆ SWMM_WeirType

enum SWMM_WeirType

Weir-flow classification.

Used with swmm_link_set_weir_type and swmm_link_get_weir_type. Numeric order matches the legacy WeirType enum in legacy/engine/enums.h:925 and the legacy SWMM-GUI combo (SWMM-GUI/Epaswmm5/objprops.txt:160).

The companion "Shape" attribute in the legacy GUI is derived from the weir type (see objprops.txt:162 for the mapping) and need not be stored separately; clients that want the shape should consult swmm_link_get_xsect.

Since: 6.0.0 (engine gap BN-LINK-03, added 2026-05-25)

Enumerator
SWMM_WEIR_TRANSVERSE	Sharp-crested transverse weir.
SWMM_WEIR_SIDEFLOW	Side-flow weir (USBR formula).
SWMM_WEIR_VNOTCH	Triangular / V-notch weir.
SWMM_WEIR_TRAPEZOIDAL	Trapezoidal weir.
SWMM_WEIR_ROADWAY	FHWA HDS-5 roadway weir.

◆ SWMM_XSectShape

enum SWMM_XSectShape

Cross-section shape codes for conduit links.

Used with swmm_link_set_xsect() and swmm_link_get_xsect(). The interpretation of geom1–geom4 depends on the shape; see the SWMM 5.2 reference manual for cross-section geometry definitions.

Warning: Renumbered in 6.0. These codes are the engine's own storage codes (openswmm::XsectShape). Prior to 6.0 every constant from 8 upward named a different shape than the one the engine stored, so e.g. SWMM_XSECT_IRREGULAR silently produced a vertical ellipse. Code that passed these constants symbolically and is recompiled against this header is corrected automatically; code that hard-coded the old integers must be renumbered. swmm_xsect_shape_name() is provided to check a code at runtime.

Note: These are NOT the legacy SWMM 5 XsectType codes (which put DUMMY at 0 and are used internally by the geometry kernels); the engine translates between the two at its own boundary.

Enumerator
SWMM_XSECT_CIRCULAR	Full circular pipe. geom1=diameter.
SWMM_XSECT_FILLED_CIRCULAR	Circular pipe with sediment deposit. geom1=diameter, geom2=filled depth.
SWMM_XSECT_RECT_CLOSED	Closed rectangular conduit. geom1=height, geom2=width.
SWMM_XSECT_RECT_OPEN	Open rectangular channel. geom1=height, geom2=width, geom3=# sides removed (0/1/2).
SWMM_XSECT_TRAPEZOIDAL	Trapezoidal channel. geom1=height, geom2=bottom width, geom3/geom4=side slopes.
SWMM_XSECT_TRIANGULAR	Triangular channel. geom1=height, geom2=top width.
SWMM_XSECT_PARABOLIC	Parabolic channel. geom1=height, geom2=top width.
SWMM_XSECT_POWER	Power-law shaped channel. geom1=height, geom2=top width, geom3=exponent.
SWMM_XSECT_MOD_BASKET	Modified baskethandle. geom1=height, geom2=bottom width, geom3=top radius.
SWMM_XSECT_EGGSHAPED	Egg-shaped (standard). geom1=height.
SWMM_XSECT_HORSESHOE	Horseshoe. geom1=height.
SWMM_XSECT_GOTHIC	Gothic. geom1=height.
SWMM_XSECT_CATENARY	Catenary. geom1=height.
SWMM_XSECT_SEMIELLIPTICAL	Semi-elliptical. geom1=height.
SWMM_XSECT_BASKETHANDLE	Baskethandle. geom1=height.
SWMM_XSECT_SEMICIRCULAR	Semi-circular. geom1=height.
SWMM_XSECT_RECT_TRIANG	Rectangular-triangular channel. geom1=height, geom2=top width, geom3=triangle height.
SWMM_XSECT_RECT_ROUND	Rectangular-round channel. geom1=height, geom2=top width, geom3=bottom radius.
SWMM_XSECT_HORIZ_ELLIPSE	Horizontal ellipse. geom1=height, geom2=width.
SWMM_XSECT_VERT_ELLIPSE	Vertical ellipse. geom1=height, geom2=width.
SWMM_XSECT_ARCH	Arch pipe. geom1=height, geom2=width.
SWMM_XSECT_IRREGULAR	Irregular (from transect data). geom1=transect index.
SWMM_XSECT_CUSTOM	Custom shape (from a shape curve). geom1=height, geom2=shape-curve index.
SWMM_XSECT_FORCE_MAIN	Circular force main. geom1=diameter, geom2=roughness (H-W C or D-W eps).
SWMM_XSECT_STREET	Street cross-section (from [STREETS]). geom1=street index.
SWMM_XSECT_DUMMY	Dummy — no geometry; all queries return 0.

Function Documentation

◆ swmm_link_add()

SWMM_ENGINE_API int swmm_link_add	(	SWMM_Engine	engine,
		const char *	id,
		int	type )

Add a new link to the model.

The engine must be in SWMM_STATE_BUILDING (programmatic construction) or SWMM_STATE_OPENED (interactive editing after the .inp has been parsed). Returns SWMM_ERR_LIFECYCLE for any other state. After creation, use swmm_link_set_nodes() to specify connectivity and the appropriate geometry / cross-section setters.

Parameters

[in]	engine	Engine handle.
[in]	id	Unique null-terminated identifier for the new link.
[in]	type	Link type (see SWMM_LinkType).

Returns: SWMM_OK on success, SWMM_ERR_LIFECYCLE if not in an editable state, or another error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE.

Here is the call graph for this function:

◆ swmm_link_count()

SWMM_ENGINE_API int swmm_link_count ( SWMM_Engine engine )

Get the total number of links in the model.

Parameters

[in] engine Engine handle.

Returns: Number of links, or -1 on error.

◆ swmm_link_get_barrels()

SWMM_ENGINE_API int swmm_link_get_barrels	(	SWMM_Engine	engine,
		int	idx,
		int *	n )

Get the number of parallel barrels in a conduit.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	n	Receives the barrel count.

Returns: SWMM_OK on success, or an error code.

Note: n may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_capacities_bulk()

SWMM_ENGINE_API int swmm_link_get_capacities_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Copy signed capacity ratios for a prefix of the link table.

Returns zero when full-flow discharge is not greater than 1e-12 internal ft3/s, including non-conduit links; reverse flow yields a negative ratio.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[out]	buf	Non-null caller-owned array of count doubles in dimensionless q/q_full.
[in]	count	Positive capacity/requested prefix length; writes min(count,link count) entries and leaves the tail unchanged.

Returns: SWMM_OK, including partial prefix reads; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null buf/count<=0.

◆ swmm_link_get_capacity()

SWMM_ENGINE_API int swmm_link_get_capacity	(	SWMM_Engine	engine,
		int	idx,
		double *	capacity )

Get the current flow capacity utilization (depth / full depth).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	capacity	Receives the ratio [0, 1+] (can exceed 1 if surcharged).

Returns: SWMM_OK on success, or an error code.

Note: capacity may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX. The ratio is signed q/q_full, not absolute capacity use; returns zero for absent/nonpositive full-flow capacity.

◆ swmm_link_get_closed()

SWMM_ENGINE_API int swmm_link_get_closed	(	SWMM_Engine	engine,
		int	idx,
		int *	closed )

Read the current link closed/open flag.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	closed	Optional destination: 1 when closed, 0 when open.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index.

◆ swmm_link_get_control_setting()

SWMM_ENGINE_API int swmm_link_get_control_setting	(	SWMM_Engine	engine,
		int	idx,
		double *	setting )

Read the stored link current control setting.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	setting	Optional dimensionless setting destination; no clamping is applied on read.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index.

◆ swmm_link_get_control_settings_bulk()

SWMM_ENGINE_API int swmm_link_get_control_settings_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Copy current control settings for a prefix of the link table.

Reads stored setting values without clamping.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[out]	buf	Non-null caller-owned array of count doubles in dimensionless.
[in]	count	Positive capacity/requested prefix length; writes min(count,link count) entries and leaves the tail unchanged.

Returns: SWMM_OK, including partial prefix reads; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null buf/count<=0.

◆ swmm_link_get_crest_height()

SWMM_ENGINE_API int swmm_link_get_crest_height	(	SWMM_Engine	engine,
		int	idx,
		double *	h )

Get the crest height for a weir link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	h	Receives the crest height.

Returns: SWMM_OK on success, or an error code.

Note: h may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_culvert_code()

SWMM_ENGINE_API int swmm_link_get_culvert_code	(	SWMM_Engine	engine,
		int	idx,
		int *	code )

Get the FHWA culvert inlet geometry code.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	code	Receives the culvert code.

Returns: SWMM_OK on success, or an error code.

Note: code may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_depth()

SWMM_ENGINE_API int swmm_link_get_depth	(	SWMM_Engine	engine,
		int	idx,
		double *	depth )

Get the current water depth in a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	depth	Receives the depth in project length units.

Returns: SWMM_OK on success, or an error code.

Note: depth may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_depths_bulk()

SWMM_ENGINE_API int swmm_link_get_depths_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Get water depths for all links in a single call.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least `count` doubles.
[in]	count	Number of elements.

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Copies min(count,link count) records and leaves any buffer tail unchanged.

◆ swmm_link_get_discharge_coeff()

SWMM_ENGINE_API int swmm_link_get_discharge_coeff	(	SWMM_Engine	engine,
		int	idx,
		double *	cd )

Get the discharge coefficient for a weir link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	cd	Receives the discharge coefficient.

Returns: SWMM_OK on success, or an error code.

Note: cd may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_end_contractions()

SWMM_ENGINE_API int swmm_link_get_end_contractions	(	SWMM_Engine	engine,
		int	idx,
		double *	n )

Get the number of end contractions for a weir link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	n	Receives the number of end contractions.

Returns: SWMM_OK on success, or an error code.

Note: n may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_flap_gate()

SWMM_ENGINE_API int swmm_link_get_flap_gate	(	SWMM_Engine	engine,
		int	idx,
		int *	has_gate )

Get whether a flap gate exists on a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	has_gate	Receives 1 if flap gate present, 0 otherwise.

Returns: SWMM_OK on success, or an error code.

Note: has_gate may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_flow()

SWMM_ENGINE_API int swmm_link_get_flow	(	SWMM_Engine	engine,
		int	idx,
		double *	flow )

Get the current flow rate in a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	flow	Receives the flow in project flow units.

Returns: SWMM_OK on success, or an error code.

Note: flow may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_flows_bulk()

SWMM_ENGINE_API int swmm_link_get_flows_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Get flow rates for all links in a single call.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least `count` doubles.
[in]	count	Number of elements (should equal swmm_link_count()).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Copies min(count,link count) records and leaves any buffer tail unchanged.

◆ swmm_link_get_from_node()

SWMM_ENGINE_API int swmm_link_get_from_node	(	SWMM_Engine	engine,
		int	idx,
		int *	node_idx )

Get the upstream (inlet) node index of a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	node_idx	Receives the upstream node index.

Returns: SWMM_OK on success, or an error code.

Note: node_idx may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_hyd_power()

SWMM_ENGINE_API int swmm_link_get_hyd_power	(	SWMM_Engine	engine,
		int	idx,
		double *	power )

Read a link hydraulic head-change power magnitude.

Computes 62.4*abs(Q_cfs)*abs(head_from_ft-head_to_ft); no conversion to watts/horsepower is performed.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	power	Optional destination in ft*lbf/s, regardless of project display units.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index.

◆ swmm_link_get_hyd_powers_bulk()

SWMM_ENGINE_API int swmm_link_get_hyd_powers_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Copy hydraulic head-change power magnitudes for a prefix of the link table.

Computes 62.4*abs(Q_cfs)*abs(head_from_ft-head_to_ft) with no conversion to watts or horsepower; non-conduit links use the same expression.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[out]	buf	Non-null caller-owned array of count doubles in ft*lbf/s, regardless of project display units.
[in]	count	Positive capacity/requested prefix length; writes min(count,link count) entries and leaves the tail unchanged.

Returns: SWMM_OK, including partial prefix reads; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null buf/count<=0.

◆ swmm_link_get_ids_bulk()

SWMM_ENGINE_API int swmm_link_get_ids_bulk	(	SWMM_Engine	engine,
		char *	buf,
		int	stride,
		int	count )

Get link IDs for all links in a single call (stride-packed UTF-8).

Stride-packed format matching swmm_node_get_ids_bulk : each ID is written into the slot buf[i*stride .. i*stride+stride-1] and NUL-terminated within its slot (truncated to stride-1 bytes if longer). The function zero-fills the requested region on entry so trailing bytes are always NUL.

Parameters

[in]	engine	Engine handle.
[out]	buf	Caller-allocated buffer of `stride*count` bytes.
[in]	stride	Per-ID slot size in bytes (must be > 1).
[in]	count	Number of IDs to read.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE if engine is invalid; SWMM_ERR_BADPARAM if buf is NULL, stride < 2, or count <= 0.

See also: swmm_link_id, swmm_node_get_ids_bulk

Since: 6.0.0

Note: A null engine returns SWMM_ERR_BADHANDLE.

◆ swmm_link_get_initial_flow()

SWMM_ENGINE_API int swmm_link_get_initial_flow	(	SWMM_Engine	engine,
		int	idx,
		double *	flow )

Get the initial flow in a link at simulation start.

Symmetric getter for swmm_link_set_initial_flow: the authored initial flow, in any post-construction engine state.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	flow	Receives the initial flow in project flow units.

Returns: SWMM_OK on success, or an error code.

Since: 6.0.0 (engine gap BN-LINK-01a, added 2026-05-25)

Note: flow may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link index check returns SWMM_ERR_BADINDEX. The run does not change it; read the current flow with swmm_link_get_flow().

◆ swmm_link_get_length()

SWMM_ENGINE_API int swmm_link_get_length	(	SWMM_Engine	engine,
		int	idx,
		double *	length )

Get the conduit length.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	length	Receives the length in project length units.

Returns: SWMM_OK on success, or an error code.

Note: length may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_loss_coeff()

SWMM_ENGINE_API int swmm_link_get_loss_coeff	(	SWMM_Engine	engine,
		int	idx,
		double *	inlet,
		double *	outlet,
		double *	avg )

Get entry, exit, and average loss coefficients for a conduit.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	inlet	Receives the inlet loss coefficient.
[out]	outlet	Receives the outlet loss coefficient.
[out]	avg	Receives the average loss coefficient.

Returns: SWMM_OK on success, or an error code.

Note: inlet may be NULL to suppress that output. outlet may be NULL to suppress that output. avg may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_max_flow()

SWMM_ENGINE_API int swmm_link_get_max_flow	(	SWMM_Engine	engine,
		int	idx,
		double *	flow )

Get the maximum allowable flow in a link.

Symmetric getter for swmm_link_set_max_flow. Returns 0.0 when no limit is configured (mirrors the setter's contract).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	flow	Receives the maximum flow in project flow units.

Returns: SWMM_OK on success, or an error code.

Since: 6.0.0 (engine gap BN-LINK-01b, added 2026-05-25)

Note: flow may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_offset_dn()

SWMM_ENGINE_API int swmm_link_get_offset_dn	(	SWMM_Engine	engine,
		int	idx,
		double *	offset )

Get the downstream (outlet) offset.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	offset	Receives the offset in project length units.

Returns: SWMM_OK on success, or an error code.

Note: offset may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX. Offsets use authored values; the internal sediment-depth bump for FILLED_CIRCULAR sections is added/removed at this boundary.

◆ swmm_link_get_offset_up()

SWMM_ENGINE_API int swmm_link_get_offset_up	(	SWMM_Engine	engine,
		int	idx,
		double *	offset )

Get the upstream (inlet) offset.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	offset	Receives the offset in project length units.

Returns: SWMM_OK on success, or an error code.

Note: offset may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX. Offsets use authored values; the internal sediment-depth bump for FILLED_CIRCULAR sections is added/removed at this boundary.

◆ swmm_link_get_orifice_open_close_rate()

SWMM_ENGINE_API int swmm_link_get_orifice_open_close_rate	(	SWMM_Engine	engine,
		int	idx,
		double *	rate )

Read the orifice open/close rate.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	rate	Optional destination. Fraction of full opening per second, with 0 meaning instantaneous. This API takes a rate rather than the legacy editor time in hours; no finite/range validation is imposed.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_BADPARAM for a non-ORIFICE link.

◆ swmm_link_get_orifice_type()

SWMM_ENGINE_API int swmm_link_get_orifice_type	(	SWMM_Engine	engine,
		int	idx,
		int *	type )

Get the orifice flow-attack classification.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	type	Receives the orifice type (see SWMM_OrificeType).

Returns: SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-orifice link.

Since: 6.0.0 (engine gap BN-LINK-02, added 2026-05-25)

Note: type may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_outlet_expon()

SWMM_ENGINE_API int swmm_link_get_outlet_expon	(	SWMM_Engine	engine,
		int	idx,
		double *	expon )

Read the outlet functional-rating exponent.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	expon	Optional destination. Dimensionless exponent; retained but not used for tabular rating types.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_BADPARAM for a non-OUTLET link.

◆ swmm_link_get_outlet_rating_type()

SWMM_ENGINE_API int swmm_link_get_outlet_rating_type	(	SWMM_Engine	engine,
		int	idx,
		int *	type )

Read the outlet rating selector.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	type	Optional destination. 0=FUNCTIONAL_HEAD, 1=FUNCTIONAL_DEPTH, 2=TABULAR_HEAD, 3=TABULAR_DEPTH.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_BADPARAM for a non-OUTLET link.

◆ swmm_link_get_pump_curve()

SWMM_ENGINE_API int swmm_link_get_pump_curve	(	SWMM_Engine	engine,
		int	idx,
		int *	curve_idx )

Get the pump curve index assigned to a pump link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	curve_idx	Receives the curve index.

Returns: SWMM_OK on success, or an error code.

Note: curve_idx may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_pump_init_state()

SWMM_ENGINE_API int swmm_link_get_pump_init_state	(	SWMM_Engine	engine,
		int	idx,
		int *	on )

Get the initial on/off state of a pump.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	on	Receives 1 if initially ON, 0 if OFF.

Returns: SWMM_OK on success, or an error code.

Note: on may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_pump_shutoff_depth()

SWMM_ENGINE_API int swmm_link_get_pump_shutoff_depth	(	SWMM_Engine	engine,
		int	idx,
		double *	depth )

Read the pump shutoff depth.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	depth	Optional destination. Project display length (ft US, m SI);

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_BADPARAM for a non-PUMP link.

◆ swmm_link_get_pump_startup_depth()

SWMM_ENGINE_API int swmm_link_get_pump_startup_depth	(	SWMM_Engine	engine,
		int	idx,
		double *	depth )

Read the pump startup depth.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	depth	Optional destination. Project display length (ft US, m SI);

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_BADPARAM for a non-PUMP link.

◆ swmm_link_get_pump_stats_bulk()

SWMM_ENGINE_API int swmm_link_get_pump_stats_bulk	(	SWMM_Engine	engine,
		int *	cycles,
		double *	on_time,
		double *	volume,
		int	count )

Get pump utilization statistics for all links in a single call.

Single-pass bulk accessor that avoids N round-trips through the C ABI when caller needs pump stats across the network (e.g. when building a network-wide pump summary report). For links whose type is not LinkType::PUMP, the corresponding cycles entry is set to -1 and the on_time / volume entries to 0.0 — this allows the caller to distinguish "non-pump" from "pump with zero cycles".

Any of cycles, on_time, volume may be NULL if the caller does not need that output; the function still iterates the full link array (the cost is identical) but skips the store.

Parameters

[in]	engine	Engine handle (must be in INITIALIZED state or later so the statistics vectors are sized).
[out]	cycles	Caller-allocated `int` buffer of at least `count` entries, or `NULL`. Non-pump links get `-1`.
[out]	on_time	Caller-allocated `double` buffer of at least `count` entries (seconds), or `NULL`.
[out]	volume	Caller-allocated `double` buffer of at least `count` entries (ft3), or `NULL`.
[in]	count	Length of the caller-allocated buffers. If smaller than the link count, only the first `min(count, n_links)` entries are written.

Returns: SWMM_OK on success; SWMM_ERR_BADHANDLE if engine is invalid; SWMM_ERR_BADPARAM if count is non-positive or all three output pointers are NULL.

Example: int n = swmm_link_count(eng);

int* cycles = malloc(n * sizeof(int));

double* on_time = malloc(n * sizeof(double));

double* volume = malloc(n * sizeof(double));

swmm_link_get_pump_stats_bulk(eng, cycles, on_time, volume, n);

for (int i = 0; i < n; ++i) {

if (cycles[i] < 0) continue; // not a pump

printf("link %d: %d cycles, %.1f s, %.2f ft3\n",

i, cycles[i], on_time[i], volume[i]);

}

swmm_link_count
SWMM_ENGINE_API int swmm_link_count(SWMM_Engine engine)
Get the total number of links in the model.
Definition openswmm_links_impl.cpp:118

swmm_link_get_pump_stats_bulk
SWMM_ENGINE_API int swmm_link_get_pump_stats_bulk(SWMM_Engine engine, int *cycles, double *on_time, double *volume, int count)
Get pump utilization statistics for all links in a single call.
Definition openswmm_links_impl.cpp:1866

Note: Equivalent to calling swmm_link_get_stat_pump_cycles, swmm_link_get_stat_pump_on_time, and swmm_link_get_stat_pump_volume for every link, but with one C ABI crossing instead of 3N.

See also: swmm_link_get_stat_pump_cycles; swmm_link_get_stat_pump_on_time; swmm_link_get_stat_pump_volume

Since: 6.0.0

Note: cycles may be NULL to suppress that output. on_time may be NULL to suppress that output. volume may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. All three output arrays NULL or count<=0 returns SWMM_ERR_BADPARAM. Copies min(count,link count) rows; uninitialized statistics are reported with the same non-pump sentinels.

◆ swmm_link_get_quality()

SWMM_ENGINE_API int swmm_link_get_quality	(	SWMM_Engine	engine,
		int	link_idx,
		int	pollutant_idx,
		double *	conc )

Get the pollutant concentration in a link.

Parameters

[in]	engine	Engine handle.
[in]	link_idx	Zero-based link index.
[in]	pollutant_idx	Zero-based pollutant index.
[out]	conc	Receives the concentration in pollutant units.

Returns: SWMM_OK on success, or an error code.

Note: conc may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_quality_bulk()

SWMM_ENGINE_API int swmm_link_get_quality_bulk	(	SWMM_Engine	engine,
		int	pollutant_idx,
		double *	buf,
		int	count )

Get pollutant concentrations for all links for one pollutant.

Parameters

[in]	engine	Engine handle.
[in]	pollutant_idx	Zero-based pollutant index.
[out]	buf	Caller-allocated buffer of at least `count` doubles.
[in]	count	Number of elements (should equal swmm_link_count()).

Returns: SWMM_OK on success, or an error code.

Note: A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Copies min(count,link count) records and leaves any buffer tail unchanged.

◆ swmm_link_get_roughness()

SWMM_ENGINE_API int swmm_link_get_roughness	(	SWMM_Engine	engine,
		int	idx,
		double *	n )

Get the Manning's roughness coefficient.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	n	Receives the Manning's n value.

Returns: SWMM_OK on success, or an error code.

Note: n may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_seep_rate()

SWMM_ENGINE_API int swmm_link_get_seep_rate	(	SWMM_Engine	engine,
		int	idx,
		double *	rate )

Get the seepage loss rate for a conduit.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	rate	Receives the seepage rate.

Returns: SWMM_OK on success, or an error code.

Note: rate may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_slope()

SWMM_ENGINE_API int swmm_link_get_slope	(	SWMM_Engine	engine,
		int	idx,
		double *	slope )

Get the computed slope of a conduit.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	slope	Receives the slope (dimensionless, rise/run).

Returns: SWMM_OK on success, or an error code.

Note: slope may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_slot_volume()

SWMM_ENGINE_API int swmm_link_get_slot_volume	(	SWMM_Engine	engine,
		int	idx,
		double *	volume )

Get the portion of a link's stored volume held in the Preissmann slot.

Finite-volume routing only: the water standing above the pipe crown in the slot (sum over cells of max(0, A - A_crown) * dx). Always a subset of swmm_link_get_volume; reads 0.0 under the dynamic-wave router and whenever the conduit is below its crown.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	volume	Receives the slot volume in project volume units.

Returns: SWMM_OK on success, or an error code.

Note: volume may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_stat_max_filling()

SWMM_ENGINE_API int swmm_link_get_stat_max_filling	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Get the maximum depth/full-depth ratio (filling) in a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	val	Receives the maximum filling ratio.

Returns: SWMM_OK on success, or an error code.

Note: val may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_stat_max_flow()

SWMM_ENGINE_API int swmm_link_get_stat_max_flow	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Get the maximum flow recorded in a link during the simulation.

Parameters

[in]	engine	Engine handle (ENDED or RUNNING state).
[in]	idx	Zero-based link index.
[out]	val	Receives the maximum flow in project flow units.

Returns: SWMM_OK on success, or an error code.

Note: val may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_stat_max_velocity()

SWMM_ENGINE_API int swmm_link_get_stat_max_velocity	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Get the maximum velocity recorded in a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	val	Receives the maximum velocity in project velocity units.

Returns: SWMM_OK on success, or an error code.

Note: val may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_stat_peak_slot_share()

SWMM_ENGINE_API int swmm_link_get_stat_peak_slot_share	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Read a link peak instantaneous numerical-slot storage share.

Recorded by FV routing; zero under dynamic-wave routing.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	val	Optional destination in dimensionless ratio, normally [0,1].

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index.

◆ swmm_link_get_stat_pump_cycles()

SWMM_ENGINE_API int swmm_link_get_stat_pump_cycles	(	SWMM_Engine	engine,
		int	idx,
		int *	cycles )

Read a link recorded pump on/off cycle count.

Does not reject non-pumps; it reads the link statistics column directly.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	cycles	Optional destination in integer count.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index.

◆ swmm_link_get_stat_pump_on_time()

SWMM_ENGINE_API int swmm_link_get_stat_pump_on_time	(	SWMM_Engine	engine,
		int	idx,
		double *	seconds )

Read a link recorded pump on-duration.

Does not reject non-pumps; use link type or bulk sentinel outputs when classifying rows.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	seconds	Optional destination in seconds.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index.

◆ swmm_link_get_stat_pump_volume()

SWMM_ENGINE_API int swmm_link_get_stat_pump_volume	(	SWMM_Engine	engine,
		int	idx,
		double *	volume )

Read a link recorded pumped water volume.

Converts internal ft3 to display volume; does not reject non-pumps.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	volume	Optional destination in project display volume units.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index.

◆ swmm_link_get_stat_slot_share()

SWMM_ENGINE_API int swmm_link_get_stat_slot_share	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Read a link time-integrated numerical-slot storage share.

Computes integral(slot volume dt)/integral(stored volume dt), returning zero when the denominator is nonpositive.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	val	Optional destination in dimensionless ratio, normally [0,1].

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index.

◆ swmm_link_get_stat_surcharge_time()

SWMM_ENGINE_API int swmm_link_get_stat_surcharge_time	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Get the total surcharge duration for a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	val	Receives the surcharge duration in seconds.

Returns: SWMM_OK on success, or an error code.

Note: val may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_stat_vol_flow()

SWMM_ENGINE_API int swmm_link_get_stat_vol_flow	(	SWMM_Engine	engine,
		int	idx,
		double *	val )

Get the total volume conveyed through a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	val	Receives the total volume in project volume units.

Returns: SWMM_OK on success, or an error code.

Note: val may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_tag()

SWMM_ENGINE_API int swmm_link_get_tag	(	SWMM_Engine	engine,
		int	idx,
		char *	buf,
		int	buflen )

Copy a link free-form tag.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	buf	Non-null caller-owned destination, empty when no tag exists; NUL-terminated and silently truncated to buflen-1 bytes.
[in]	buflen	Positive byte capacity including NUL.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_BADPARAM for null buf/nonpositive capacity.

◆ swmm_link_get_target_setting()

SWMM_ENGINE_API int swmm_link_get_target_setting	(	SWMM_Engine	engine,
		int	idx,
		double *	setting )

Read the stored link target control setting.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[out]	setting	Optional dimensionless setting destination; no clamping is applied on read.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index.

◆ swmm_link_get_target_settings_bulk()

SWMM_ENGINE_API int swmm_link_get_target_settings_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Copy target control settings for a prefix of the link table.

Reads stored target_setting values without clamping.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[out]	buf	Non-null caller-owned array of count doubles in dimensionless.
[in]	count	Positive capacity/requested prefix length; writes min(count,link count) entries and leaves the tail unchanged.

Returns: SWMM_OK, including partial prefix reads; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null buf/count<=0.

◆ swmm_link_get_to_node()

SWMM_ENGINE_API int swmm_link_get_to_node	(	SWMM_Engine	engine,
		int	idx,
		int *	node_idx )

Get the downstream (outlet) node index of a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	node_idx	Receives the downstream node index.

Returns: SWMM_OK on success, or an error code.

Note: node_idx may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_type()

SWMM_ENGINE_API int swmm_link_get_type	(	SWMM_Engine	engine,
		int	idx,
		int *	type )

Get the type of a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	type	Receives the link type (see SWMM_LinkType).

Returns: SWMM_OK on success, or an error code.

Note: type may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_velocities_bulk()

SWMM_ENGINE_API int swmm_link_get_velocities_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Evaluate conveyance velocities for a prefix of links.

Uses the true cross-section area at published depth, clamps above-crown depth to full conveyance depth and splits aggregate conduit flow across barrels. Numerical-slot area does not dilute conveyance velocity. Matches swmm_link_get_velocity().

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[out]	buf	Non-null caller-owned count-double array in project display length per second (ft/s US, m/s SI).
[in]	count	Positive capacity/requested prefix length; writes min(count,link count) entries and leaves the tail unchanged.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null buf/count<=0.

Here is the call graph for this function:

◆ swmm_link_get_velocity()

SWMM_ENGINE_API int swmm_link_get_velocity	(	SWMM_Engine	engine,
		int	idx,
		double *	velocity )

Get the current flow velocity in a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	velocity	Receives the velocity in project velocity units.

Returns: SWMM_OK on success, or an error code.

Note: velocity may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

Here is the call graph for this function:

◆ swmm_link_get_volume()

SWMM_ENGINE_API int swmm_link_get_volume	(	SWMM_Engine	engine,
		int	idx,
		double *	volume )

Get the current water volume stored in a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	volume	Receives the volume in project volume units.

Returns: SWMM_OK on success, or an error code.

Note: volume may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_volumes_bulk()

SWMM_ENGINE_API int swmm_link_get_volumes_bulk	(	SWMM_Engine	engine,
		double *	buf,
		int	count )

Copy current stored water volumes for a prefix of the link table.

Converts every stored volume from internal units; this is not a raw memcpy in SI projects.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[out]	buf	Non-null caller-owned array of count doubles in project display volume units.
[in]	count	Positive capacity/requested prefix length; writes min(count,link count) entries and leaves the tail unchanged.

Returns: SWMM_OK, including partial prefix reads; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null buf/count<=0.

◆ swmm_link_get_weir_type()

SWMM_ENGINE_API int swmm_link_get_weir_type	(	SWMM_Engine	engine,
		int	idx,
		int *	type )

Get the weir flow classification.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	type	Receives the weir type (see SWMM_WeirType).

Returns: SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-weir link.

Since: 6.0.0 (engine gap BN-LINK-03, added 2026-05-25)

Note: type may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_get_xsect()

SWMM_ENGINE_API int swmm_link_get_xsect	(	SWMM_Engine	engine,
		int	idx,
		int *	shape,
		double *	geom1,
		double *	geom2,
		double *	geom3,
		double *	geom4 )

Get the cross-section geometry for a conduit link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[out]	shape	Receives the shape code (see SWMM_XSectShape).
[out]	geom1	Receives the primary dimension.
[out]	geom2	Receives the secondary dimension.
[out]	geom3	Receives the tertiary dimension.
[out]	geom4	Receives the quaternary dimension.

Returns: SWMM_OK on success, or an error code.

Note: shape may be NULL to suppress that output. geom1 may be NULL to suppress that output. geom2 may be NULL to suppress that output. geom3 may be NULL to suppress that output. geom4 may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX. STREET geom1 is the referenced street index (or -1), with other geometry outputs zero. IRREGULAR geom1 is the transect index; retained geom2-4 are returned. Ordinary shapes prefer retained raw authoring; absent raw geom1 falls back to derived depth/width/area, so geom3 in that fallback is area rather than the original input field.

Here is the call graph for this function:

◆ swmm_link_id()

SWMM_ENGINE_API const char * swmm_link_id	(	SWMM_Engine	engine,
		int	idx )

Get the string identifier of a link by index.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.

Returns: Null-terminated string owned by the engine, or NULL on error.

Note: Borrowed ID storage may be invalidated by name/topology edits, close/reopen or engine destruction; copy before retaining it across operations.

◆ swmm_link_index()

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

Look up a link's zero-based index by its string identifier.

Parameters

[in]	engine	Engine handle.
[in]	id	Null-terminated link identifier.

Returns: Zero-based index, or -1 if not found.

◆ swmm_link_pop_last()

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

Remove the most recently added link (undo-of-add).

Pops the tail of the link list. The engine must be in SWMM_STATE_BUILDING or SWMM_STATE_OPENED. Returns SWMM_ERR_BADINDEX if the tail doesn't match id, or SWMM_ERR_LIFECYCLE if the state is wrong.

As with swmm_node_pop_last, this is the narrow "rollback-of-add" surface; a general swmm_link_remove(idx) requires renumbering every reference (controls, reports, etc.) and is tracked separately.

Parameters

[in]	engine	Engine handle.
[in]	id	Expected tail identifier (null-terminated).

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE.

◆ swmm_link_rename()

SWMM_ENGINE_API int swmm_link_rename	(	SWMM_Engine	engine,
		int	idx,
		const char *	newId )

Rename an editable link in its name index.

Numeric link indices are retained. Borrowed ID pointers may be invalidated; this wrapper does not rewrite arbitrary stored text references.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[in]	newId	Non-null, nonempty NUL-terminated unique ID, copied internally.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED or SWMM_ERR_BADPARAM for null/empty/duplicate ID.

◆ swmm_link_set_barrels()

SWMM_ENGINE_API int swmm_link_set_barrels	(	SWMM_Engine	engine,
		int	idx,
		int	n )

Set the number of parallel barrels in a conduit.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	n	Number of barrels (>= 1).

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_closed()

SWMM_ENGINE_API int swmm_link_set_closed	(	SWMM_Engine	engine,
		int	idx,
		int	closed )

Open or close a link.

Parameters

[in]	engine	Engine handle (RUNNING state).
[in]	idx	Link index.
[in]	closed	Non-zero to close; zero to open.

Note: Requires RUNNING; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_control_setting()

SWMM_ENGINE_API int swmm_link_set_control_setting	(	SWMM_Engine	engine,
		int	idx,
		double	setting )

Assign a link current control setting directly during a run.

Does not remove control rules or install a permanent override; subsequent control/actuator evaluation can change effective values.

Parameters

[in]	engine	Non-null RUNNING engine.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[in]	setting	Dimensionless setting, conventionally 0..1 for full opening/speed. Stored without clamping or finite/range validation.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_LIFECYCLE outside RUNNING.

◆ swmm_link_set_crest_height()

SWMM_ENGINE_API int swmm_link_set_crest_height	(	SWMM_Engine	engine,
		int	idx,
		double	h )

Set the crest height for a weir link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index (must be SWMM_LINK_WEIR).
[in]	h	Crest height in project length units.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

Here is the call graph for this function:

◆ swmm_link_set_culvert_code()

SWMM_ENGINE_API int swmm_link_set_culvert_code	(	SWMM_Engine	engine,
		int	idx,
		int	code )

Set the FHWA culvert inlet geometry code.

Used for computing inlet-controlled culvert flow. Code values correspond to FHWA HDS-5 chart numbers (0 = not a culvert).

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	code	Culvert code (0 = none).

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_discharge_coeff()

SWMM_ENGINE_API int swmm_link_set_discharge_coeff	(	SWMM_Engine	engine,
		int	idx,
		double	cd )

Set the discharge coefficient for a weir link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index (must be SWMM_LINK_WEIR).
[in]	cd	Discharge coefficient (dimensionless).

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_end_contractions()

SWMM_ENGINE_API int swmm_link_set_end_contractions	(	SWMM_Engine	engine,
		int	idx,
		double	n )

Set the number of end contractions for a weir link.

End contractions reduce the effective crest length. Typical values are 0, 1, or 2 for standard weir configurations.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index (must be SWMM_LINK_WEIR).
[in]	n	Number of end contractions.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_flap_gate()

SWMM_ENGINE_API int swmm_link_set_flap_gate	(	SWMM_Engine	engine,
		int	idx,
		int	has_gate )

Set whether a flap gate exists on a link.

A flap gate prevents reverse flow through the link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	has_gate	Non-zero to enable; zero to disable.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_flow()

SWMM_ENGINE_API int swmm_link_set_flow	(	SWMM_Engine	engine,
		int	idx,
		double	flow )

Set the flow rate in a link (runtime override).

Parameters

[in]	engine	Engine handle (RUNNING state).
[in]	idx	Zero-based link index.
[in]	flow	New flow in project flow units.

Returns: SWMM_OK on success, or an error code.

Note: Requires RUNNING; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_flows_bulk()

SWMM_ENGINE_API int swmm_link_set_flows_bulk	(	SWMM_Engine	engine,
		const double *	buf,
		int	count )

Set flow rates for all links in a single call (runtime override).

Parameters

[in]	engine	Engine handle (RUNNING state).
[in]	buf	Array of flow values, one per link.
[in]	count	Number of elements.

Returns: SWMM_OK on success, or an error code.

Note: Requires RUNNING; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A null buffer or nonpositive count returns SWMM_ERR_BADPARAM. Copies min(count,link count) records and leaves any buffer tail unchanged.

◆ swmm_link_set_initial_flow()

SWMM_ENGINE_API int swmm_link_set_initial_flow	(	SWMM_Engine	engine,
		int	idx,
		double	flow )

Set the initial flow in a link at simulation start.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	flow	Initial flow in project flow units.

Returns: SWMM_OK on success, or an error code.

Note: Sets the authored initial flow (the [CONDUITS] InitFlow column), which swmm_link_get_initial_flow() reads, the .inp writer saves and initialization turns into the starting flow, depth and volume. Requires BUILDING or OPENED: after initialization the starting state already exists, so other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_length()

SWMM_ENGINE_API int swmm_link_set_length	(	SWMM_Engine	engine,
		int	idx,
		double	length )

Set the conduit length.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	length	Conduit length in project length units.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_loss_coeff()

SWMM_ENGINE_API int swmm_link_set_loss_coeff	(	SWMM_Engine	engine,
		int	idx,
		double	inlet,
		double	outlet,
		double	avg )

Set entry, exit, and average loss coefficients for a conduit.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index (must be SWMM_LINK_CONDUIT).
[in]	inlet	Inlet (entry) loss coefficient.
[in]	outlet	Outlet (exit) loss coefficient.
[in]	avg	Average loss coefficient along the conduit length.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_max_flow()

SWMM_ENGINE_API int swmm_link_set_max_flow	(	SWMM_Engine	engine,
		int	idx,
		double	flow )

Set the maximum allowable flow in a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	flow	Maximum flow in project flow units (0 = no limit).

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_nodes()

SWMM_ENGINE_API int swmm_link_set_nodes	(	SWMM_Engine	engine,
		int	idx,
		int	from_node_idx,
		int	to_node_idx )

Set the upstream and downstream nodes of a link.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	from_node_idx	Zero-based index of the upstream (inlet) node.
[in]	to_node_idx	Zero-based index of the downstream (outlet) node.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX. The endpoint indices are stored without individual node-bound checks; supply existing node indices before validation/initialization.

◆ swmm_link_set_offset_dn()

SWMM_ENGINE_API int swmm_link_set_offset_dn	(	SWMM_Engine	engine,
		int	idx,
		double	offset )

Set the downstream (outlet) offset above the downstream node invert.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	offset	Offset in project length units.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX. Offsets use authored values; the internal sediment-depth bump for FILLED_CIRCULAR sections is added/removed at this boundary.

◆ swmm_link_set_offset_up()

SWMM_ENGINE_API int swmm_link_set_offset_up	(	SWMM_Engine	engine,
		int	idx,
		double	offset )

Set the upstream (inlet) offset above the upstream node invert.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	offset	Offset in project length units.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX. Offsets use authored values; the internal sediment-depth bump for FILLED_CIRCULAR sections is added/removed at this boundary.

Here is the caller graph for this function:

◆ swmm_link_set_orifice_open_close_rate()

SWMM_ENGINE_API int swmm_link_set_orifice_open_close_rate	(	SWMM_Engine	engine,
		int	idx,
		double	rate )

Set the orifice open/close rate on an editable orifice link.

Copies the field into its subtype storage. Does not convert the link type or validate associated curves/other settings.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[in]	rate	Fraction of full opening per second, with 0 meaning instantaneous. This API takes a rate rather than the legacy editor time in hours; no finite/range validation is imposed.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED; SWMM_ERR_BADPARAM for the wrong link type.

◆ swmm_link_set_orifice_type()

SWMM_ENGINE_API int swmm_link_set_orifice_type	(	SWMM_Engine	engine,
		int	idx,
		int	type )

Set the orifice flow-attack classification (SIDE / BOTTOM).

Only valid on links of type SWMM_LINK_ORIFICE; returns SWMM_ERR_BADPARAM otherwise.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	type	Orifice type (see SWMM_OrificeType).

Returns: SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-orifice link or type is out of range.

Since: 6.0.0 (engine gap BN-LINK-02, added 2026-05-25)

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_outlet_expon()

SWMM_ENGINE_API int swmm_link_set_outlet_expon	(	SWMM_Engine	engine,
		int	idx,
		double	expon )

Set the outlet functional-rating exponent on an editable outlet link.

Copies the field into its subtype storage. Does not convert the link type or validate associated curves/other settings.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[in]	expon	Dimensionless exponent; retained but not used for tabular rating types. No finite/range validation is imposed.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED; SWMM_ERR_BADPARAM for the wrong link type.

◆ swmm_link_set_outlet_rating_type()

SWMM_ENGINE_API int swmm_link_set_outlet_rating_type	(	SWMM_Engine	engine,
		int	idx,
		int	type )

Set the outlet rating selector on an editable outlet link.

Copies the field into its subtype storage. Does not convert the link type or validate associated curves/other settings.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[in]	type	0=FUNCTIONAL_HEAD, 1=FUNCTIONAL_DEPTH, 2=TABULAR_HEAD, 3=TABULAR_DEPTH.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED; SWMM_ERR_BADPARAM for the wrong link type or selector outside 0..3.

◆ swmm_link_set_pump_curve()

SWMM_ENGINE_API int swmm_link_set_pump_curve	(	SWMM_Engine	engine,
		int	idx,
		int	curve_idx )

Assign a pump curve to a pump link.

The curve defines the relationship between head (or volume or depth) and pump flow rate.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index (must be SWMM_LINK_PUMP).
[in]	curve_idx	Zero-based curve index (from swmm_curve_add()).

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_pump_init_state()

SWMM_ENGINE_API int swmm_link_set_pump_init_state	(	SWMM_Engine	engine,
		int	idx,
		int	on )

Set the initial on/off state of a pump at simulation start.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index (must be SWMM_LINK_PUMP).
[in]	on	Non-zero for ON; zero for OFF.

Returns: SWMM_OK on success, or an error code.

Note: Permitted in BUILDING, OPENED or INITIALIZED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_pump_shutoff_depth()

SWMM_ENGINE_API int swmm_link_set_pump_shutoff_depth	(	SWMM_Engine	engine,
		int	idx,
		double	depth )

Set the pump shutoff depth on an editable pump link.

Copies the field into its subtype storage. Does not convert the link type or validate associated curves/other settings.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[in]	depth	Project display length (ft US, m SI); no finite/nonnegative validation is imposed.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED; SWMM_ERR_BADPARAM for the wrong link type.

◆ swmm_link_set_pump_startup_depth()

SWMM_ENGINE_API int swmm_link_set_pump_startup_depth	(	SWMM_Engine	engine,
		int	idx,
		double	depth )

Set the pump startup depth on an editable pump link.

Copies the field into its subtype storage. Does not convert the link type or validate associated curves/other settings.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[in]	depth	Project display length (ft US, m SI); no finite/nonnegative validation is imposed.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED; SWMM_ERR_BADPARAM for the wrong link type.

◆ swmm_link_set_roughness()

SWMM_ENGINE_API int swmm_link_set_roughness	(	SWMM_Engine	engine,
		int	idx,
		double	n )

Set the Manning's roughness coefficient.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	n	Manning's n value.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

Here is the call graph for this function:

◆ swmm_link_set_seep_rate()

SWMM_ENGINE_API int swmm_link_set_seep_rate	(	SWMM_Engine	engine,
		int	idx,
		double	rate )

Set the seepage loss rate for a conduit.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	rate	Seepage rate in project length/time units.

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_tag()

SWMM_ENGINE_API int swmm_link_set_tag	(	SWMM_Engine	engine,
		int	idx,
		const char *	tag )

Copy or clear a link free-form tag.

No lifecycle guard is imposed. Tags are keyed by link index and persist through rename.

Parameters

[in]	engine	Non-null live engine handle; caller provides exclusive access.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[in]	tag	Borrowed NUL-terminated text to copy; NULL/empty clears it.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index.

◆ swmm_link_set_target_setting()

SWMM_ENGINE_API int swmm_link_set_target_setting	(	SWMM_Engine	engine,
		int	idx,
		double	setting )

Assign a link target control setting directly during a run.

Does not remove control rules or install a permanent override; subsequent control/actuator evaluation can change effective values.

Parameters

[in]	engine	Non-null RUNNING engine.
[in]	idx	Zero-based existing link index in [0,swmm_link_count(engine)).
[in]	setting	Dimensionless setting, conventionally 0..1 for full opening/speed. Stored without clamping or finite/range validation.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid link index. SWMM_ERR_LIFECYCLE outside RUNNING.

◆ swmm_link_set_weir_type()

SWMM_ENGINE_API int swmm_link_set_weir_type	(	SWMM_Engine	engine,
		int	idx,
		int	type )

Set the weir flow classification.

Only valid on links of type SWMM_LINK_WEIR; returns SWMM_ERR_BADPARAM otherwise.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	type	Weir type (see SWMM_WeirType).

Returns: SWMM_OK on success, SWMM_ERR_BADPARAM if idx names a non-weir link or type is out of range.

Since: 6.0.0 (engine gap BN-LINK-03, added 2026-05-25)

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX.

◆ swmm_link_set_xsect()

SWMM_ENGINE_API int swmm_link_set_xsect	(	SWMM_Engine	engine,
		int	idx,
		int	shape,
		double	geom1,
		double	geom2,
		double	geom3,
		double	geom4 )

Set the cross-section geometry for a conduit link.

The meaning of geom1–geom4 depends on the shape; see SWMM_XSectShape for per-shape documentation.

Parameters

[in]	engine	Engine handle.
[in]	idx	Zero-based link index.
[in]	shape	Cross-section shape code (see SWMM_XSectShape).
[in]	geom1	Primary geometry parameter (usually height or diameter).
[in]	geom2	Secondary geometry parameter (usually width).
[in]	geom3	Tertiary geometry parameter (shape-dependent).
[in]	geom4	Quaternary geometry parameter (shape-dependent).

Returns: SWMM_OK on success, or an error code.

Note: Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed link/pollutant index check returns SWMM_ERR_BADINDEX. Some reference-validation failures occur after shape/raw geometry fields have been assigned; this edit is not uniformly atomic. STREET/IRREGULAR geom1 is a store index, not a length. Unsupported shapes use the implementation generic geometry fallback.

Here is the call graph for this function:

◆ swmm_links_restore_authored_orientation()

SWMM_ENGINE_API int swmm_links_restore_authored_orientation	(	SWMM_Engine	engine,
		int *	count )

Restore authored From/To orientation on every conduit the parser reversed for adverse slope (DYNWAVE/FV routing).

At open, adverse-slope conduits have node1/node2, offset1/offset2, initial flow sign and inlet/outlet losses swapped in place. An editing host that displays and saves the live context should call this once after open so the user sees and edits the orientation they authored. Not needed for simulation-only hosts. The .inp writer undoes the reversal on its own regardless.

Parameters

[in]	engine	Engine handle.
[out]	count	Optional; receives the number of conduits restored.

Returns: SWMM_OK on success, or an error code.

Note: count may be NULL to suppress that output. Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE.

Here is the call graph for this function:

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ SWMM_LinkType

◆ SWMM_OrificeType

◆ SWMM_OutletRatingType

◆ SWMM_WeirType

◆ SWMM_XSectShape

Enumeration Type Documentation

◆ SWMM_LinkType

◆ SWMM_OrificeType

◆ SWMM_OutletRatingType

◆ SWMM_WeirType

◆ SWMM_XSectShape

Function Documentation

◆ swmm_link_add()

◆ swmm_link_count()

◆ swmm_link_get_barrels()

◆ swmm_link_get_capacities_bulk()

◆ swmm_link_get_capacity()

◆ swmm_link_get_closed()

◆ swmm_link_get_control_setting()

◆ swmm_link_get_control_settings_bulk()

◆ swmm_link_get_crest_height()

◆ swmm_link_get_culvert_code()

◆ swmm_link_get_depth()

◆ swmm_link_get_depths_bulk()

◆ swmm_link_get_discharge_coeff()

◆ swmm_link_get_end_contractions()

◆ swmm_link_get_flap_gate()

◆ swmm_link_get_flow()

◆ swmm_link_get_flows_bulk()

◆ swmm_link_get_from_node()

◆ swmm_link_get_hyd_power()

◆ swmm_link_get_hyd_powers_bulk()

◆ swmm_link_get_ids_bulk()

◆ swmm_link_get_initial_flow()

◆ swmm_link_get_length()

◆ swmm_link_get_loss_coeff()

◆ swmm_link_get_max_flow()

◆ swmm_link_get_offset_dn()

◆ swmm_link_get_offset_up()

◆ swmm_link_get_orifice_open_close_rate()

◆ swmm_link_get_orifice_type()

◆ swmm_link_get_outlet_expon()

◆ swmm_link_get_outlet_rating_type()

◆ swmm_link_get_pump_curve()

◆ swmm_link_get_pump_init_state()

◆ swmm_link_get_pump_shutoff_depth()

◆ swmm_link_get_pump_startup_depth()

◆ swmm_link_get_pump_stats_bulk()

◆ swmm_link_get_quality()

◆ swmm_link_get_quality_bulk()

◆ swmm_link_get_roughness()

◆ swmm_link_get_seep_rate()

◆ swmm_link_get_slope()

◆ swmm_link_get_slot_volume()

◆ swmm_link_get_stat_max_filling()

◆ swmm_link_get_stat_max_flow()

◆ swmm_link_get_stat_max_velocity()

◆ swmm_link_get_stat_peak_slot_share()

◆ swmm_link_get_stat_pump_cycles()

◆ swmm_link_get_stat_pump_on_time()

◆ swmm_link_get_stat_pump_volume()

◆ swmm_link_get_stat_slot_share()

◆ swmm_link_get_stat_surcharge_time()

◆ swmm_link_get_stat_vol_flow()

◆ swmm_link_get_tag()

◆ swmm_link_get_target_setting()

◆ swmm_link_get_target_settings_bulk()

◆ swmm_link_get_to_node()

◆ swmm_link_get_type()

◆ swmm_link_get_velocities_bulk()

◆ swmm_link_get_velocity()

◆ swmm_link_get_volume()

◆ swmm_link_get_volumes_bulk()

◆ swmm_link_get_weir_type()

◆ swmm_link_get_xsect()