[*.h] Expand documentation ; [acquire/tests/test_url_utils.h] New test suite ; [acquire/tests/test_checksum.h] Massively expand test suite ; [acquire/tests/CMakeLists.txt] Ensure included test headers are also explicitly referenced here

Author: SamuelMarks

acquire/acquire_checksums.h

@@ -1,13 +1,18 @@
-/*
- * Prototype for checksum API
- *
- * Always `#include` this when adding new checksum implementations,
- * to ensure the implementation matches the prototype.
- * */
-
 #ifndef LIBACQUIRE_ACQUIRE_CHECKSUMS_H
 #define LIBACQUIRE_ACQUIRE_CHECKSUMS_H
 
+/**
+ * @file acquire_checksums.h
+ * @brief Collection of checksum function declarations and interface.
+ *
+ * This header declares typedefs and functions for computing and verifying
+ * various checksum algorithms like crc32c, md5, sha1, etc.
+ * Also provides functionality to get checksum function by name.
+ *
+ * NOTE: Always `#include` this when adding new checksum implementations,
+ * to ensure the implementation matches the prototype.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */
@@ -21,11 +26,42 @@ extern "C" {
 #include "acquire_config.h"
 #include "acquire_string_extras.h"
 
-extern LIBACQUIRE_LIB_EXPORT bool crc32c(const char *, const char *);
+/**
+ * @brief Boolean result type alias for checksum validation functions.
+ */
 
-extern LIBACQUIRE_LIB_EXPORT bool sha256(const char *, const char *);
+/**
+ * @brief Verify file using CRC32C checksum.
+ *
+ * @param filename Path to file.
+ * @param hash Expected CRC32C checksum string.
+ *
+ * @return true if valid.
+ */
+extern LIBACQUIRE_LIB_EXPORT bool crc32c(const char *filename,
+                                         const char *hash);
 
-extern LIBACQUIRE_LIB_EXPORT bool sha512(const char *, const char *);
+/**
+ * @brief Verify file using SHA256 checksum.
+ *
+ * @param filename Path to file.
+ * @param hash Expected checksum string.
+ *
+ * @return true if valid.
+ */
+extern LIBACQUIRE_LIB_EXPORT bool sha256(const char *filename,
+                                         const char *hash);
+
+/**
+ * @brief Verify file using SHA256 checksum.
+ *
+ * @param filename Path to file.
+ * @param hash Expected checksum string.
+ *
+ * @return true if valid.
+ */
+extern LIBACQUIRE_LIB_EXPORT bool sha512(const char *filename,
+                                         const char *hash);
 
 enum Checksum {
   LIBACQUIRE_CRC32C,
@@ -36,8 +72,19 @@ enum Checksum {
 
 extern LIBACQUIRE_LIB_EXPORT enum Checksum string2checksum(const char *);
 
-extern LIBACQUIRE_LIB_EXPORT bool (*get_checksum_function(enum Checksum))(
-    const char *, const char *);
+/**
+ * @brief Obtain a pointer to a checksum function by name.
+ *
+ * Returns a pointer to a function matching the
+ * signature of checksum_func_t, or NULL if not found.
+ *
+ * @param checksum Discriminant from `enum Checksum` representing checksum
+ * algorithm
+ *
+ * @return Function pointer on success; NULL on failure.
+ */
+extern LIBACQUIRE_LIB_EXPORT bool (
+    *get_checksum_function(enum Checksum checksum))(const char *, const char *);
 
 #ifdef LIBACQUIRE_IMPLEMENTATION
 

acquire/acquire_common_defs.h

@@ -1,12 +1,14 @@
-/*
- * Common definitions used through libacquire
- *
- * Defines things like `PATH_SEP`, `MAX_FILENAME`, and `NAME_MAX`
- * */
-
 #ifndef LIBACQUIRE_ACQUIRE_COMMON_DEFS_H
 #define LIBACQUIRE_ACQUIRE_COMMON_DEFS_H
 
+/**
+ * @file acquire_common_defs.h
+ * @brief Common macros, constants, and definitions used throughout libacquire.
+ *
+ * This header defines frequently used constants, macros for error handling,
+ * log level definitions, and other common values.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */

acquire/acquire_crc32c.h

@@ -1,17 +1,14 @@
-/*
- * Taken from FreeBSD implementation of CRC32C, specifically:
- * - usr.bin\cksum\crc32_algo.c @ d91d2b513eb30a226e87f0e52e2f9f232a2e1ca3
- *
- * Actually taken from:
- * - https://gist.github.com/Jessidhia/1484174
- *
- * Alternatives are to use `zlib`'s CRC32C impl conditionally or RHash or miniz
- * */
-
-#if !defined(LIBACQUIRE_ACQUIRE_CRC32C_H) &&                                   \
-    defined(LIBACQUIRE_IMPLEMENTATION) && defined(USE_CRC32C)
+#ifndef LIBACQUIRE_ACQUIRE_CRC32C_H
 #define LIBACQUIRE_ACQUIRE_CRC32C_H
 
+/**
+ * @file acquire_crc32c.h
+ * @brief Header declaring the CRC32C checksum verification function.
+ *
+ * This header provides the interface and implementation of a function
+ * to compute and verify the CRC32C checksum of a file against a known hash.
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #elif defined(HAS_STDBOOL) && !defined(bool)
@@ -20,6 +17,33 @@ extern "C" {
 #include "acquire_stdbool.h"
 #endif /* __cplusplus */
 
+#include <stdio.h>
+
+/**
+ * @brief Verify the CRC32C checksum of a given file against an expected hash
+ * string.
+ *
+ * Opens the file, computes its CRC32C checksum, then compares it with the input
+ * hash string case-insensitively.
+ *
+ * @param filename Path to the file to be validated.
+ * @param hash Expected CRC32C checksum string in hexadecimal (8 characters).
+ *
+ * @return true if computed checksum matches input hash, false otherwise or on
+ * error.
+ */
+extern bool crc32c(const char *filename, const char *hash);
+
+/*
+ * Taken from FreeBSD implementation of CRC32C, specifically:
+ * - usr.bin\cksum\crc32_algo.c @ d91d2b513eb30a226e87f0e52e2f9f232a2e1ca3
+ *
+ * Actually taken from:
+ * - https://gist.github.com/Jessidhia/1484174
+ *
+ * Alternatives are to use `zlib`'s CRC32C impl conditionally or RHash or miniz
+ * */
+
 #define CHUNK_SIZE 4096
 
 #include <stdio.h>
@@ -33,7 +57,7 @@ extern "C" {
 
 #ifndef O_BINARY
 #define O_BINARY 0
-#endif
+#endif /* !O_BINARY */
 
 unsigned int crc32_file(FILE *file);
 unsigned int crc32_algo(unsigned int iv, unsigned char *buf, long long len);
@@ -101,40 +125,43 @@ unsigned int crc32_file(FILE *file) {
   return crc;
 }
 
+#ifdef LIBACQUIRE_IMPLEMENTATION
+#ifdef USE_CRC32C
+
+/**
+ * @brief Implementation of CRC32C checksum verification.
+ *
+ * Reads the file and computes its CRC32C checksum, then compares with
+ * the hash string ignoring character cases.
+ */
 bool crc32c(const char *filename, const char *hash) {
   unsigned int crc32_res;
   FILE *fh;
-  /* Format computed CRC32C in hex into buffer 9 chars, zero terminated */
   char computed[9];
-#if defined(_MSC_VER) || defined(__STDC_LIB_EXT1__) && __STDC_WANT_LIB_EXT1__
+
+#if defined(_MSC_VER) || (defined(__STDC_LIB_EXT1__) && __STDC_WANT_LIB_EXT1__)
   fopen_s(&fh, filename, "rb");
 #else
   fh = fopen(filename, "rb");
-#endif
-  if (fh != NULL) {
-    crc32_res = crc32_file(fh);
-    printf("crc32_res: %x\n", crc32_res);
-    fclose(fh);
-  }
-  return true;
+#endif /* defined(_MSC_VER) || (defined(__STDC_LIB_EXT1__) &&                  \
+          __STDC_WANT_LIB_EXT1__) */
+  if (fh == NULL)
+    return false;
 
   crc32_res = crc32_file(fh);
   fclose(fh);
 
-  /* Verify CRC32C checksum: input hash string expected to be hex digits */
   snprintf(computed, sizeof(computed), "%08x", crc32_res);
 
-  /* Case insensitive compare */
   {
     int i;
     for (i = 0; computed[i] && hash[i]; i++) {
       char c1 = computed[i];
       char c2 = hash[i];
-      /* convert both to lowercase */
       if (c1 >= 'A' && c1 <= 'F')
-        c1 += ('a' - 'A');
+        c1 += 'a' - 'A';
       if (c2 >= 'A' && c2 <= 'F')
-        c2 += ('a' - 'A');
+        c2 += 'a' - 'A';
       if (c1 != c2)
         return false;
     }
@@ -144,9 +171,11 @@ bool crc32c(const char *filename, const char *hash) {
   return true;
 }
 
+#endif /* USE_CRC32C */
+#endif /* LIBACQUIRE_IMPLEMENTATION */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
 
-#endif /* !defined(LIBACQUIRE_ACQUIRE_CRC32C_H) &&                             \
-          defined(LIBACQUIRE_IMPLEMENTATION) && defined(USE_CRC32C) */
+#endif /* !LIBACQUIRE_ACQUIRE_CRC32C_H */

acquire/acquire_download.h

@@ -1,13 +1,17 @@
-/*
- * Prototype for download API
- *
- * Always `#include` this when adding new download implementations,
- * to ensure the implementation matches the prototype.
- * */
-
 #ifndef LIBACQUIRE_ACQUIRE_DOWNLOAD_H
 #define LIBACQUIRE_ACQUIRE_DOWNLOAD_H
 
+/**
+ * @file acquire_download.h
+ * @brief Functionality to download files from network locations.
+ *
+ * This module handles downloading files via protocols like HTTP(S),
+ * providing progress monitoring and retry logic support.
+ *
+ * NOTE: Always `#include` this when adding new download implementations,
+ * to ensure the implementation matches the prototype.
+ */
+
 #include <stdlib.h>
 
 #ifdef __cplusplus

acquire/acquire_extract.h

@@ -1,15 +1,24 @@
 /*
  * Prototype for extract API
  *
- * Always `#include` this when adding new extraction implementations,
- * to ensure the implementation matches the prototype.
  *
- * The extract API is for expanding the contents of archives
  * */
 
 #ifndef LIBACQUIRE_ACQUIRE_EXTRACT_H
 #define LIBACQUIRE_ACQUIRE_EXTRACT_H
 
+/**
+ * @file acquire_extract.h
+ * @brief Extraction of compressed archives.
+ *
+ * Provides functions to decompress and extract files from archives,
+ * supporting common formats like ZIP, TAR, GZ, etc.
+ * NOTE: Always `#include` this when adding new extraction
+ * implementations, to ensure implementation matches the prototype.
+ *
+ * The extract API is for expanding the contents of archives
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */
@@ -22,10 +31,34 @@ enum LIBACQUIRE_LIB_EXPORT Archive {
   LIBACQUIRE_UNSUPPORTED_ARCHIVE
 };
 
-extern LIBACQUIRE_LIB_EXPORT int extract_archive(enum Archive, const char *,
-                                                 const char *);
+/**
+ * @brief Extract an archive file into a specified directory.
+ *
+ * Supports formats based on `enum Archive` discriminant.
+ *
+ * @param archive `enum Archive` discriminant type of archive.
+ * @param archive_filepath Path to the archive file.
+ * @param output_folder Directory path where contents should be extracted.
+ *
+ * @return `EXIT_SUCCESS` if extraction succeeds;
+ * `EXIT_FAILURE` or non-`EXIT_SUCCESS` otherwise.
+ */
+extern LIBACQUIRE_LIB_EXPORT int extract_archive(enum Archive archive,
+                                                 const char *archive_filepath,
+                                                 const char *output_folder);
 
-extern LIBACQUIRE_LIB_EXPORT enum Archive extension2archive(const char *);
+/**
+ * @brief Determine archive type based on extension
+ *
+ * TODO: magic bytes whence `LIBACQUIRE_INFER`
+ *
+ * @param extension Simple end of path, like ".zip" or ".tar.gz".
+ *
+ * @return `enum Archive` discriminant; including potential values of
+ * `LIBACQUIRE_UNSUPPORTED_ARCHIVE` xor `LIBACQUIRE_INFER`.
+ */
+extern LIBACQUIRE_LIB_EXPORT enum Archive
+extension2archive(const char *extension);
 
 #ifdef LIBACQUIRE_IMPLEMENTATION