Skip to content

Commit 3b13d44

Browse files
SamuelMarksSamuelMarks
committed
[README.md] Document that there are now sync and async APIs ; add hyperlinks ; [*.h,*.c,CMakeLists.txt] Implement async and sync APIs for network libraries ; add tests for this
1 parent 3cb8a67 commit 3b13d44

22 files changed

+1091
-1612
lines changed

‎CMakeLists.txt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,8 @@ set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
120120
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${PROJECT_BINARY_DIR}")
121121

122122
option(BUILD_SHARED_LIB "Build shared library" ON)
123+
option(BUILD_CLI "Build CLI" ON)
124+
option(BUILD_EXAMPLES "Build examples" ON)
123125

124126
if (APPLE)
125127
set(CMAKE_INSTALL_RPATH "@executable_path/../lib")
@@ -135,7 +137,12 @@ get_arch()
135137
########################
136138

137139
add_subdirectory("${PROJECT_NAME}")
138-
add_subdirectory("${PROJECT_NAME}/cli")
140+
if (BUILD_CLI)
141+
add_subdirectory("${PROJECT_NAME}/cli")
142+
endif (BUILD_CLI)
143+
if (BUILD_EXAMPLES)
144+
add_subdirectory("${PROJECT_NAME}/examples")
145+
endif (BUILD_EXAMPLES)
139146

140147
######################
141148
# Test configuration #

‎README.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,16 @@ libacquire
55
[![CI for FreeBSD](https://api.cirrus-ci.com/github/offscale/libacquire.svg)](https://cirrus-ci.com/github/offscale/libacquire)
66
[![C89](https://img.shields.io/badge/C-89-blue)](https://en.wikipedia.org/wiki/C89_(C_version))
77

8-
The core for your package manager, minus the dependency graph components. Features: **download**, **verify**, and **extract**.
8+
The core for your package manager, minus the dependency graph components.
9+
Features both synchronous and asynchronous variants for: **download**; **verify**; and **extract**.
910

10-
By default—for HTTP, HTTPS, and FTP—this uses `libfetch` on FreeBSD; `wininet` on Windows; and `libcurl` everywhere else. Override with `-DLIBACQUIRE_USE_LIBCURL` or `-DLIBACQUIRE_USE_LIBFETCH`.
11+
By default—for HTTP, HTTPS, and FTP—this uses [`libfetch`](https://github.com/freebsd/freebsd-src/blob/main/lib/libfetch/fetch.c) on FreeBSD; [`wininet`](https://learn.microsoft.com/en-us/windows/win32/wininet/about-wininet) on Windows; and [`libcurl`](https://curl.se/libcurl/) everywhere else. Override with `-DLIBACQUIRE_USE_LIBCURL` or `-DLIBACQUIRE_USE_LIBFETCH`.
1112

12-
By default—for MD5, SHA256, SHA512—this uses `wincrypt` on Windows; and `OpenSSL` everywhere else. _Note that on macOS this uses the builtin `CommonCrypto/CommonDigest.h` header, and on OpenBSD it uses `LibreSSL`; however in both of these cases it's the OpenSSL API with different headers._ Override with `-DLIBACQUIRE_USE_OPENSSL`.
13+
By default—for MD5, SHA256, SHA512—this uses [`wincrypt`](https://learn.microsoft.com/en-us/windows/win32/api/wincrypt/) on Windows; and [`OpenSSL`](https://openssl-library.org) everywhere else. _Note that on macOS this uses the builtin [`CommonCrypto/CommonDigest.h`](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/Common%20Crypto.3cc.html) header, and on OpenBSD it uses [`LibreSSL`](https://libressl.org); however in both of these cases it's the OpenSSL API with different headers._ Override with `-DLIBACQUIRE_USE_OPENSSL`.
1314

14-
By default—for crc32c—this uses `rhash` if available (also giving access to: CRC32, MD4, MD5, SHA1, SHA256, SHA512, SHA3, AICH, ED2K, DC++ TTH, BitTorrent BTIH, Tiger, GOST R 34.11-94, GOST R 34.11-2012, RIPEMD-160, HAS-160, EDON-R, and Whirlpool); otherwise uses included crc32c implementation. Override with `-DUSE_CRC32C`.
15+
By default—for crc32c—this uses [`rhash`](https://github.com/rhash/RHash) if available (also giving access to: CRC32, MD4, MD5, SHA1, SHA256, SHA512, SHA3, AICH, ED2K, DC++ TTH, BitTorrent BTIH, Tiger, GOST R 34.11-94, GOST R 34.11-2012, RIPEMD-160, HAS-160, EDON-R, and Whirlpool); [wincrypt.h](https://learn.microsoft.com/en-us/windows/win32/api/wincrypt/) on Windows; otherwise uses included crc32c implementation. Override with `-DUSE_CRC32C`.
1516

16-
By default—for decompression—this uses `compressapi.h` on Windows; then, in order of precedence tries: libarchive; zlib; or downloads miniz.
17+
By default—for decompression—this uses [`compressapi.h`](https://learn.microsoft.com/en-us/windows/win32/api/compressapi) on Windows; then, in order of precedence tries: [libarchive](https://libarchive.org); [zlib](https://zlib.net); or downloads [miniz](https://github.com/richgel999/miniz).
1718

1819
Supports:
1920

‎acquire/CMakeLists.txt‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -281,9 +281,10 @@ else ()
281281
# Network common #
282282
##################
283283
elseif (src MATCHES "/gen_acquire_net_common.c$")
284+
set(gen_acquire_net_common "${src}")
284285
set_source_files_properties(
285286
${src} PROPERTIES
286-
COMPILE_DEFINITIONS "LIBACQUIRE_IMPLEMENTATION=1"
287+
COMPILE_DEFINITIONS "LIBACQUIRE_IMPLEMENTATION=1;LIBACQUIRE_ACQUIRE_NET_COMMON_IMPL=1"
287288
)
288289
##############
289290
# Networking #
@@ -360,6 +361,13 @@ else ()
360361
endif (WIN32)
361362
endforeach (src IN LISTS gen_source_files)
362363

364+
if (NOT ("LIBACQUIRE_DOWNLOAD_DIR_IMPL" IN_LIST impls))
365+
set_source_files_properties(
366+
"${gen_acquire_net_common}" PROPERTIES
367+
COMPILE_DEFINITIONS "LIBACQUIRE_IMPLEMENTATION=1;LIBACQUIRE_ACQUIRE_NET_COMMON_IMPL=1;LIBACQUIRE_DOWNLOAD_DIR_IMPL=1"
368+
)
369+
endif (NOT ("LIBACQUIRE_DOWNLOAD_DIR_IMPL" IN_LIST impls))
370+
363371
if (WIN32)
364372
set(gen_source_file "${CMAKE_BINARY_DIR}/gen/gen_acquire_main.c")
365373
file(WRITE "${gen_source_file}" "#include <minwindef.h>\n\n"

‎acquire/acquire_download.h‎

Lines changed: 109 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,134 @@
1+
/* acquire/acquire_download.h */
12
#ifndef LIBACQUIRE_ACQUIRE_DOWNLOAD_H
23
#define LIBACQUIRE_ACQUIRE_DOWNLOAD_H
34

45
/**
56
* @file acquire_download.h
6-
* @brief Functionality to download files from network locations.
7+
* @brief Public API for synchronous and asynchronous file downloads.
78
*
8-
* This module handles downloading files via protocols like HTTP(S),
9-
* providing progress monitoring and retry logic support.
10-
*
11-
* NOTE: Always `#include` this when adding new download implementations,
12-
* to ensure the implementation matches the prototype.
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`.
1312
*/
1413

15-
#include <stdlib.h>
16-
1714
#ifdef __cplusplus
1815
extern "C" {
19-
#elif defined(HAS_STDBOOL) && !defined(bool)
20-
#include <stdbool.h>
21-
#else
22-
#include "acquire_stdbool.h"
2316
#endif /* __cplusplus */
17+
18+
#include "acquire_checksums.h"
2419
#include "acquire_config.h"
2520
#include "acquire_fileutils.h"
2621
#include "acquire_url_utils.h"
27-
28-
#include "acquire_checksums.h"
2922
#include "libacquire_export.h"
3023

31-
#if (defined(LIBACQUIRE_USE_COMMON_CRYPTO) && LIBACQUIRE_USE_COMMON_CRYPTO) || \
32-
(defined(LIBACQUIRE_USE_OPENSSL) && LIBACQUIRE_USE_OPENSSL)
33-
#include "acquire_openssl.h"
34-
#elif defined(LIBACQUIRE_USE_WINCRYPT) && LIBACQUIRE_USE_WINCRYPT
35-
#include "acquire_wincrypt.h"
36-
#endif /* (defined(LIBACQUIRE_USE_COMMON_CRYPTO) && \
37-
LIBACQUIRE_USE_COMMON_CRYPTO) || (defined(LIBACQUIRE_USE_OPENSSL) && \
38-
LIBACQUIRE_USE_OPENSSL) */
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);
83+
84+
/* --- 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+
*/
93+
extern LIBACQUIRE_EXPORT int
94+
acquire_download_sync(struct acquire_handle *handle, const char *url,
95+
const char *dest_path);
96+
97+
/* --- 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+
*/
106+
extern LIBACQUIRE_EXPORT int
107+
acquire_download_async_start(struct acquire_handle *handle, const char *url,
108+
const char *dest_path);
109+
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+
*/
115+
extern LIBACQUIRE_EXPORT enum acquire_status
116+
acquire_download_async_poll(struct acquire_handle *handle);
117+
118+
/**
119+
* @brief Requests cancellation of an asynchronous operation.
120+
* @param handle The handle for the operation.
121+
*/
122+
extern LIBACQUIRE_EXPORT void
123+
acquire_download_async_cancel(struct acquire_handle *handle);
124+
125+
/* --- Other Helpers --- */
39126

40127
extern LIBACQUIRE_EXPORT const char *get_download_dir(void);
41128

42129
extern LIBACQUIRE_EXPORT bool is_downloaded(const char *, enum Checksum,
43130
const char *, const char *);
44131

45-
extern LIBACQUIRE_EXPORT int download(const char *, enum Checksum, const char *,
46-
const char *, bool, size_t, size_t);
47-
48-
extern LIBACQUIRE_EXPORT int download_many(const char *[], const char *[],
49-
enum Checksum[], const char *, bool,
50-
size_t, size_t);
51132
#ifdef __cplusplus
52133
}
53134
#endif /* __cplusplus */

0 commit comments

Comments
 (0)