openswmm_process_components.h

Go to the documentation of this file.

/* SPDX-License-Identifier: Apache-2.0
 *
 * Copyright 2026 Caleb Buahin
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

 
#ifndef OPENSWMM_PROCESS_COMPONENTS_H
#define OPENSWMM_PROCESS_COMPONENTS_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif

SWMM_ENGINE_API int swmm_process_component_count(SWMM_Engine engine);

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

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

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

SWMM_ENGINE_API int swmm_process_component_remove(SWMM_Engine engine, int idx);
 
/* ---- Built-in component catalogue (U1, 2026-09-07) -----------------------
 * The ids the engine knows how to bind, independent of any model: the six
 * planned/implemented built-ins of the process-global registry. This is the
 * catalogue the GUI's Process Components table offers in its Id combo. The
 * external component-library discovery (`swmm_component_library_*`,
 * PROG stream D) is a separate, later seam; this one never scans disk.
 */

SWMM_ENGINE_API int swmm_process_component_known_count(void);

SWMM_ENGINE_API int swmm_process_component_known_get(int idx, char* id_buf, int id_len,
                                                     char* desc_buf, int desc_len,
                                                     int* implemented);
 
/* ------------------------------------------------------------------------
 * D2 (program plan §B.2.5) — discovered HydroCouple component libraries.
 *
 * Process-global, like the built-in catalogue above: no engine handle. A
 * component library is a shared library exporting HydroCouple's loader
 * contract (`hydrocouple_component_abi_v1` + `hydrocouple_component_info_v1`,
 * from HydroCouple's hydrocouplecomponentabi.h), or the legacy
 * `CreateComponentInfo`.
 *
 * Discovery (§B.2.3) runs once, on the first call to either query below:
 * the engine library's directory and its plugins/ and components/
 * subdirectories, then each directory in the path-list environment
 * variable HYDROCOUPLE_COMPONENT_PATH (':'-separated; ';' on Windows).
 * swmm_component_search_path_add() scans a further directory immediately.
 *
 * Every library the engine RECOGNISED as a component is listed — including
 * ones it refused. A stamped library whose ABI stamp differs from the
 * engine's is never called beyond its stamp, and is listed with both stamps
 * in `load_error`. A legacy library is loaded best-effort and listed with
 * stamp "unstamped(legacy CreateComponentInfo)", so it is never mistaken
 * for a verified one. Libraries that are not components are not listed.
 *
 * Built without OPENSWMM_WITH_HYDROCOUPLE, discovery finds nothing: the
 * count is 0 and swmm_component_search_path_add returns SWMM_ERR_PLUGIN.
 *
 * Argument / exchange-item / capability enumeration
 * (swmm_component_info_*) is a later part of D2 and not yet available.
 * ------------------------------------------------------------------------ */

typedef struct SWMM_ComponentLibraryInfo {
    char id[256]; 
    char caption[256];
    char version[64];
    char path[1024];       
    char kind[16];         
    char stamp[256];       
    char load_error[1024]; 
} SWMM_ComponentLibraryInfo;

SWMM_ENGINE_API int swmm_component_search_path_add(const char* dir);

SWMM_ENGINE_API int swmm_component_library_count(void);

SWMM_ENGINE_API int swmm_component_library_get(int idx, SWMM_ComponentLibraryInfo* info);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OPENSWMM_PROCESS_COMPONENTS_H */