Dark-Horse-Linux/dpm-core
1
0
Fork 0
Code Pull Requests Releases Activity

directory restructure and documentation cleanup

Browse Source
This commit is contained in:
Chris Punches
2025-03-08 04:56:07 -05:00
parent 34bab86b69
commit f0859c93c3
19 changed files with 1180 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

144
include/ConfigManager.hpp
View File

@@ -45,52 +45,166 @@
#include "dpm_interface_helpers.hpp"
/**
* @class ConfigManager
* @brief Manages and provides access to configuration settings
*
* This class handles loading, parsing, and providing access to configuration
* values from INI-style files. It supports sections, key-value pairs, and
* provides type-conversion methods for different value types.
*/
class ConfigManager {
public:
// Constructor
/**
* @brief Constructor
*
* Initializes a new ConfigManager instance with the default
* configuration directory.
*/
ConfigManager();
// Set the configuration directory
/**
* @brief Sets the configuration directory path
*
* @param config_dir The directory path where configuration files are located
*/
void setConfigDir(const std::string& config_dir);
// Get the current configuration directory
/**
* @brief Gets the current configuration directory path
*
* @return The current configuration directory path
*/
std::string getConfigDir() const;
// Load all configuration files from the config directory
/**
* @brief Loads all configuration files from the config directory
*
* Scans the configuration directory for .conf files, parses them,
* and populates the internal configuration data structure.
*
* @return true if at least one configuration file was loaded successfully,
* false otherwise
*/
bool loadConfigurations();
// Get configuration values with type conversion
/**
* @brief Gets a configuration value as a C-style string
*
* @param section The section name (uses DEFAULT_SECTION if NULL)
* @param key The configuration key
* @return The configuration value as a C-style string, or NULL if not found
*/
const char* getConfigValue(const char* section, const char* key) const;
/**
* @brief Gets a configuration value as a C++ string with default
*
* @param section The section name (uses DEFAULT_SECTION if NULL)
* @param key The configuration key
* @param defaultValue The default value to return if the key is not found
* @return The configuration value as a string, or defaultValue if not found
*/
std::string getConfigString(const char* section, const char* key, const std::string& defaultValue = "") const;
/**
* @brief Gets a configuration value as an integer with default
*
* @param section The section name (uses DEFAULT_SECTION if NULL)
* @param key The configuration key
* @param defaultValue The default value to return if the key is not found or conversion fails
* @return The configuration value as an integer, or defaultValue if not found or conversion fails
*/
int getConfigInt(const char* section, const char* key, int defaultValue = 0) const;
/**
* @brief Gets a configuration value as a double with default
*
* @param section The section name (uses DEFAULT_SECTION if NULL)
* @param key The configuration key
* @param defaultValue The default value to return if the key is not found or conversion fails
* @return The configuration value as a double, or defaultValue if not found or conversion fails
*/
double getConfigDouble(const char* section, const char* key, double defaultValue = 0.0) const;
/**
* @brief Gets a configuration value as a boolean with default
*
* Recognizes "true", "yes", "1", "on", "enabled" as true values and
* "false", "no", "0", "off", "disabled" as false values (case-insensitive).
*
* @param section The section name (uses DEFAULT_SECTION if NULL)
* @param key The configuration key
* @param defaultValue The default value to return if the key is not found or conversion fails
* @return The configuration value as a boolean, or defaultValue if not found or conversion fails
*/
bool getConfigBool(const char* section, const char* key, bool defaultValue = false) const;
// Check if configuration directory exists
/**
* @brief Checks if the configuration directory exists
*
* @return true if the configuration directory exists, false otherwise
*/
bool configDirExists() const;
// Check if a configuration key exists
/**
* @brief Checks if a configuration key exists
*
* @param section The section name (uses DEFAULT_SECTION if NULL)
* @param key The configuration key
* @return true if the key exists in the specified section or DEFAULT_SECTION, false otherwise
*/
bool hasConfigKey(const char* section, const char* key) const;
private:
// Default section name to use when none is specified
/**
* @brief Default section name to use when none is specified
*/
static constexpr const char* DEFAULT_SECTION = "MAIN";
// Parse a single configuration file
/**
* @brief Parses a single configuration file
*
* @param config_file Path to the configuration file to parse
* @return true if the file was parsed successfully, false otherwise
*/
bool parseConfigFile(const std::filesystem::path& config_file);
// Trim whitespace from a string
/**
* @brief Removes leading and trailing whitespace from a string
*
* @param str The string to trim
* @return The trimmed string
*/
std::string trimWhitespace(const std::string& str) const;
// Find a key in the given section or in the default section
/**
* @brief Finds a configuration value by section and key
*
* Searches for the key in the specified section. If not found and the
* section is not DEFAULT_SECTION, tries to find the key in DEFAULT_SECTION.
*
* @param section The section name
* @param key The configuration key
* @return Optional reference to the configuration value if found, empty optional otherwise
*/
std::optional<std::reference_wrapper<const std::string>> findConfigValue(const std::string& section, const std::string& key) const;
// Configuration directory path
/**
* @brief Configuration directory path
*/
std::string _config_dir;
// Configuration data structure: section -> key -> value
/**
* @brief Configuration data structure: section -> key -> value
*/
std::map<std::string, std::map<std::string, std::string>> _config_data;
};
// Global configuration manager instance
extern ConfigManager g_config_manager;
/**
* @brief Global configuration manager instance
*
* Provides a single instance of the ConfigManager that can be accessed
* from anywhere in the application.
*/
extern ConfigManager g_config_manager;

69
include/DPMDefaults.hpp
View File

@@ -33,20 +33,87 @@
#include <string>
#include "LoggingLevels.hpp"
// default system configuration
/**
* @struct DPMDefaults
* @brief Default configuration values for DPM
*
* Provides system-wide default values for paths, logging settings, and
* other configuration options used when explicit configuration is not provided.
*/
struct DPMDefaults {
/**
* @brief Default path to the directory containing DPM modules
*
* Directory where DPM looks for module shared objects (.so files)
* when no explicit module path is provided.
*/
static const char* const MODULE_PATH;
/**
* @brief Default path to the directory containing configuration files
*
* Directory where DPM looks for configuration files (.conf files)
* when no explicit configuration directory is provided.
*/
static const char* const CONFIG_DIR;
/**
* @brief Default path to the log file
*
* File where DPM writes log messages when logging to file is enabled
* and no explicit log file path is provided.
*/
static const char* const LOG_FILE;
/**
* @brief Default setting for whether to write to log file
*
* Determines whether DPM writes log messages to a file by default.
*/
static const bool write_to_log;
/**
* @brief Default log level
*
* Determines which log messages are recorded based on their severity.
* Messages with a level less than or equal to this value are logged.
*/
static const LoggingLevels LOG_LEVEL;
};
// Initialize static constants
/**
* @brief Default module path initialization
*
* Sets the default module path to the standard system location.
*/
inline const char * const DPMDefaults::MODULE_PATH = "/usr/lib/dpm/modules/";
/**
* @brief Default configuration directory initialization
*
* Sets the default configuration directory to the standard system location.
*/
inline const char * const DPMDefaults::CONFIG_DIR = "/etc/dpm/conf.d/";
/**
* @brief Default log file path initialization
*
* Sets the default log file path to the standard system location.
*/
inline const char * const DPMDefaults::LOG_FILE = "/var/log/dpm.log";
/**
* @brief Default write to log setting initialization
*
* By default, logging to file is disabled.
*/
inline const bool DPMDefaults::write_to_log = false;
/**
* @brief Default log level initialization
*
* By default, only messages with level INFO or lower (FATAL, ERROR, WARN, INFO)
* are logged, while DEBUG messages are not.
*/
inline const LoggingLevels DPMDefaults::LOG_LEVEL = LoggingLevels::INFO;

130
include/Logger.hpp
View File

@@ -1,3 +1,33 @@
/**
* @file Logger.hpp
* @brief Logging system for the DPM utility
*
* Defines the Logger class which provides a centralized logging facility
* for the DPM utility. Supports multiple log levels, console output, and
* optional file logging with timestamps.
*
* @copyright Copyright (c) 2025 SILO GROUP LLC
* @author Chris Punches <chris.punches@silogroup.org>
*
* Part of the Dark Horse Linux Package Manager (DPM)
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* For bug reports or contributions, please contact the dhlp-contributors
* mailing list at: https://lists.darkhorselinux.org/mailman/listinfo/dhlp-contributors
*/
#pragma once
#include <fstream>
@@ -11,38 +41,116 @@
#include "LoggingLevels.hpp"
#include "DPMDefaults.hpp"
/**
* @class Logger
* @brief Provides logging capabilities for the DPM system
*
* Implements a configurable logging system that can write messages to
* both console and file outputs. Supports different log levels to
* control verbosity and includes automatic timestamp generation for
* log file entries.
*/
class Logger {
public:
// constructor
/**
* @brief Constructor
*
* Initializes a new Logger instance with default settings from DPMDefaults.
*/
Logger();
// destructor
/**
* @brief Destructor
*/
~Logger();
// Log method that accepts a string
/**
* @brief Logs a message with the specified log level
*
* Writes a log message to the console and optionally to a log file
* if the message level is less than or equal to the configured log level.
* Messages with levels FATAL, ERROR, or WARN are written to stderr,
* while others go to stdout. File logging includes timestamps.
*
* @param log_level The severity level of the message
* @param message The message to log
*/
void log(LoggingLevels log_level, const std::string& message);
// Configuration setters
/**
* @brief Sets the log file path
*
* Changes the file path where log messages are written when file
* logging is enabled. Ensures the log directory exists and is writable.
*
* @param log_file The path to the log file
*/
void setLogFile(const std::string& log_file);
/**
* @brief Enables or disables file logging
*
* Controls whether log messages are written to a file in addition
* to console output. If enabled, validates that the log file is writable.
*
* @param write_to_log true to enable file logging, false to disable
*/
void setWriteToLog(bool write_to_log);
/**
* @brief Sets the log level threshold
*
* Sets the maximum log level that will be processed. Messages with
* a level higher than this threshold will be ignored.
*
* @param log_level The new log level threshold
*/
void setLogLevel(LoggingLevels log_level);
// String to LoggingLevels conversion
/**
* @brief Converts a log level string to the corresponding enum value
*
* Parses a string representation of a log level (e.g., "INFO", "DEBUG")
* and returns the corresponding LoggingLevels enum value.
*
* @param level_str The string representation of the log level
* @param default_level The default level to return if parsing fails
* @return The corresponding LoggingLevels enum value
*/
static LoggingLevels stringToLogLevel(const std::string& level_str, LoggingLevels default_level = LoggingLevels::INFO);
// Convert LoggingLevels enum to string
/**
* @brief Converts a LoggingLevels enum value to its string representation
*
* Returns the string representation of a log level (e.g., "INFO", "DEBUG")
* for the given LoggingLevels enum value.
*
* @param level The LoggingLevels enum value
* @return The string representation of the log level
*/
static std::string LogLevelToString(LoggingLevels level);
private:
// the logging level to stay initialized to
/**
* @brief The current log level threshold
*/
LoggingLevels log_level;
// whether or not to log to file
/**
* @brief Whether to write log messages to a file
*/
bool log_to_file;
// log file path
/**
* @brief The path to the log file
*/
std::string log_file;
};
// Global logger instance
extern Logger g_logger;
/**
* @brief Global logger instance
*
* Provides a single instance of the Logger that can be accessed
* from anywhere in the application.
*/
extern Logger g_logger;

48
include/LoggingLevels.hpp
View File

@@ -1,12 +1,48 @@
/**
* @file LoggingLevels.hpp
* @brief Defines log level enumeration for DPM logging system
*
* Provides a standardized set of logging levels used throughout the DPM system
* to classify messages by severity and control logging verbosity.
*
* @copyright Copyright (c) 2025 SILO GROUP LLC
* @author Chris Punches <chris.punches@silogroup.org>
*
* Part of the Dark Horse Linux Package Manager (DPM)
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License as
* published by the Free Software Foundation, either version 3 of the
* License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*
* For bug reports or contributions, please contact the dhlp-contributors
* mailing list at: https://lists.darkhorselinux.org/mailman/listinfo/dhlp-contributors
*/
#pragma once
extern "C" {
// Log level enum that will be accessible to modules
/**
* @enum LoggingLevels
* @brief Enumeration of logging severity levels
*
* Defines the various severity levels for log messages in the DPM system.
* Lower values represent higher severity. This allows for filtering log
* messages based on their importance.
*/
enum LoggingLevels {
FATAL = 0,
ERROR = 1,
WARN = 2,
INFO = 3,
DEBUG = 4
FATAL = 0, /**< Critical errors that cause immediate program termination */
ERROR = 1, /**< Errors that prevent an operation from completing but allow program to continue */
WARN = 2, /**< Warning conditions that don't prevent operation but indicate potential issues */
INFO = 3, /**< Informational messages about normal program operation */
DEBUG = 4 /**< Detailed debug information for troubleshooting */
};
}

98
include/ModuleLoader.hpp
View File

@@ -42,29 +42,115 @@
#include "error.hpp"
#include "module_interface.hpp"
/**
* @class ModuleLoader
* @brief Handles dynamic loading and management of DPM modules
*
* Provides functionality for discovering, loading, validating, and executing
* DPM modules from shared object files. Ensures that modules conform to the
* required interface before allowing their execution.
*/
class ModuleLoader {
public:
// initializer
/**
* @brief Constructor
*
* Initializes a new ModuleLoader with the specified module path.
*
* @param module_path Directory path where DPM modules are located (defaults to /usr/lib/dpm/modules/)
*/
explicit ModuleLoader(std::string module_path = "/usr/lib/dpm/modules/");
/**
* @brief Lists available modules in the module path
*
* Populates a vector with the names of available modules found in
* the configured module path.
*
* @param modules Vector to populate with module names
* @return DPMErrorCategory indicating success or failure
*/
DPMErrorCategory list_available_modules(std::vector<std::string>& modules) const;
/**
* @brief Gets the configured module path
*
* Retrieves the directory path where modules are located.
*
* @param path Reference to store the module path
* @return DPMErrorCategory indicating success or failure
*/
DPMErrorCategory get_module_path(std::string& path) const;
// Load and execute methods
/**
* @brief Loads a module by name
*
* Attempts to dynamically load a module from the configured module path.
*
* @param module_name Name of the module to load
* @param module_handle Reference to store the loaded module handle
* @return DPMErrorCategory indicating success or failure
*/
DPMErrorCategory load_module(const std::string& module_name, void*& module_handle) const;
/**
* @brief Executes a module with the specified command
*
* Loads a module and executes its main entry point with the given command.
*
* @param module_name Name of the module to execute
* @param command Command string to pass to the module
* @return DPMErrorCategory indicating success or failure
*/
DPMErrorCategory execute_module(const std::string& module_name, const std::string& command) const;
// Get module version
/**
* @brief Gets a module's version information
*
* Retrieves the version string from a loaded module.
*
* @param module_handle Handle to a loaded module
* @param version Reference to store the version string
* @return DPMErrorCategory indicating success or failure
*/
DPMErrorCategory get_module_version(void* module_handle, std::string& version) const;
// Get module description
/**
* @brief Gets a module's description
*
* Retrieves the description string from a loaded module.
*
* @param module_handle Handle to a loaded module
* @param description Reference to store the description string
* @return DPMErrorCategory indicating success or failure
*/
DPMErrorCategory get_module_description(void* module_handle, std::string& description) const;
// Check if all required symbols from module_interface.hpp are exported by the module
/**
* @brief Validates a module's interface
*
* Checks if a loaded module exports all required symbols as defined
* in the module_interface.
*
* @param module_handle Handle to a loaded module
* @param missing_symbols Reference to store names of any missing required symbols
* @return DPMErrorCategory indicating success or failure
*/
DPMErrorCategory validate_module_interface(void* module_handle, std::vector<std::string>& missing_symbols) const;
// Helper method to check module path validity
/**
* @brief Checks module path validity
*
* Verifies that the configured module path exists, is a directory,
* and has the necessary permissions.
*
* @return DPMErrorCategory indicating success or failure
*/
DPMErrorCategory check_module_path() const;
private:
/**
* @brief Directory path where modules are located
*/
std::string _module_path;
};

37
include/dpm_interface.hpp
View File

@@ -41,16 +41,39 @@
#include "dpm_interface_helpers.hpp"
#include "Logger.hpp"
/*
*
* DPM Interface methods. These are wrappers of DPM functionality that are meant to handle user view, turning
* error codes into human-presentable information, etc. Features are defined internally, these will only ever be
* wrappers of existing features to provide the human/cli interface.
/**
* @defgroup dpm_interface DPM Interface Methods
* @brief Interface methods for the DPM command-line tool
*
* These functions provide the human-readable interface for the DPM utility,
* transforming error codes into user-friendly messages and implementing
* commands that report system information.
* @{
*/
// check if the module path exists
/**
* @brief Verifies that the module path exists and is accessible
*
* Checks if the configured module path exists, is a directory, and has
* the necessary read permissions. If any check fails, an appropriate
* error message is displayed.
*
* @param loader Reference to a ModuleLoader object that provides the module path
* @return 0 if the path exists and is accessible, 1 otherwise
*/
int main_check_module_path(const ModuleLoader& loader);
// list the modules
/**
* @brief Lists all available and valid DPM modules
*
* Retrieves and displays a formatted table of available DPM modules
* from the specified module path, including their versions and descriptions.
* Validates each module by checking for required symbols before including
* it in the list.
*
* @param loader Reference to a ModuleLoader object that provides access to modules
* @return 0 on success, 1 on failure
*/
int main_list_modules(const ModuleLoader& loader);
/** @} */ // end of dpm_interface group

32
include/dpm_interface_helpers.hpp
View File

@@ -38,13 +38,31 @@
#include "LoggingLevels.hpp"
#include "DPMDefaults.hpp"
// data structure for supplied arguments
/**
* @struct CommandArgs
* @brief Structure for storing parsed command-line arguments
*
* Contains fields for all command-line arguments that can be passed to
* the DPM utility, providing a structured way to access them throughout
* the application.
*/
struct CommandArgs {
std::string module_path;
std::string config_dir;
std::string module_name;
std::string command;
std::string module_path; /**< Path to the directory containing DPM modules */
std::string config_dir; /**< Path to the directory containing configuration files */
std::string module_name; /**< Name of the module to execute */
std::string command; /**< Command string to pass to the module */
};
// parse dpm cli arguments into a serialized structure
CommandArgs parse_args( int argc, char * argv[] );
/**
* @brief Parses command-line arguments into a CommandArgs structure
*
* Processes the arguments provided to DPM and organizes them into a
* CommandArgs structure for easier access. Handles options like
* --module-path, --config-dir, and --help, as well as module names
* and module-specific arguments.
*
* @param argc Number of command-line arguments
* @param argv Array of C-style strings containing the arguments
* @return A CommandArgs structure containing the parsed arguments
*/
CommandArgs parse_args(int argc, char* argv[]);

63
include/error.hpp
View File

@@ -32,31 +32,52 @@
#include <iostream>
// global errors for the core DPM routing/execution component
/**
* @enum DPMErrorCategory
* @brief Defines error categories for the DPM system
*
* Enumeration of all possible error conditions that can occur during
* DPM operations, particularly related to module loading and execution.
*/
enum class DPMErrorCategory {
SUCCESS,
PATH_NOT_FOUND,
PATH_NOT_DIRECTORY,
PATH_TOO_LONG,
PERMISSION_DENIED,
MODULE_NOT_FOUND,
MODULE_NOT_LOADED,
MODULE_LOAD_FAILED,
INVALID_MODULE,
SYMBOL_NOT_FOUND,
SYMBOL_EXECUTION_FAILED,
UNDEFINED_ERROR
SUCCESS, /**< Operation completed successfully */
PATH_NOT_FOUND, /**< The specified path does not exist */
PATH_NOT_DIRECTORY, /**< The specified path exists but is not a directory */
PATH_TOO_LONG, /**< The specified path exceeds the system's path length limit */
PERMISSION_DENIED, /**< Insufficient permissions to access the path */
MODULE_NOT_FOUND, /**< The specified module was not found in the module path */
MODULE_NOT_LOADED, /**< Failed to load the module (e.g., before executing it) */
MODULE_LOAD_FAILED, /**< Dynamic loading of the module failed */
INVALID_MODULE, /**< The module does not conform to the required interface */
SYMBOL_NOT_FOUND, /**< A required symbol was not found in the loaded module */
SYMBOL_EXECUTION_FAILED, /**< Execution of a module function failed */
UNDEFINED_ERROR /**< An undefined or unexpected error occurred */
};
// A generic context object that can hold any error-specific data
// only DPMErrorCategory is required, all other fields are optional
/**
* @struct FlexDPMError
* @brief Error context structure for DPM operations
*
* Provides context information for errors that occur during DPM operations.
* Only the error field is required; other fields can be populated as needed
* depending on the specific error condition.
*/
typedef struct {
DPMErrorCategory error;
const char * module_name;
const char * module_path;
const char * message;
DPMErrorCategory error; /**< The error category (required) */
const char * module_name; /**< Name of the module involved in the error (optional) */
const char * module_path; /**< Path to the modules directory (optional) */
const char * message; /**< Additional error message or context (optional) */
// Add other potential fields as needed as all fields beyond error are optional
} FlexDPMError;
// shorthand for creating a FlexDPMError instance
FlexDPMError make_error( DPMErrorCategory error_category );
/**
* @brief Creates a new FlexDPMError instance with the specified error category
*
* Utility function to simplify the creation of FlexDPMError structures.
* Initializes a new error context with the given error category and
* sets all other fields to NULL.
*
* @param error_category The error category to assign to the new error context
* @return A FlexDPMError structure with the specified error category
*/
FlexDPMError make_error(DPMErrorCategory error_category);

124
include/handlers.hpp
View File

@@ -33,21 +33,137 @@
#include <iostream>
#include "error.hpp"
// fatal error routing method
/**
* @brief Main error handler that dispatches to specific handlers
*
* Routes an error to the appropriate specialized handler based on the
* error category in the context. Validates required fields before calling
* the specialized handler.
*
* @param context Error context containing the error category and related information
* @return Exit code appropriate for the error condition (0 for success, non-zero for errors)
*/
int handle_error(FlexDPMError context);
// declare a required field
/**
* @brief Validates that a required field is present in the error context
*
* Checks if a field that is required for a specific error category is
* present in the error context. If the field is missing, outputs an
* error message and exits the program.
*
* @param context Error context to validate
* @param field_name Name of the field being validated (for error reporting)
* @param field_value Pointer to the field value
*/
void validate_field(FlexDPMError context, const char* field_name, const void* field_value);
// Individual error handler prototypes
/**
* @brief Handler for PATH_NOT_FOUND errors
*
* Reports that a specified path does not exist.
*
* @param context Error context with module_path field populated
* @return Exit code for the error condition
*/
int handle_path_not_found(FlexDPMError context);
/**
* @brief Handler for PATH_NOT_DIRECTORY errors
*
* Reports that a specified path exists but is not a directory.
*
* @param context Error context with module_path field populated
* @return Exit code for the error condition
*/
int handle_path_not_directory(FlexDPMError context);
/**
* @brief Handler for PATH_TOO_LONG errors
*
* Reports that a specified path exceeds the system's path length limit.
*
* @param context Error context with module_path field populated
* @return Exit code for the error condition
*/
int handle_path_too_long(FlexDPMError context);
/**
* @brief Handler for PERMISSION_DENIED errors
*
* Reports insufficient permissions to access a path.
*
* @param context Error context with module_path field populated
* @return Exit code for the error condition
*/
int handle_permission_denied(FlexDPMError context);
/**
* @brief Handler for MODULE_NOT_FOUND errors
*
* Reports that a specified module was not found in the module path.
*
* @param context Error context with module_name and module_path fields populated
* @return Exit code for the error condition
*/
int handle_module_not_found(FlexDPMError context);
/**
* @brief Handler for MODULE_NOT_LOADED errors
*
* Reports that a module could not be loaded.
*
* @param context Error context with module_name field populated
* @return Exit code for the error condition
*/
int handle_module_not_loaded(FlexDPMError context);
/**
* @brief Handler for MODULE_LOAD_FAILED errors
*
* Reports that dynamic loading of a module failed.
*
* @param context Error context with module_name field populated
* @return Exit code for the error condition
*/
int handle_module_load_failed(FlexDPMError context);
/**
* @brief Handler for INVALID_MODULE errors
*
* Reports that a module does not conform to the required interface.
*
* @param context Error context with module_name field populated
* @return Exit code for the error condition
*/
int handle_invalid_module(FlexDPMError context);
/**
* @brief Handler for SYMBOL_NOT_FOUND errors
*
* Reports that a required symbol was not found in a loaded module.
*
* @param context Error context with module_name field populated
* @return Exit code for the error condition
*/
int handle_symbol_not_found(FlexDPMError context);
/**
* @brief Handler for SYMBOL_EXECUTION_FAILED errors
*
* Reports that execution of a module function failed.
*
* @param context Error context with module_name field populated
* @return Exit code for the error condition
*/
int handle_symbol_execution_failed(FlexDPMError context);
int handle_undefined_error(FlexDPMError context);
/**
* @brief Handler for UNDEFINED_ERROR errors
*
* Reports an undefined or unexpected error.
*
* @param context Error context with optional module_name and message fields
* @return Exit code for the error condition
*/
int handle_undefined_error(FlexDPMError context);

75
include/module_interface.hpp
View File

@@ -38,13 +38,19 @@
#include "LoggingLevels.hpp"
#include "Logger.hpp"
/*
* Provides reserved symbol names we look for in modules.
/**
* @namespace module_interface
* @brief Namespace containing module interface definitions
*
* Provides reserved symbol names and interface definitions for DPM modules.
*/
// Define required symbols in one place
namespace module_interface {
// This is the single source of truth for required module symbols
/**
* @brief List of required symbols that every valid DPM module must export
*
* These function names must be exported by a module for the module to be
* considered valid and loadable by the DPM core system.
*/
static const std::vector<std::string> required_symbols = {
"dpm_module_execute",
"dpm_module_get_version",
@@ -52,20 +58,67 @@ namespace module_interface {
};
}
// Common interface for all DPM modules
/**
* @defgroup module_interface Common Interface for DPM Modules
* @brief Functions that modules must implement and core functions available to modules
* @{
*/
extern "C" {
// Module must export this symbol to be considered valid
/**
* @brief Main entry point for module execution
*
* This function must be implemented by all modules and serves as the
* primary execution point when the module is invoked by DPM.
*
* @param command The command string to execute
* @param argc Number of arguments provided
* @param argv Array of argument strings
* @return 0 on success, non-zero on failure
*/
int dpm_module_execute(const char* command, int argc, char** argv);
// Module version information
/**
* @brief Provides module version information
*
* Returns a string containing the module's version information.
* This is displayed when listing available modules.
*
* @return String containing the module's version
*/
const char* dpm_module_get_version(void);
// Module description information
/**
* @brief Provides module description
*
* Returns a human-readable description of the module's functionality.
* This is displayed when listing available modules.
*
* @return String containing the module's description
*/
const char* dpm_get_description(void);
// Direct configuration access function
/**
* @brief Accesses configuration values
*
* Allows modules to retrieve configuration values from the DPM
* configuration system. Implemented by the DPM core and available
* to all modules.
*
* @param section The configuration section name
* @param key The configuration key within the section
* @return The configuration value as a string, or NULL if not found
*/
const char* dpm_get_config(const char* section, const char* key);
// Direct logging function
/**
* @brief Logs messages through the DPM logging system
*
* Allows modules to log messages using the centralized DPM logging
* system. Implemented by the DPM core and available to all modules.
*
* @param level The log level as an integer (0=FATAL, 1=ERROR, 2=WARN, 3=INFO, 4=DEBUG)
* @param message The message to log
*/
void dpm_log(int level, const char* message);
}
/** @} */