crc-fast-rust: cleaning up for CI; implementing the Error for FFI.

Author: loadingalias

libcrc_fast.h

@@ -9,6 +9,44 @@
 #include <stdint.h>
 #include <stdlib.h>
 
+/**
+ * Error codes for FFI operations
+ */
+typedef enum CrcFastError {
+  /**
+   * Operation completed successfully
+   */
+  Success = 0,
+  /**
+   * Lock was poisoned (thread panicked while holding lock)
+   */
+  LockPoisoned = 1,
+  /**
+   * Null pointer was passed where non-null required
+   */
+  NullPointer = 2,
+  /**
+   * Invalid key count for CRC parameters
+   */
+  InvalidKeyCount = 3,
+  /**
+   * Unsupported CRC width (must be 32 or 64)
+   */
+  UnsupportedWidth = 4,
+  /**
+   * Invalid UTF-8 string
+   */
+  InvalidUtf8 = 5,
+  /**
+   * File I/O error
+   */
+  IoError = 6,
+  /**
+   * Internal string conversion error
+   */
+  StringConversionError = 7,
+} CrcFastError;
+
 /**
  * The supported CRC algorithms
  */
@@ -72,6 +110,23 @@ typedef struct CrcFastParams {
 extern "C" {
 #endif // __cplusplus
 
+/**
+ * Gets the last error that occurred in the current thread
+ * Returns CrcFastError::Success if no error has occurred
+ */
+enum CrcFastError crc_fast_get_last_error(void);
+
+/**
+ * Clears the last error for the current thread
+ */
+void crc_fast_clear_error(void);
+
+/**
+ * Gets a human-readable error message for the given error code
+ * Returns a pointer to a static string (do not free)
+ */
+const char *crc_fast_error_message(enum CrcFastError error);
+
 /**
  * Creates a new Digest to compute CRC checksums using algorithm
  */
@@ -86,6 +141,7 @@ struct CrcFastDigestHandle *crc_fast_digest_new_with_init_state(enum CrcFastAlgo
 /**
  * Creates a new Digest to compute CRC checksums using custom parameters
  * Returns NULL if parameters are invalid (invalid key count or null pointer)
+ * Call crc_fast_get_last_error() to get the specific error code
  */
 struct CrcFastDigestHandle *crc_fast_digest_new_with_params(struct CrcFastParams params);
 
@@ -96,6 +152,7 @@ void crc_fast_digest_update(struct CrcFastDigestHandle *handle, const char *data
 
 /**
  * Calculates the CRC checksum for data that's been written to the Digest
+ * Returns 0 on error (e.g. null handle)
  */
 uint64_t crc_fast_digest_finalize(struct CrcFastDigestHandle *handle);
 
@@ -111,6 +168,7 @@ void crc_fast_digest_reset(struct CrcFastDigestHandle *handle);
 
 /**
  * Finalize and reset the Digest in one operation
+ * Returns 0 on error (e.g. null handle)
  */
 uint64_t crc_fast_digest_finalize_reset(struct CrcFastDigestHandle *handle);
 
@@ -122,22 +180,26 @@ void crc_fast_digest_combine(struct CrcFastDigestHandle *handle1,
 
 /**
  * Gets the amount of data processed by the Digest so far
+ * Returns 0 on error (e.g. null handle)
  */
 uint64_t crc_fast_digest_get_amount(struct CrcFastDigestHandle *handle);
 
 /**
  * Gets the current state of the Digest
+ * Returns 0 on error (e.g. null handle)
  */
 uint64_t crc_fast_digest_get_state(struct CrcFastDigestHandle *handle);
 
 /**
  * Helper method to calculate a CRC checksum directly for a string using algorithm
+ * Returns 0 on error (e.g. null data pointer)
  */
 uint64_t crc_fast_checksum(enum CrcFastAlgorithm algorithm, const char *data, uintptr_t len);
 
 /**
  * Helper method to calculate a CRC checksum directly for data using custom parameters
  * Returns 0 if parameters are invalid or data is null
+ * Call crc_fast_get_last_error() to get the specific error code
  */
 uint64_t crc_fast_checksum_with_params(struct CrcFastParams params,
                                        const char *data,
@@ -146,6 +208,7 @@ uint64_t crc_fast_checksum_with_params(struct CrcFastParams params,
 /**
  * Helper method to just calculate a CRC checksum directly for a file using algorithm
  * Returns 0 if path is null or file I/O fails
+ * Call crc_fast_get_last_error() to get the specific error code
  */
 uint64_t crc_fast_checksum_file(enum CrcFastAlgorithm algorithm,
                                 const uint8_t *path_ptr,
@@ -154,6 +217,7 @@ uint64_t crc_fast_checksum_file(enum CrcFastAlgorithm algorithm,
 /**
  * Helper method to calculate a CRC checksum directly for a file using custom parameters
  * Returns 0 if parameters are invalid, path is null, or file I/O fails
+ * Call crc_fast_get_last_error() to get the specific error code
  */
 uint64_t crc_fast_checksum_file_with_params(struct CrcFastParams params,
                                             const uint8_t *path_ptr,
@@ -170,6 +234,7 @@ uint64_t crc_fast_checksum_combine(enum CrcFastAlgorithm algorithm,
 /**
  * Combine two CRC checksums using custom parameters
  * Returns 0 if parameters are invalid
+ * Call crc_fast_get_last_error() to get the specific error code
  */
 uint64_t crc_fast_checksum_combine_with_params(struct CrcFastParams params,
                                                uint64_t checksum1,
@@ -178,6 +243,7 @@ uint64_t crc_fast_checksum_combine_with_params(struct CrcFastParams params,
 
 /**
  * Returns the custom CRC parameters for a given set of Rocksoft CRC parameters
+ * If width is not 32 or 64, sets error to UnsupportedWidth
  */
 struct CrcFastParams crc_fast_get_custom_params(const char *name_ptr,
                                                 uint8_t width,
@@ -189,7 +255,8 @@ struct CrcFastParams crc_fast_get_custom_params(const char *name_ptr,
 
 /**
  * Gets the target build properties (CPU architecture and fine-tuning parameters) for this algorithm
- * Returns NULL if string conversion fails (should never happen)
+ * Returns NULL if string conversion fails
+ * Call crc_fast_get_last_error() to get the specific error code
  */
 const char *crc_fast_get_calculator_target(enum CrcFastAlgorithm algorithm);