diff options
| -rw-r--r-- | include/tinyff/result.h | 125 |
1 files changed, 89 insertions, 36 deletions
diff --git a/include/tinyff/result.h b/include/tinyff/result.h index 8f09a52..d57d7c4 100644 --- a/include/tinyff/result.h +++ b/include/tinyff/result.h @@ -1,45 +1,98 @@ -#ifndef RESULT_H -#define RESULT_H +#ifndef TINYFF_RESULT_H +#define TINYFF_RESULT_H #include <stdbool.h> +/** + * @brief Flags used to represent binary choices + */ typedef enum { - FF_TRUE = true, - FF_FALSE = false + FF_TRUE = true, ///< A true output/action + FF_FALSE = false ///< A false output/action } FF_FLAG; +/** + * @brief Master status codes for tinyff function operations. Returned by every (exported) function. + * + * This enumeration provides status codes to be returned from every single tinyff function + * to show what output the operation ended up doing. Operations will return FF_RESULT_OK + * when the function has done the explicit task it was meant to do. + * + * Warnings do not instantly mean that the function failed, but rather indicate that the + * operation completed under sub-optimal conditions, fallback behaviors, or without non-essential + * features enabled. In contrast, Error codes explicitly state that the operation has halted + * prematurely and failed to produce the intended output. + */ typedef enum { - // -- SUCCESS -- - FF_RESULT_OK = 0, - - // -- WARNINGS -- - FF_RESULT_WARN_DEBUG_DISABLED, - FF_RESULT_WARN_NO_IMPL, - - // -- ERRORS -- - - // File - FF_RESULT_ERROR_INVALID_FILE, - FF_RESULT_ERROR_READ_FILE_FAILURE, - - // Generic - FF_RESULT_ERROR_OUT_OF_BOUNDS, - FF_RESULT_ERROR_NULL_PTR, - - // Media specific - - // PNG - FF_RESULT_ERROR_INVALID_PNG_SIGNATURE, - - // BMP - FF_RESULT_ERROR_INVALID_BMP_SIGNATURE, - FF_RESULT_ERROR_INVALID_BMP_HEADER, - - // Archive (more general archives terms) - FF_RESULT_ERROR_DECOMPRESSION_FAILURE, - - // Memory - FF_RESULT_ERROR_MEMORY_ALLOCATION, + + /* ========================================================================= */ + /** @name Success Codes + * Operational states indicating successful completion. + */ + ///@{ + FF_RESULT_OK = 0, ///< Operation completed successfully and did not re/produce any errors. + ///@} + + /* ========================================================================= */ + /** @name Warning Codes + * Non-fatal notifications about limited functionality or disabled configurations. + */ + ///@{ + FF_RESULT_WARN_DEBUG_DISABLED, ///< Operation succeeded, but internal debug logging/tracing features are disabled. + FF_RESULT_WARN_NO_IMPL, ///< The requested optional feature or extension has no implementation in this build. + ///@} + + /* ========================================================================= */ + /** @name File System Errors + * Failures encountered during high-level file operations. + */ + ///@{ + FF_RESULT_ERROR_INVALID_FILE, ///< The specified file handle is invalid, corrupted, or cannot be accessed. + FF_RESULT_ERROR_READ_FILE_FAILURE, ///< A physical or software read error occurred while streaming data from the file. + ///@} + + /* ========================================================================= */ + /** @name Generic Runtime Errors + * Common execution safety violations. + */ + ///@{ + FF_RESULT_ERROR_OUT_OF_BOUNDS, ///< An index or data pointer exceeded the legal boundaries of the allocated buffer. + FF_RESULT_ERROR_NULL_PTR, ///< A critical argument or internal pointer was found to be NULL where data was expected. + ///@} + + /* ========================================================================= */ + /** @name PNG Media Errors + * Failures specific to Portable Network Graphics files. + */ + ///@{ + FF_RESULT_ERROR_INVALID_PNG_SIGNATURE, ///< The target data stream does not begin with the standard 8-byte PNG magic signature code. + ///@} + + /* ========================================================================= */ + /** @name BMP Media Errors + * Failures specific to Bitmap image files. + */ + ///@{ + FF_RESULT_ERROR_INVALID_BMP_SIGNATURE, ///< The target data stream lacks the standard 'BM' magic signature bytes. + FF_RESULT_ERROR_INVALID_BMP_HEADER, ///< The internal BITMAPINFOHEADER or BITMAPFILEHEADER structures contain invalid, corrupted, or unsupported metadata dimensions. + ///@} + + /* ========================================================================= */ + /** @name Archive Errors + * Failures regarding compressed or multi-file archives. + */ + ///@{ + FF_RESULT_ERROR_DECOMPRESSION_FAILURE, ///< The compression stream is corrupted or failed to inflate correctly during processing. + ///@} + + /* ========================================================================= */ + /** @name Memory Allocation Errors + * Failures regarding system resources. + */ + ///@{ + FF_RESULT_ERROR_MEMORY_ALLOCATION, ///< The system heap is exhausted, and the application failed to allocate the requested working memory block. + ///@} + } ff_result; -#endif
\ No newline at end of file +#endif |