OpenSWMM Engine  6.0.0-alpha.1
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.1)
Loading...
Searching...
No Matches
openswmm_infrastructure_impl.cpp File Reference

C API implementation — transects, streets, inlets, LID controls, LID usage. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_infrastructure.h"
#include <cctype>
#include <string>
Include dependency graph for openswmm_infrastructure_impl.cpp:

Functions

SWMM_ENGINE_API int swmm_transect_add (SWMM_Engine engine, const char *id)
 Add a new transect for irregular cross-sections.
 
SWMM_ENGINE_API int swmm_transect_set_roughness (SWMM_Engine engine, int idx, double n_left, double n_right, double n_channel)
 Set Manning's roughness for left overbank, right overbank, and channel.
 
SWMM_ENGINE_API int swmm_transect_add_station (SWMM_Engine engine, int idx, double station, double elevation)
 Add a station–elevation data point to a transect.
 
SWMM_ENGINE_API int swmm_transect_count (SWMM_Engine engine)
 Get the total number of transects in the model.
 
SWMM_ENGINE_API int swmm_transect_index (SWMM_Engine engine, const char *id)
 Look up a transect's zero-based index by its string identifier.
 
SWMM_ENGINE_API const char * swmm_transect_id (SWMM_Engine engine, int idx)
 Get the string identifier of a transect by index.
 
SWMM_ENGINE_API int swmm_transect_get_roughness (SWMM_Engine engine, int idx, double *n_left, double *n_right, double *n_channel)
 Get the Manning's roughness values for a transect.
 
SWMM_ENGINE_API int swmm_transect_set_bank_stations (SWMM_Engine engine, int idx, double x_left, double x_right)
 Set the left and right bank stations for a transect.
 
SWMM_ENGINE_API int swmm_transect_get_bank_stations (SWMM_Engine engine, int idx, double *x_left, double *x_right)
 Get the left and right bank stations for a transect.
 
SWMM_ENGINE_API int swmm_transect_set_encroachment_stations (SWMM_Engine engine, int idx, double x_left, double x_right)
 Set the left and right encroachment stations for a transect (BQ-TR-02).
 
SWMM_ENGINE_API int swmm_transect_get_encroachment_stations (SWMM_Engine engine, int idx, double *x_left, double *x_right)
 Get the left and right encroachment stations for a transect (BQ-TR-02).
 
SWMM_ENGINE_API int swmm_transect_set_modifiers (SWMM_Engine engine, int idx, double x_factor, double y_factor, double length_factor)
 Set the station, elevation, and meander modifiers for a transect.
 
SWMM_ENGINE_API int swmm_transect_get_modifiers (SWMM_Engine engine, int idx, double *x_factor, double *y_factor, double *length_factor)
 Get the station, elevation, and meander modifiers for a transect.
 
SWMM_ENGINE_API int swmm_transect_set_comments (SWMM_Engine engine, int idx, const char *text)
 Set the free-form comments / description for a transect.
 
SWMM_ENGINE_API int swmm_transect_get_comments (SWMM_Engine engine, int idx, char *buf, int buflen)
 Get the free-form comments / description for a transect.
 
SWMM_ENGINE_API int swmm_transect_get_station_count (SWMM_Engine engine, int idx)
 Get the number of station–elevation points stored for a transect.
 
SWMM_ENGINE_API int swmm_transect_get_station (SWMM_Engine engine, int idx, int station_idx, double *station, double *elevation)
 Get a single station–elevation pair from a transect.
 
SWMM_ENGINE_API int swmm_transect_clear_stations (SWMM_Engine engine, int idx)
 Remove all station–elevation pairs from a transect.
 
SWMM_ENGINE_API int swmm_transect_rename (SWMM_Engine engine, int idx, const char *new_id)
 Rename an existing transect.
 
SWMM_ENGINE_API int swmm_transect_remove (SWMM_Engine engine, int idx)
 Remove a transect by index.
 
SWMM_ENGINE_API int swmm_street_add (SWMM_Engine engine, const char *id)
 Add a new street cross-section definition.
 
SWMM_ENGINE_API int swmm_street_set_params (SWMM_Engine engine, int idx, double t_crown, double h_curb, double sx, double n_road, double gutter_depres, double gutter_width, int sides, double back_width, double back_slope, double back_n)
 Set the geometric parameters for a street cross-section.
 
SWMM_ENGINE_API int swmm_street_count (SWMM_Engine engine)
 Get the total number of street definitions in the model.
 
SWMM_ENGINE_API int swmm_street_index (SWMM_Engine engine, const char *id)
 Look up a street's zero-based index by its string identifier.
 
SWMM_ENGINE_API const char * swmm_street_id (SWMM_Engine engine, int idx)
 Get the string identifier of a street by index.
 
SWMM_ENGINE_API int swmm_inlet_add (SWMM_Engine engine, const char *id, const char *type)
 Add a new inlet definition.
 
SWMM_ENGINE_API int swmm_inlet_set_params (SWMM_Engine engine, int idx, double length, double width, const char *grate_type, double open_area, double splash_veloc)
 Set the geometric parameters for an inlet.
 
SWMM_ENGINE_API int swmm_inlet_count (SWMM_Engine engine)
 Get the total number of inlet definitions in the model.
 
SWMM_ENGINE_API int swmm_inlet_index (SWMM_Engine engine, const char *id)
 Look up an inlet's zero-based index by its string identifier.
 
SWMM_ENGINE_API const char * swmm_inlet_id (SWMM_Engine engine, int idx)
 Get the string identifier of an inlet by index.
 
SWMM_ENGINE_API int swmm_lid_add (SWMM_Engine engine, const char *id, int type)
 Add a new LID (Low Impact Development) control.
 
SWMM_ENGINE_API int swmm_lid_set_surface (SWMM_Engine engine, int idx, double storage, double roughness, double slope)
 Set the surface layer properties for a LID control.
 
SWMM_ENGINE_API int swmm_lid_set_soil (SWMM_Engine engine, int idx, double thick, double porosity, double fc, double wp, double ksat, double kslope)
 Set the soil layer properties for a LID control.
 
SWMM_ENGINE_API int swmm_lid_set_storage (SWMM_Engine engine, int idx, double thick, double void_frac, double ksat)
 Set the storage layer properties for a LID control.
 
SWMM_ENGINE_API int swmm_lid_set_drain (SWMM_Engine engine, int idx, double coeff, double expon, double offset)
 Set the underdrain properties for a LID control.
 
SWMM_ENGINE_API int swmm_lid_count (SWMM_Engine engine)
 Get the total number of LID controls in the model.
 
SWMM_ENGINE_API int swmm_lid_index (SWMM_Engine engine, const char *id)
 Look up a LID control's zero-based index by its string identifier.
 
SWMM_ENGINE_API const char * swmm_lid_id (SWMM_Engine engine, int idx)
 Get the string identifier of a LID control by index.
 
SWMM_ENGINE_API int swmm_lid_usage_add (SWMM_Engine engine, int subcatch_idx, int lid_idx, int number, double area, double width, double init_sat, double from_imperv)
 Assign a LID control to a subcatchment.
 

Detailed Description

C API implementation — transects, streets, inlets, LID controls, LID usage.

See also
include/openswmm/engine/openswmm_infrastructure.h
Author
Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com
License\n MIT License

Function Documentation

◆ swmm_inlet_add()

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

Add a new inlet definition.

Parameters
engineEngine handle (SWMM_STATE_BUILDING).
idUnique null-terminated identifier.
typeInlet type string (e.g., "GRATE", "CURB", "SLOTTED", "CUSTOM").
Returns
SWMM_OK on success, or an error code.

◆ swmm_inlet_count()

SWMM_ENGINE_API int swmm_inlet_count ( SWMM_Engine  engine)

Get the total number of inlet definitions in the model.

Parameters
engineEngine handle.
Returns
Number of inlets, or -1 on error.

◆ swmm_inlet_id()

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

Get the string identifier of an inlet by index.

Parameters
engineEngine handle.
idxZero-based inlet index.
Returns
Null-terminated string owned by the engine, or NULL on error.

◆ swmm_inlet_index()

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

Look up an inlet's zero-based index by its string identifier.

Parameters
engineEngine handle.
idNull-terminated inlet identifier.
Returns
Zero-based index, or -1 if not found.

◆ swmm_inlet_set_params()

SWMM_ENGINE_API int swmm_inlet_set_params ( SWMM_Engine  engine,
int  idx,
double  length,
double  width,
const char *  grate_type,
double  open_area,
double  splash_veloc 
)

Set the geometric parameters for an inlet.

Parameters
engineEngine handle.
idxZero-based inlet index.
lengthInlet length.
widthInlet width.
grate_typeGrate type string (e.g., "P-50", "GENERIC").
open_areaOpen area fraction (0–1).
splash_velocSplash-over velocity threshold.
Returns
SWMM_OK on success, or an error code.

◆ swmm_lid_add()

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

Add a new LID (Low Impact Development) control.

LID types: 0=BIO_CELL, 1=RAIN_GARDEN, 2=GREEN_ROOF, 3=INFIL_TRENCH, 4=PERM_PAVEMENT, 5=RAIN_BARREL, 6=ROOFTOP_DISCONN, 7=VEGETATIVE_SWALE.

Parameters
engineEngine handle (SWMM_STATE_BUILDING).
idUnique null-terminated identifier.
typeLID type code.
Returns
SWMM_OK on success, or an error code.

◆ swmm_lid_count()

SWMM_ENGINE_API int swmm_lid_count ( SWMM_Engine  engine)

Get the total number of LID controls in the model.

Parameters
engineEngine handle.
Returns
Number of LID controls, or -1 on error.

◆ swmm_lid_id()

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

Get the string identifier of a LID control by index.

Parameters
engineEngine handle.
idxZero-based LID index.
Returns
Null-terminated string owned by the engine, or NULL on error.

◆ swmm_lid_index()

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

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

Parameters
engineEngine handle.
idNull-terminated LID identifier.
Returns
Zero-based index, or -1 if not found.

◆ swmm_lid_set_drain()

SWMM_ENGINE_API int swmm_lid_set_drain ( SWMM_Engine  engine,
int  idx,
double  coeff,
double  expon,
double  offset 
)

Set the underdrain properties for a LID control.

Parameters
engineEngine handle.
idxZero-based LID index.
coeffDrain coefficient.
exponDrain exponent.
offsetDrain offset height above the storage layer bottom.
Returns
SWMM_OK on success, or an error code.

◆ swmm_lid_set_soil()

SWMM_ENGINE_API int swmm_lid_set_soil ( SWMM_Engine  engine,
int  idx,
double  thick,
double  porosity,
double  fc,
double  wp,
double  ksat,
double  kslope 
)

Set the soil layer properties for a LID control.

Parameters
engineEngine handle.
idxZero-based LID index.
thickSoil thickness.
porositySoil porosity (fraction).
fcField capacity (fraction).
wpWilting point (fraction).
ksatSaturated hydraulic conductivity.
kslopeSlope of the conductivity–moisture curve.
Returns
SWMM_OK on success, or an error code.

◆ swmm_lid_set_storage()

SWMM_ENGINE_API int swmm_lid_set_storage ( SWMM_Engine  engine,
int  idx,
double  thick,
double  void_frac,
double  ksat 
)

Set the storage layer properties for a LID control.

Parameters
engineEngine handle.
idxZero-based LID index.
thickStorage layer thickness.
void_fracVoid fraction (porosity of gravel/aggregate).
ksatSeepage rate through the storage layer bottom.
Returns
SWMM_OK on success, or an error code.

◆ swmm_lid_set_surface()

SWMM_ENGINE_API int swmm_lid_set_surface ( SWMM_Engine  engine,
int  idx,
double  storage,
double  roughness,
double  slope 
)

Set the surface layer properties for a LID control.

Parameters
engineEngine handle.
idxZero-based LID index.
storageSurface storage depth.
roughnessSurface Manning's n.
slopeSurface slope (fraction).
Returns
SWMM_OK on success, or an error code.

◆ swmm_lid_usage_add()

SWMM_ENGINE_API int swmm_lid_usage_add ( SWMM_Engine  engine,
int  subcatch_idx,
int  lid_idx,
int  number,
double  area,
double  width,
double  init_sat,
double  from_imperv 
)

Assign a LID control to a subcatchment.

Multiple LID units of the same or different types can be assigned to a single subcatchment.

Parameters
engineEngine handle.
subcatch_idxZero-based subcatchment index.
lid_idxZero-based LID control index.
numberNumber of replicate LID units.
areaArea of each LID unit in project area units.
widthTop width of the overland flow surface per unit.
init_satInitial saturation of the soil layer (0–1).
from_impervFraction of impervious area runoff treated by this LID (0–1).
Returns
SWMM_OK on success, or an error code.

◆ swmm_street_add()

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

Add a new street cross-section definition.

Parameters
engineEngine handle (SWMM_STATE_BUILDING).
idUnique null-terminated identifier.
Returns
SWMM_OK on success, or an error code.

◆ swmm_street_count()

SWMM_ENGINE_API int swmm_street_count ( SWMM_Engine  engine)

Get the total number of street definitions in the model.

Parameters
engineEngine handle.
Returns
Number of streets, or -1 on error.

◆ swmm_street_id()

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

Get the string identifier of a street by index.

Parameters
engineEngine handle.
idxZero-based street index.
Returns
Null-terminated string owned by the engine, or NULL on error.

◆ swmm_street_index()

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

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

Parameters
engineEngine handle.
idNull-terminated street identifier.
Returns
Zero-based index, or -1 if not found.

◆ swmm_street_set_params()

SWMM_ENGINE_API int swmm_street_set_params ( SWMM_Engine  engine,
int  idx,
double  t_crown,
double  h_curb,
double  sx,
double  n_road,
double  gutter_depres,
double  gutter_width,
int  sides,
double  back_width,
double  back_slope,
double  back_n 
)

Set the geometric parameters for a street cross-section.

Parameters
engineEngine handle.
idxZero-based street index.
t_crownCrown thickness (rise of the crown above the gutter).
h_curbCurb height.
sxCross slope of the roadway.
n_roadManning's n for the road surface.
gutter_depresGutter depression depth.
gutter_widthGutter width.
sidesNumber of sides (1 or 2).
back_widthBacking (sidewalk) width.
back_slopeBacking slope.
back_nManning's n for the backing area.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_add()

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

Add a new transect for irregular cross-sections.

Parameters
engineEngine handle (SWMM_STATE_BUILDING).
idUnique null-terminated identifier.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_add_station()

SWMM_ENGINE_API int swmm_transect_add_station ( SWMM_Engine  engine,
int  idx,
double  station,
double  elevation 
)

Add a station–elevation data point to a transect.

Stations must be added in order from left to right across the cross-section.

Parameters
engineEngine handle.
idxZero-based transect index.
stationHorizontal distance (station) from a reference.
elevationElevation at this station.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_clear_stations()

SWMM_ENGINE_API int swmm_transect_clear_stations ( SWMM_Engine  engine,
int  idx 
)

Remove all station–elevation pairs from a transect.

Used by the GUI's snapshot-and-rewrite path: clear then re-add the full station list in one shot.

Parameters
engineEngine handle.
idxZero-based transect index.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_count()

SWMM_ENGINE_API int swmm_transect_count ( SWMM_Engine  engine)

Get the total number of transects in the model.

Parameters
engineEngine handle.
Returns
Number of transects, or -1 on error.

◆ swmm_transect_get_bank_stations()

SWMM_ENGINE_API int swmm_transect_get_bank_stations ( SWMM_Engine  engine,
int  idx,
double *  x_left,
double *  x_right 
)

Get the left and right bank stations for a transect.

Parameters
engineEngine handle.
idxZero-based transect index.
x_left[out] Station of the left bank. May be NULL.
x_right[out] Station of the right bank. May be NULL.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_get_comments()

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

Get the free-form comments / description for a transect.

Writes the comment into buf with NUL termination; truncates if the buffer is smaller than the comment. Always returns SWMM_OK (an empty comment results in buf[0] == '\0').

Parameters
engineEngine handle.
idxZero-based transect index.
bufDestination buffer.
buflenSize of buf in bytes (must be > 0).
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_get_encroachment_stations()

SWMM_ENGINE_API int swmm_transect_get_encroachment_stations ( SWMM_Engine  engine,
int  idx,
double *  x_left,
double *  x_right 
)

Get the left and right encroachment stations for a transect (BQ-TR-02).

Parameters
engineEngine handle.
idxZero-based transect index.
x_left[out] Station of the left encroachment limit. May be NULL.
x_right[out] Station of the right encroachment limit. May be NULL.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_get_modifiers()

SWMM_ENGINE_API int swmm_transect_get_modifiers ( SWMM_Engine  engine,
int  idx,
double *  x_factor,
double *  y_factor,
double *  length_factor 
)

Get the station, elevation, and meander modifiers for a transect.

Parameters
engineEngine handle.
idxZero-based transect index.
x_factor[out] Station spacing multiplier. May be NULL.
y_factor[out] Elevation offset. May be NULL.
length_factor[out] Meander factor. May be NULL.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_get_roughness()

SWMM_ENGINE_API int swmm_transect_get_roughness ( SWMM_Engine  engine,
int  idx,
double *  n_left,
double *  n_right,
double *  n_channel 
)

Get the Manning's roughness values for a transect.

Parameters
engineEngine handle.
idxZero-based transect index.
n_left[out] Manning's n for the left overbank. May be NULL.
n_right[out] Manning's n for the right overbank. May be NULL.
n_channel[out] Manning's n for the main channel. May be NULL.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_get_station()

SWMM_ENGINE_API int swmm_transect_get_station ( SWMM_Engine  engine,
int  idx,
int  station_idx,
double *  station,
double *  elevation 
)

Get a single station–elevation pair from a transect.

Parameters
engineEngine handle.
idxZero-based transect index.
station_idxZero-based station-pair index.
station[out] Horizontal distance. May be NULL.
elevation[out] Elevation at this station. May be NULL.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_get_station_count()

SWMM_ENGINE_API int swmm_transect_get_station_count ( SWMM_Engine  engine,
int  idx 
)

Get the number of station–elevation points stored for a transect.

Parameters
engineEngine handle.
idxZero-based transect index.
Returns
Station count, or -1 on error.

◆ swmm_transect_id()

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

Get the string identifier of a transect by index.

Parameters
engineEngine handle.
idxZero-based transect index.
Returns
Null-terminated string owned by the engine, or NULL on error.

◆ swmm_transect_index()

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

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

Parameters
engineEngine handle.
idNull-terminated transect identifier.
Returns
Zero-based index, or -1 if not found.

◆ swmm_transect_remove()

SWMM_ENGINE_API int swmm_transect_remove ( SWMM_Engine  engine,
int  idx 
)

Remove a transect by index.

Out-of-range indices are a SWMM_OK no-op (mirrors the pattern mutation API — see test_pattern_mutation_api.cpp). Remaining transects preserve their relative order; their indices shift down by one.

Parameters
engineEngine handle.
idxZero-based transect index.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_rename()

SWMM_ENGINE_API int swmm_transect_rename ( SWMM_Engine  engine,
int  idx,
const char *  new_id 
)

Rename an existing transect.

Refuses on collision with another existing transect name (case insensitive); same-name is a no-op SWMM_OK.

Parameters
engineEngine handle.
idxZero-based transect index.
new_idNew null-terminated identifier.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_set_bank_stations()

SWMM_ENGINE_API int swmm_transect_set_bank_stations ( SWMM_Engine  engine,
int  idx,
double  x_left,
double  x_right 
)

Set the left and right bank stations for a transect.

Bank stations delimit the main channel from the overbanks; they are independent of the encroachment stations (BQ-TR-02).

Parameters
engineEngine handle.
idxZero-based transect index.
x_leftStation of the left bank.
x_rightStation of the right bank.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_set_comments()

SWMM_ENGINE_API int swmm_transect_set_comments ( SWMM_Engine  engine,
int  idx,
const char *  text 
)

Set the free-form comments / description for a transect.

Parameters
engineEngine handle.
idxZero-based transect index.
textNull-terminated comment string. NULL clears the comment.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_set_encroachment_stations()

SWMM_ENGINE_API int swmm_transect_set_encroachment_stations ( SWMM_Engine  engine,
int  idx,
double  x_left,
double  x_right 
)

Set the left and right encroachment stations for a transect (BQ-TR-02).

Encroachment stations are distinct from bank stations and identify floodplain encroachment limits (HEC-RAS convention). On legacy [TRANSECTS] X1 records that omit the trailing encroachment columns, the INP parser may default these to the bank stations to preserve backward compatibility; callers writing programmatic values via this API are setting them explicitly.

Parameters
engineEngine handle.
idxZero-based transect index.
x_leftStation of the left encroachment limit.
x_rightStation of the right encroachment limit.
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_set_modifiers()

SWMM_ENGINE_API int swmm_transect_set_modifiers ( SWMM_Engine  engine,
int  idx,
double  x_factor,
double  y_factor,
double  length_factor 
)

Set the station, elevation, and meander modifiers for a transect.

Maps to the xFactor, yFactor, and lengthFactor parameters on the [TRANSECTS] X1 record:

  • x_factor = station-spacing multiplier (default 1.0).
  • y_factor = elevation offset added to every station elevation (default 0.0 — engine stores 1.0 as a no-op marker at swmm_transect_add time).
  • length_factor = meander factor = channel / floodplain length ratio (default 1.0).
Parameters
engineEngine handle.
idxZero-based transect index.
x_factorStation spacing multiplier.
y_factorElevation offset.
length_factorMeander factor (channel/floodplain length ratio).
Returns
SWMM_OK on success, or an error code.

◆ swmm_transect_set_roughness()

SWMM_ENGINE_API int swmm_transect_set_roughness ( SWMM_Engine  engine,
int  idx,
double  n_left,
double  n_right,
double  n_channel 
)

Set Manning's roughness for left overbank, right overbank, and channel.

Parameters
engineEngine handle.
idxZero-based transect index.
n_leftManning's n for the left overbank.
n_rightManning's n for the right overbank.
n_channelManning's n for the main channel.
Returns
SWMM_OK on success, or an error code.