openswmm_output2d_impl.cpp File Reference

Public C API implementation for saved 2D result access. More...

#include "openswmm/engine/openswmm_output2d.h"
#include "openswmm/engine/openswmm_engine.h"
#include "Output2DReader.hpp"
#include "../io/Hdf5Mutex.hpp"
#include <cstring>
#include <memory>
#include <stdexcept>
#include <string>

Include dependency graph for openswmm_output2d_impl.cpp:

Functions
int	swmm_output2d_available (void)
	Query whether saved 2D HDF5 result reading was compiled into this engine.
const char *	swmm_output2d_error (void)
	Access the calling thread's last saved-result reader diagnostic.
int	swmm_output2d_open (const char *path, SWMM_Output2D *output)
	Open and validate an existing 2D HDF5 result file for read-only access.
void	swmm_output2d_close (SWMM_Output2D output)
	Release a reader and its owned HDF5 file.
int	swmm_output2d_datasets (SWMM_Output2D output, char *text, size_t capacity, size_t *required)
	Enumerate readable numeric and string datasets in a saved result.
int	swmm_output2d_shape (SWMM_Output2D output, const char *path, int *rank, uint64_t *dimensions, int *integer, uint64_t *unlimited_axes)
	Read a dataset's rank, extents, storage category, and appendable axes.
int	swmm_output2d_attributes (SWMM_Output2D output, const char *path, char *text, size_t capacity, size_t *required)
	Enumerate metadata attribute names on an HDF5 object.
int	swmm_output2d_attribute (SWMM_Output2D output, const char *path, const char *name, char *text, size_t capacity, size_t *required)
	Obtain a string representation of a supported metadata attribute.
int	swmm_output2d_read_double (SWMM_Output2D output, const char *path, const uint64_t *start, const uint64_t *count, const uint64_t *stride, double *values, size_t capacity)
	Read a bounded numeric hyperslab, converting values to double.
int	swmm_output2d_strings (SWMM_Output2D output, const char *path, char *text, size_t capacity, size_t *required)
	Read a bounded one-dimensional string identity table.
int	swmm_output2d_read_int64 (SWMM_Output2D output, const char *path, const uint64_t *start, const uint64_t *count, const uint64_t *stride, int64_t *values, size_t capacity)
	Read a bounded integer hyperslab as signed 64-bit values.

Detailed Description

Public C API implementation for saved 2D result access.

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License

Apache-2.0

Function Documentation

swmm_output2d_attribute()

int swmm_output2d_attribute	(	SWMM_Output2D	output,
		const char *	object,
		const char *	name,
		char *	text,
		size_t	capacity,
		size_t *	required )

Obtain a string representation of a supported metadata attribute.

Parameters

[in]	output	Live reader handle.
[in]	object	Non-null, non-empty path of the owning dataset/group, or "/".
[in]	name	Non-null, non-empty attribute name on that object.
[out]	text	Destination for null-terminated attribute text, or NULL with zero capacity to query size. Empty attribute text still requires its NUL.
[in]	capacity	Destination capacity in bytes including the NUL terminator.
[out]	required	Required pointer receiving the byte count including NUL.

Returns

SWMM_OK, or BADHANDLE/BADPARAM/BADINDEX and backend/IO/allocation errors.

Scalar fixed/variable strings and integer/floating-point arrays are supported. Numeric arrays are flattened into comma-separated values; floating-point values use 17 significant digits. Unsupported types or excessive sizes fail. Querying does not allocate a persistent caller-owned string. A short buffer updates required without copying a partial attribute value.

swmm_output2d_attributes()

int swmm_output2d_attributes	(	SWMM_Output2D	output,
		const char *	object,
		char *	text,
		size_t	capacity,
		size_t *	required )

Enumerate metadata attribute names on an HDF5 object.

Parameters

[in]	output	Live reader handle.
[in]	object	Non-null, non-empty dataset/group path, or "/" for the root object.
[out]	text	Null-terminated, newline-separated names; NULL/zero queries size.
[in]	capacity	Available bytes in text, including its NUL terminator.
[out]	required	Required pointer receiving the complete byte count including NUL.

Returns

SWMM_OK, or BADHANDLE/BADPARAM/BADINDEX and backend/IO/allocation errors.

Note

Names are enumerated in HDF5 name-index order. A too-small buffer updates required but is not partially written; an object with no attributes needs one byte.

swmm_output2d_available()

int swmm_output2d_available

(

void

)

Query whether saved 2D HDF5 result reading was compiled into this engine.

Returns

1 when available, or 0 when the backend is absent.

Note

No file or reader handle is required. This query leaves the thread's previous reader diagnostic unchanged.

swmm_output2d_close()

void swmm_output2d_close

(

SWMM_Output2D

output

)

Release a reader and its owned HDF5 file.

Parameters

[in]

output

Handle returned by swmm_output2d_open(), or NULL for a no-op.

Precondition

A non-null handle must still be live and must not be in use by another call.

Postcondition

A non-null handle is invalid and must not be used or closed again.

Note

This function leaves the last reader diagnostic unchanged. Backend-disabled builds perform no action; arbitrary or already-closed handles are not validated.

Here is the call graph for this function:

swmm_output2d_datasets()

int swmm_output2d_datasets	(	SWMM_Output2D	output,
		char *	text,
		size_t	capacity,
		size_t *	required )

Enumerate readable numeric and string datasets in a saved result.

Parameters

[in]	output	Live reader handle.
[out]	text	Destination for null-terminated, newline-separated absolute HDF5 paths, or NULL with capacity zero to query the required size.
[in]	capacity	Available destination bytes, including the terminating NUL.
[out]	required	Required pointer receiving the complete byte count including NUL.

Returns

SWMM_OK on success; BADHANDLE for a null reader, BADPARAM for an invalid or short destination, or the IO/allocation/backend errors described by open().

Paths are sorted lexicographically. Only hard links are followed; external and symbolic links are skipped. Excessive group nesting is rejected. A short buffer updates required without writing partial text. Even a size query enumerates the datasets and can fail during HDF5 access.

swmm_output2d_error()

const char * swmm_output2d_error

(

void

)

Access the calling thread's last saved-result reader diagnostic.

Returns

Borrowed, null-terminated text, empty after a successful checked reader operation. Copy it before another operation replaces that thread's error.

Note

The caller must not modify or free the text. Reading this diagnostic, testing backend availability, and closing a reader do not clear it. It is independent of an engine simulation handle's error state.

swmm_output2d_open()

int swmm_output2d_open	(	const char *	path,
		SWMM_Output2D *	output )

Open and validate an existing 2D HDF5 result file for read-only access.

Parameters

[in]	path	Non-null, non-empty, null-terminated filesystem path to a saved result containing mesh coordinates, connectivity, and time datasets.
[out]	output	Required pointer receiving the newly owned reader handle. Set to NULL before opening and left NULL on failure.

Return values

SWMM_OK	The file was opened and its required mesh/time layout was validated.
SWMM_ERR_BADPARAM	An argument or required dataset shape/type is invalid.
SWMM_ERR_BADINDEX	A required HDF5 object is absent.
SWMM_ERR_IO	The file cannot be opened or an HDF5 operation fails.
SWMM_ERR_NOMEM	Allocation fails while opening or validating the reader.
SWMM_ERR_PLUGIN	This build has no 2D HDF5 result reader.
SWMM_ERR_INTERNAL	An otherwise unclassified exception was caught.

Postcondition

On success, the caller must close the handle exactly once with swmm_output2d_close(). An older handle already stored in output is not closed.

Note

Read a closed result file or an immutable published copy. Opening does not establish a concurrent-writer protocol or convert stored scientific units.

swmm_output2d_read_double()

int swmm_output2d_read_double	(	SWMM_Output2D	output,
		const char *	dataset,
		const uint64_t *	start,
		const uint64_t *	count,
		const uint64_t *	stride,
		double *	values,
		size_t	capacity )

Read a bounded numeric hyperslab, converting values to double.

Parameters

[in]	output	Live reader handle.
[in]	dataset	Non-null, non-empty path of an integer or floating-point dataset.
[in]	start	Zero-based starting indices in native axis order, one per rank axis. May be NULL for a scalar, whose rank is zero.
[in]	count	Number of selected elements along each axis; any zero makes the selection empty. May be NULL only for a scalar.
[in]	stride	Strictly positive index increments, one per axis; NULL for a scalar.
[out]	values	Storage for the selected doubles in HDF5's native axis order; may be NULL only for an empty selection. Caller retains ownership.
[in]	capacity	Available double elements, not bytes. A scalar requires at least one.

Returns

SWMM_OK, including for valid empty selections; BADINDEX for an out-of-bounds selection; BADPARAM for missing axes, zero strides, size overflow, unsupported types, or insufficient storage; otherwise a handle/backend/IO/allocation error.

Shape, selection bounds, and capacity are checked before HDF5 copies data. No physical-unit conversion occurs. Integer-to-double conversion can lose precision; use swmm_output2d_read_int64() to retain integer identity values. A failure during the HDF5 read itself does not promise an untouched buffer.

swmm_output2d_read_int64()

int swmm_output2d_read_int64	(	SWMM_Output2D	output,
		const char *	dataset,
		const uint64_t *	start,
		const uint64_t *	count,
		const uint64_t *	stride,
		int64_t *	values,
		size_t	capacity )

Read a bounded integer hyperslab as signed 64-bit values.

Parameters

[in]	output	Live reader handle.
[in]	dataset	Non-null, non-empty path of an integer dataset; floating-point and string storage are rejected rather than rounded or parsed.
[in]	start	Zero-based starting indices; one per axis, or NULL for a scalar.
[in]	count	Selected extents; one per axis, or NULL for a scalar. A zero extent makes the selection empty while all other selection checks still apply.
[in]	stride	Strictly positive increments; one per axis, or NULL for a scalar.
[out]	values	Caller-owned int64_t storage; NULL is accepted only for an empty selection. Values are converted by HDF5 to its native int64 type.
[in]	capacity	Available int64_t elements, not bytes; at least one for a scalar.

Returns

The same selection/handle/backend/IO error categories as read_double(), plus BADPARAM when the dataset does not have integer storage.

Note

Native axis order and stored scientific units are preserved. The reader adds no range check beyond HDF5's conversion from the stored integer representation.

swmm_output2d_shape()

int swmm_output2d_shape	(	SWMM_Output2D	output,
		const char *	dataset,
		int *	rank,
		uint64_t *	dimensions,
		int *	integer,
		uint64_t *	unlimited_axes )

Read a dataset's rank, extents, storage category, and appendable axes.

Parameters

[in]	output	Live reader handle.
[in]	dataset	Non-null, non-empty HDF5 path identifying a dataset in this file.
[out]	rank	Required pointer receiving the rank in [0,8]; zero denotes a scalar.
[out]	dimensions	Required storage for at least eight uint64_t entries. Only the first rank entries are written; each is an element count.
[out]	integer	Required pointer receiving 1 for integer, 0 for floating-point, or -1 for string storage. Other storage classes are rejected.
[out]	unlimited_axes	Required pointer receiving a bit mask whose bit i is set when axis i has an unlimited maximum extent.

Returns

SWMM_OK on success; BADHANDLE, BADPARAM, BADINDEX, or a backend/IO/allocation error on failure. Output values must be disregarded after any failure.

Note

Output pointers remain required for rank-zero scalars. Extents use the native dataset axis order and do not imply a particular physical unit or time axis.

swmm_output2d_strings()

int swmm_output2d_strings	(	SWMM_Output2D	output,
		const char *	dataset,
		char *	text,
		size_t	capacity,
		size_t *	required )

Read a bounded one-dimensional string identity table.

Parameters

[in]	output	Live reader handle.
[in]	dataset	Non-null, non-empty path of a rank-one string dataset.
[out]	text	Destination for one string per line, or NULL with zero capacity to query size. Each entry is followed by a newline, including the last.
[in]	capacity	Destination capacity in bytes, including the final NUL terminator.
[out]	required	Required pointer receiving the complete byte count including NUL.

Returns

SWMM_OK, or BADHANDLE/BADPARAM/BADINDEX and backend/IO/allocation errors.

Fixed/variable strings are supported, up to 65,536 entries and the reader's 64 MiB string-payload bound. Embedded CR or LF characters are rejected so each entry remains one line. A short destination is not partially written.

Note

A size query still reads the complete table; it is not a cheap metadata query.