mirror of
https://github.com/aaru-dps/libaaruformat.git
synced 2025-12-16 19:24:40 +00:00
Enhance documentation for various structures with detailed descriptions and formatting improvements
This commit is contained in:
@@ -19,35 +19,136 @@
|
||||
#ifndef LIBAARUFORMAT_ERRORS_H
|
||||
#define LIBAARUFORMAT_ERRORS_H
|
||||
|
||||
#define AARUF_ERROR_NOT_AARUFORMAT (-1)
|
||||
#define AARUF_ERROR_FILE_TOO_SMALL (-2)
|
||||
#define AARUF_ERROR_INCOMPATIBLE_VERSION (-3)
|
||||
#define AARUF_ERROR_CANNOT_READ_INDEX (-4)
|
||||
#define AARUF_ERROR_SECTOR_OUT_OF_BOUNDS (-5)
|
||||
#define AARUF_ERROR_CANNOT_READ_HEADER (-6)
|
||||
#define AARUF_ERROR_CANNOT_READ_BLOCK (-7)
|
||||
#define AARUF_ERROR_UNSUPPORTED_COMPRESSION (-8)
|
||||
#define AARUF_ERROR_NOT_ENOUGH_MEMORY (-9)
|
||||
#define AARUF_ERROR_BUFFER_TOO_SMALL (-10)
|
||||
#define AARUF_ERROR_MEDIA_TAG_NOT_PRESENT (-11)
|
||||
#define AARUF_ERROR_INCORRECT_MEDIA_TYPE (-12)
|
||||
#define AARUF_ERROR_TRACK_NOT_FOUND (-13)
|
||||
#define AARUF_ERROR_REACHED_UNREACHABLE_CODE (-14)
|
||||
#define AARUF_ERROR_INVALID_TRACK_FORMAT (-15)
|
||||
#define AARUF_ERROR_SECTOR_TAG_NOT_PRESENT (-16)
|
||||
#define AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK (-17)
|
||||
#define AARUF_ERROR_INVALID_BLOCK_CRC (-18)
|
||||
#define AARUF_ERROR_CANNOT_CREATE_FILE (-19)
|
||||
#define AARUF_ERROR_INVALID_APP_NAME_LENGTH (-20)
|
||||
#define AARUF_ERROR_CANNOT_WRITE_HEADER (-21)
|
||||
#define AARUF_READ_ONLY (-22)
|
||||
#define AARUF_ERROR_CANNOT_WRITE_BLOCK_HEADER (-23)
|
||||
#define AARUF_ERROR_CANNOT_WRITE_BLOCK_DATA (-24)
|
||||
#define AARUF_ERROR_CANNOT_SET_DDT_ENTRY (-25)
|
||||
/** \file aaruformat/errors.h
|
||||
* \brief Public error and status code definitions for libaaruformat.
|
||||
*
|
||||
* Negative values represent fatal / non-recoverable error conditions returned by library functions.
|
||||
* Non-negative values (>=0) are either success (0) or sector-level status annotations used when
|
||||
* decoding per-sector metadata (e.g. a sector not dumped or with corrected/unrecoverable errors).
|
||||
*
|
||||
* Usage guidelines:
|
||||
* - Always test for < 0 to check generic failure without enumerating all codes.
|
||||
* - Use exact comparisons for caller-specific handling (e.g. retry on AARUF_ERROR_CANNOT_READ_BLOCK).
|
||||
* - Sector status codes are never returned as fatal function results; they appear in output parameters
|
||||
* populated by read/identify routines.
|
||||
*
|
||||
* Helper: see aaruformat_error_string() for a human-readable textual description suitable for logs.
|
||||
*/
|
||||
|
||||
#define AARUF_STATUS_OK 0
|
||||
#define AARUF_STATUS_SECTOR_NOT_DUMPED 1
|
||||
#define AARUF_STATUS_SECTOR_WITH_ERRORS 2
|
||||
#define AARUF_STATUS_SECTOR_DELETED 3
|
||||
/** \name Fatal / library-level error codes (negative)
|
||||
* @{ */
|
||||
#define AARUF_ERROR_NOT_AARUFORMAT (-1) ///< Input file/stream failed magic or structural validation.
|
||||
#define AARUF_ERROR_FILE_TOO_SMALL (-2) ///< File size insufficient for mandatory header / structures.
|
||||
#define AARUF_ERROR_INCOMPATIBLE_VERSION (-3) ///< Image uses a newer incompatible on-disk version.
|
||||
#define AARUF_ERROR_CANNOT_READ_INDEX (-4) ///< Index block unreadable / truncated / bad identifier.
|
||||
#define AARUF_ERROR_SECTOR_OUT_OF_BOUNDS (-5) ///< Requested logical sector outside media bounds.
|
||||
#define AARUF_ERROR_CANNOT_READ_HEADER (-6) ///< Failed to read container header.
|
||||
#define AARUF_ERROR_CANNOT_READ_BLOCK (-7) ///< Generic block read failure (seek/read error).
|
||||
#define AARUF_ERROR_UNSUPPORTED_COMPRESSION (-8) ///< Block marked with unsupported compression algorithm.
|
||||
#define AARUF_ERROR_NOT_ENOUGH_MEMORY (-9) ///< Memory allocation failure (critical).
|
||||
#define AARUF_ERROR_BUFFER_TOO_SMALL (-10) ///< Caller-supplied buffer insufficient for data.
|
||||
#define AARUF_ERROR_MEDIA_TAG_NOT_PRESENT (-11) ///< Requested media tag absent.
|
||||
#define AARUF_ERROR_INCORRECT_MEDIA_TYPE (-12) ///< Operation incompatible with image media type.
|
||||
#define AARUF_ERROR_TRACK_NOT_FOUND (-13) ///< Referenced track number not present.
|
||||
#define AARUF_ERROR_REACHED_UNREACHABLE_CODE (-14) ///< Internal logic assertion hit unexpected path.
|
||||
#define AARUF_ERROR_INVALID_TRACK_FORMAT (-15) ///< Track metadata internally inconsistent or malformed.
|
||||
#define AARUF_ERROR_SECTOR_TAG_NOT_PRESENT (-16) ///< Requested sector tag (e.g. subchannel/prefix) not stored.
|
||||
#define AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK (-17) ///< Decompression routine failed or size mismatch.
|
||||
#define AARUF_ERROR_INVALID_BLOCK_CRC (-18) ///< CRC64 mismatch indicating corruption.
|
||||
#define AARUF_ERROR_CANNOT_CREATE_FILE (-19) ///< Output file could not be created / opened for write.
|
||||
#define AARUF_ERROR_INVALID_APP_NAME_LENGTH (-20) ///< Application name field length invalid (sanity limit).
|
||||
#define AARUF_ERROR_CANNOT_WRITE_HEADER (-21) ///< Failure writing container header.
|
||||
#define AARUF_READ_ONLY (-22) ///< Operation requires write mode but context is read-only.
|
||||
#define AARUF_ERROR_CANNOT_WRITE_BLOCK_HEADER (-23) ///< Failure writing block header.
|
||||
#define AARUF_ERROR_CANNOT_WRITE_BLOCK_DATA (-24) ///< Failure writing block payload.
|
||||
#define AARUF_ERROR_CANNOT_SET_DDT_ENTRY (-25) ///< Failed to encode/store a DDT entry (overflow or IO).
|
||||
/** @} */
|
||||
|
||||
/** \name Non-fatal sector status codes (non-negative)
|
||||
* Returned through output parameters to describe individual sector state.
|
||||
* @{ */
|
||||
#define AARUF_STATUS_OK 0 ///< Sector present and read without uncorrectable errors.
|
||||
#define AARUF_STATUS_SECTOR_NOT_DUMPED 1 ///< Sector not captured (gap / missing / intentionally skipped).
|
||||
#define AARUF_STATUS_SECTOR_WITH_ERRORS 2 ///< Sector present but with unrecoverable or flagged errors.
|
||||
#define AARUF_STATUS_SECTOR_DELETED 3 ///< Sector logically marked deleted (e.g. filesystem deleted area).
|
||||
|
||||
/** @} */
|
||||
|
||||
/** \brief Convert an AaruFormat error or status code to a static human-readable string.
|
||||
*
|
||||
* Designed for diagnostics / logging; returns a constant string literal. Unknown codes yield
|
||||
* "Unknown error/status". This helper is inline to avoid adding a separate translation unit.
|
||||
*
|
||||
* \param code Error (<0) or status (>=0) numeric code.
|
||||
* \return Constant C string describing the code.
|
||||
*/
|
||||
static inline const char *aaruformat_error_string(int code)
|
||||
{
|
||||
switch(code)
|
||||
{
|
||||
/* Errors */
|
||||
case AARUF_ERROR_NOT_AARUFORMAT:
|
||||
return "Not an AaruFormat image";
|
||||
case AARUF_ERROR_FILE_TOO_SMALL:
|
||||
return "File too small";
|
||||
case AARUF_ERROR_INCOMPATIBLE_VERSION:
|
||||
return "Incompatible image version";
|
||||
case AARUF_ERROR_CANNOT_READ_INDEX:
|
||||
return "Cannot read index";
|
||||
case AARUF_ERROR_SECTOR_OUT_OF_BOUNDS:
|
||||
return "Sector out of bounds";
|
||||
case AARUF_ERROR_CANNOT_READ_HEADER:
|
||||
return "Cannot read header";
|
||||
case AARUF_ERROR_CANNOT_READ_BLOCK:
|
||||
return "Cannot read block";
|
||||
case AARUF_ERROR_UNSUPPORTED_COMPRESSION:
|
||||
return "Unsupported compression";
|
||||
case AARUF_ERROR_NOT_ENOUGH_MEMORY:
|
||||
return "Not enough memory";
|
||||
case AARUF_ERROR_BUFFER_TOO_SMALL:
|
||||
return "Buffer too small";
|
||||
case AARUF_ERROR_MEDIA_TAG_NOT_PRESENT:
|
||||
return "Media tag not present";
|
||||
case AARUF_ERROR_INCORRECT_MEDIA_TYPE:
|
||||
return "Incorrect media type";
|
||||
case AARUF_ERROR_TRACK_NOT_FOUND:
|
||||
return "Track not found";
|
||||
case AARUF_ERROR_REACHED_UNREACHABLE_CODE:
|
||||
return "Internal unreachable code reached";
|
||||
case AARUF_ERROR_INVALID_TRACK_FORMAT:
|
||||
return "Invalid track format";
|
||||
case AARUF_ERROR_SECTOR_TAG_NOT_PRESENT:
|
||||
return "Sector tag not present";
|
||||
case AARUF_ERROR_CANNOT_DECOMPRESS_BLOCK:
|
||||
return "Cannot decompress block";
|
||||
case AARUF_ERROR_INVALID_BLOCK_CRC:
|
||||
return "Invalid block CRC";
|
||||
case AARUF_ERROR_CANNOT_CREATE_FILE:
|
||||
return "Cannot create file";
|
||||
case AARUF_ERROR_INVALID_APP_NAME_LENGTH:
|
||||
return "Invalid application name length";
|
||||
case AARUF_ERROR_CANNOT_WRITE_HEADER:
|
||||
return "Cannot write header";
|
||||
case AARUF_READ_ONLY:
|
||||
return "Read-only context";
|
||||
case AARUF_ERROR_CANNOT_WRITE_BLOCK_HEADER:
|
||||
return "Cannot write block header";
|
||||
case AARUF_ERROR_CANNOT_WRITE_BLOCK_DATA:
|
||||
return "Cannot write block data";
|
||||
case AARUF_ERROR_CANNOT_SET_DDT_ENTRY:
|
||||
return "Cannot set DDT entry";
|
||||
|
||||
/* Status */
|
||||
case AARUF_STATUS_OK:
|
||||
return "OK";
|
||||
case AARUF_STATUS_SECTOR_NOT_DUMPED:
|
||||
return "Sector not dumped";
|
||||
case AARUF_STATUS_SECTOR_WITH_ERRORS:
|
||||
return "Sector with errors";
|
||||
case AARUF_STATUS_SECTOR_DELETED:
|
||||
return "Sector deleted";
|
||||
}
|
||||
return "Unknown error/status";
|
||||
}
|
||||
|
||||
#endif // LIBAARUFORMAT_ERRORS_H
|
||||
|
||||
Reference in New Issue
Block a user