Skip to content

Commit 10ec345

Browse files
SamuelMarksSamuelMarks
committed
[*.h,*.c,CMakeLists.txt] Implement async and sync APIs for more libraries ; add tests for this ; [acquire/acquire_handle.h] incorporate global async&sync handling ; [acquire/acquire_status_codes.h] Implement global error handling
1 parent 3b13d44 commit 10ec345

16 files changed

+706
-706
lines changed

‎acquire/CMakeLists.txt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,9 @@ else ()
8585
"acquire_download.h"
8686
"acquire_extract.h"
8787
"acquire_fileutils.h"
88+
"acquire_handle.h"
8889
"acquire_net_common.h"
90+
"acquire_status_codes.h"
8991
"acquire_string_extras.h"
9092
"acquire_url_utils.h"
9193
)
@@ -257,6 +259,16 @@ else ()
257259
)
258260
list(APPEND impls "LIBACQUIRE_ACQUIRE_FILEUTILS_IMPL")
259261
endif (NOT ("LIBACQUIRE_ACQUIRE_FILEUTILS_IMPL" IN_LIST impls))
262+
263+
##########
264+
# Handle #
265+
##########
266+
elseif (src MATCHES "/gen_acquire_handle.c$")
267+
set_source_files_properties(
268+
${src} PROPERTIES
269+
COMPILE_DEFINITIONS "LIBACQUIRE_IMPLEMENTATION=1;LIBACQUIRE_HANDLE_IMPL=1"
270+
)
271+
260272
#################
261273
# String extras #
262274
#################

‎acquire/acquire_download.h‎

Lines changed: 5 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -2,135 +2,31 @@
22
#ifndef LIBACQUIRE_ACQUIRE_DOWNLOAD_H
33
#define LIBACQUIRE_ACQUIRE_DOWNLOAD_H
44

5-
/**
6-
* @file acquire_download.h
7-
* @brief Public API for synchronous and asynchronous file downloads.
8-
*
9-
* This module provides both synchronous (blocking) and asynchronous
10-
* (non-blocking) APIs for downloading files. Operations are managed
11-
* through a stateful `acquire_handle`.
12-
*/
5+
#include "acquire_handle.h"
6+
#include "libacquire_export.h"
137

148
#ifdef __cplusplus
159
extern "C" {
16-
#endif /* __cplusplus */
17-
18-
#include "acquire_checksums.h"
19-
#include "acquire_config.h"
20-
#include "acquire_fileutils.h"
21-
#include "acquire_url_utils.h"
22-
#include "libacquire_export.h"
23-
24-
#include <stdio.h> /* For FILE* */
25-
#include <sys/types.h> /* For off_t */
26-
27-
/* --- Asynchronous Operation Status --- */
28-
29-
/**
30-
* @brief Describes the current state of an asynchronous operation.
31-
*/
32-
enum acquire_status {
33-
ACQUIRE_IDLE, /* The handle is ready but no operation is active. */
34-
ACQUIRE_IN_PROGRESS, /* The operation is running. */
35-
ACQUIRE_COMPLETE, /* The operation finished successfully. */
36-
ACQUIRE_ERROR_CANCELLED, /* The operation was cancelled by the user. */
37-
ACQUIRE_ERROR /* The operation failed. */
38-
};
39-
40-
/* --- Download Operation Handle --- */
41-
42-
/**
43-
* @brief A handle managing the state of a single download operation.
44-
* The definition is public to avoid a typedef, per project constraints.
45-
* Fields marked "Internal use" should not be modified by the user.
46-
*/
47-
struct acquire_handle {
48-
/* --- Publicly readable state --- */
49-
off_t bytes_downloaded;
50-
off_t total_size;
51-
enum acquire_status status;
52-
char error_message[256];
53-
54-
/* --- Internal use only --- */
55-
int cancel_flag;
56-
void *backend_handle; /* Opaque handle for backend-specific data. */
57-
FILE *output_file;
58-
};
59-
60-
/* --- Handle Management --- */
61-
62-
/**
63-
* @brief Creates and initializes a new acquire handle.
64-
* @return A new handle, or NULL on failure. Caller must free with
65-
* acquire_handle_free.
66-
*/
67-
extern LIBACQUIRE_EXPORT struct acquire_handle *acquire_handle_init(void);
68-
69-
/**
70-
* @brief Frees all resources associated with a handle.
71-
* @param handle The handle to free.
72-
*/
73-
extern LIBACQUIRE_EXPORT void
74-
acquire_handle_free(struct acquire_handle *handle);
75-
76-
/**
77-
* @brief Gets a human-readable error string for the last error on the handle.
78-
* @param handle The handle.
79-
* @return A constant string describing the last error.
80-
*/
81-
extern LIBACQUIRE_EXPORT const char *
82-
acquire_handle_get_error(struct acquire_handle *handle);
10+
#endif
8311

8412
/* --- Synchronous API --- */
85-
86-
/**
87-
* @brief Downloads a file synchronously (blocking).
88-
* @param handle A configured acquire handle.
89-
* @param url The URL to download.
90-
* @param dest_path The local path to save the file to.
91-
* @return 0 on success, non-zero on failure. Get details from the handle.
92-
*/
9313
extern LIBACQUIRE_EXPORT int
9414
acquire_download_sync(struct acquire_handle *handle, const char *url,
9515
const char *dest_path);
9616

9717
/* --- Asynchronous API --- */
98-
99-
/**
100-
* @brief Begins an asynchronous download (non-blocking).
101-
* @param handle A configured acquire handle.
102-
* @param url The URL to download.
103-
* @param dest_path The local path to save the file to.
104-
* @return 0 on success, non-zero on failure.
105-
*/
10618
extern LIBACQUIRE_EXPORT int
10719
acquire_download_async_start(struct acquire_handle *handle, const char *url,
10820
const char *dest_path);
10921

110-
/**
111-
* @brief Polls the status of an asynchronous operation, performing work.
112-
* @param handle The handle for the operation.
113-
* @return The current status of the operation (e.g., ACQUIRE_IN_PROGRESS).
114-
*/
11522
extern LIBACQUIRE_EXPORT enum acquire_status
11623
acquire_download_async_poll(struct acquire_handle *handle);
11724

118-
/**
119-
* @brief Requests cancellation of an asynchronous operation.
120-
* @param handle The handle for the operation.
121-
*/
12225
extern LIBACQUIRE_EXPORT void
12326
acquire_download_async_cancel(struct acquire_handle *handle);
12427

125-
/* --- Other Helpers --- */
126-
127-
extern LIBACQUIRE_EXPORT const char *get_download_dir(void);
128-
129-
extern LIBACQUIRE_EXPORT bool is_downloaded(const char *, enum Checksum,
130-
const char *, const char *);
131-
13228
#ifdef __cplusplus
13329
}
134-
#endif /* __cplusplus */
30+
#endif
13531

136-
#endif /* ! LIBACQUIRE_ACQUIRE_DOWNLOAD_H */
32+
#endif /* !LIBACQUIRE_ACQUIRE_DOWNLOAD_H */

‎acquire/acquire_extract.h‎

Lines changed: 79 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,111 @@
1-
/*
2-
* Prototype for extract API
3-
*
4-
*
5-
* */
6-
1+
/* acquire/acquire_extract.h */
72
#ifndef LIBACQUIRE_ACQUIRE_EXTRACT_H
83
#define LIBACQUIRE_ACQUIRE_EXTRACT_H
94

105
/**
116
* @file acquire_extract.h
12-
* @brief Extraction of compressed archives.
7+
* @brief Public API for synchronous and asynchronous archive extraction.
138
*
14-
* Provides functions to decompress and extract files from archives,
15-
* supporting common formats like ZIP, TAR, GZ, etc.
16-
* NOTE: Always `#include` this when adding new extraction
17-
* implementations, to ensure implementation matches the prototype.
18-
*
19-
* The extract API is for expanding the contents of archives
9+
* This module provides a handle-based API for both blocking and non-blocking
10+
* archive extraction. The archive format is detected automatically by the
11+
* backend (e.g., libarchive).
2012
*/
2113

14+
#include "acquire_handle.h"
15+
#include "libacquire_export.h"
16+
2217
#ifdef __cplusplus
2318
extern "C" {
2419
#endif /* __cplusplus */
2520

26-
#include "libacquire_export.h"
27-
28-
enum Archive {
29-
LIBACQUIRE_ZIP,
30-
LIBACQUIRE_INFER,
31-
LIBACQUIRE_UNSUPPORTED_ARCHIVE
32-
};
21+
/* --- Asynchronous API --- */
3322

3423
/**
35-
* @brief Extract an archive file into a specified directory.
24+
* @brief Begins an asynchronous extraction (non-blocking).
25+
*
26+
* This function initializes the extraction process. The actual work happens
27+
* during calls to `acquire_extract_async_poll`.
3628
*
37-
* Supports formats based on `enum Archive` discriminant.
29+
* @param handle An initialized acquire handle.
30+
* @param archive_path The path to the source archive file (e.g., .zip,
31+
* .tar.gz).
32+
* @param dest_path The directory to extract files into.
33+
* @return 0 on success, non-zero on failure.
34+
*/
35+
extern LIBACQUIRE_EXPORT int
36+
acquire_extract_async_start(struct acquire_handle *handle,
37+
const char *archive_path, const char *dest_path);
38+
39+
/**
40+
* @brief Polls the status of an asynchronous extraction, processing one entry.
3841
*
39-
* @param archive `enum Archive` discriminant type of archive.
40-
* @param archive_filepath Path to the archive file.
41-
* @param output_folder Directory path where contents should be extracted.
42+
* In a non-blocking application, this should be called repeatedly until it
43+
* no longer returns `ACQUIRE_IN_PROGRESS`. Each call processes one file or
44+
* directory entry from the archive.
4245
*
43-
* @return `EXIT_SUCCESS` if extraction succeeds;
44-
* `EXIT_FAILURE` or non-`EXIT_SUCCESS` otherwise.
46+
* @param handle The handle for the in-progress operation.
47+
* @return The current status of the operation.
4548
*/
46-
extern LIBACQUIRE_EXPORT int extract_archive(enum Archive archive,
47-
const char *archive_filepath,
48-
const char *output_folder);
49+
extern LIBACQUIRE_EXPORT enum acquire_status
50+
acquire_extract_async_poll(struct acquire_handle *handle);
4951

5052
/**
51-
* @brief Determine archive type based on extension
53+
* @brief Requests cancellation of an asynchronous extraction.
5254
*
53-
* TODO: magic bytes whence `LIBACQUIRE_INFER`
55+
* The cancellation will be processed on the next call to
56+
* `acquire_extract_async_poll`.
5457
*
55-
* @param extension Simple end of filepath, like ".zip" or ".tar.gz".
58+
* @param handle The handle for the operation to be cancelled.
59+
*/
60+
extern LIBACQUIRE_EXPORT void
61+
acquire_extract_async_cancel(struct acquire_handle *handle);
62+
63+
/* --- Synchronous API --- */
64+
65+
/**
66+
* @brief Extracts an archive synchronously (blocking).
67+
*
68+
* This is a helper function that wraps the asynchronous API, calling `poll`
69+
* in a loop until the operation is complete.
5670
*
57-
* @return `enum Archive` discriminant; including potential values of
58-
* `LIBACQUIRE_UNSUPPORTED_ARCHIVE` xor `LIBACQUIRE_INFER`.
71+
* @param handle An initialized acquire handle.
72+
* @param archive_path The path to the source archive file.
73+
* @param dest_path The directory to extract files into.
74+
* @return 0 on success, non-zero on failure. Details can be retrieved from the
75+
* handle.
5976
*/
60-
extern LIBACQUIRE_EXPORT enum Archive extension2archive(const char *extension);
77+
extern LIBACQUIRE_EXPORT int acquire_extract_sync(struct acquire_handle *handle,
78+
const char *archive_path,
79+
const char *dest_path);
6180

62-
#if defined(LIBACQUIRE_IMPLEMENTATION) && defined(LIBACQUIRE_EXTRACT_IMPL)
63-
#include <acquire_string_extras.h>
81+
/* --- Deprecated Symbols --- */
6482

65-
enum Archive extension2archive(const char *const extension) {
66-
if (strncasecmp(extension, ".zip", 6) == 0)
67-
return LIBACQUIRE_ZIP;
68-
else if (strlen(extension) == 0)
69-
return LIBACQUIRE_UNSUPPORTED_ARCHIVE;
70-
else
71-
return LIBACQUIRE_INFER;
72-
}
83+
/**
84+
* @deprecated This enum is no longer used in the public API and will be
85+
* removed in a future version. Archive format is now auto-detected.
86+
*/
87+
enum Archive {
88+
LIBACQUIRE_ZIP,
89+
LIBACQUIRE_INFER,
90+
LIBACQUIRE_UNSUPPORTED_ARCHIVE
91+
};
92+
93+
/**
94+
* @deprecated This function is no longer needed for the public API and will be
95+
* removed in a future version.
96+
*/
97+
extern LIBACQUIRE_EXPORT enum Archive extension2archive(const char *extension);
7398

74-
#endif /* defined(LIBACQUIRE_IMPLEMENTATION) && \
75-
defined(LIBACQUIRE_EXTRACT_IMPL) */
99+
/**
100+
* @deprecated This function is deprecated in favor of `acquire_extract_sync`.
101+
* It will be removed in a future version.
102+
*/
103+
extern LIBACQUIRE_EXPORT int extract_archive(enum Archive archive,
104+
const char *archive_filepath,
105+
const char *output_folder);
76106

77107
#ifdef __cplusplus
78108
}
79109
#endif /* __cplusplus */
80110

81-
#endif /* ! LIBACQUIRE_ACQUIRE_EXTRACT_H */
111+
#endif /* !LIBACQUIRE_ACQUIRE_EXTRACT_H */

0 commit comments

Comments
 (0)