fetch.h File Reference

A lightweight asynchronous HTTP/1.1 client library for C with fetch-like API. More...

#include "cookie.h"
#include "version.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
#include <stdio.h>

Go to the source code of this file.

Data Structures
struct	fetch_abort_controller
	Abort controller for cancelling requests. More...
struct	fetch_headers
	HTTP headers container. More...
struct	fetch_headers_iterator_t
	Iterator for traversing headers. More...
struct	fetch_body_t
	Request or response body. More...
struct	fetch_init
	Request configuration options. More...
struct	fetch_response
	HTTP response object. More...
struct	fetch_promise
	Promise for asynchronous fetch operations. More...
struct	fetch_url_search_params
	URL search parameters container. More...
struct	fetch_url_search_params_iterator_t
	Iterator for URL search parameters. More...
struct	fetch_config
	Global configuration for the fetch library. More...

Macros
#define	FETCH_INVALID_FILE_HANDLE   NULL
	Invalid file handle value.
#define	FETCH_USER_AGENT   "libfetch/" FETCH_VERSION_STRING
	Default user agent string.
#define	FETCH_FLAG_GET(flags, bit)
	Get a flag value from a flags bitfield.
#define	FETCH_FLAG_SET(flags, bit)
	Set a flag in a flags bitfield.
#define	FETCH_FLAG_CLEAR(flags, bit)
	Clear a flag in a flags bitfield.
#define	FETCH_FLAG_TOGGLE(flags, bit)
	Toggle a flag in a flags bitfield.
#define	FETCH_GET(url)
	Make a simple GET request (BLOCKING)
#define	FETCH_ASYNC_GET(url)
	Make a simple async GET request (NON-BLOCKING)
#define	FETCH_IS_OK(response)
	Check if response is successful.
#define	FETCH_PROMISE_IS_DONE(promise)
	Check if promise is done (fulfilled or rejected)
#define	FETCH_TIMEOUT_INFINITE   0
#define	FETCH_TIMEOUT_DEFAULT   30000
#define	FETCH_TIMEOUT_SHORT   5000
#define	FETCH_TIMEOUT_LONG   60000

Typedefs
typedef FILE *	FETCH_FILE_HANDLE
	File handle type for streaming file content.
typedef fetch_stream_result_t(*	fetch_file_continue_cb) (void *userdata)
	Callback function for controlling file streaming continuation.
typedef struct fetch_abort_controller	fetch_abort_controller_t
	Abort controller for cancelling requests.
typedef struct fetch_headers	fetch_headers_t
	HTTP headers container.
typedef struct fetch_init	fetch_init_t
	Request configuration options.
typedef struct fetch_response	fetch_response_t
	HTTP response object.
typedef void(*	fetch_on_fulfilled_cb) (fetch_response_t *response, void *userdata)
	Callback for successful promise completion.
typedef void(*	fetch_on_rejected_cb) (fetch_error_t error, const char *message, void *userdata)
	Callback for promise rejection/failure.
typedef struct fetch_promise	fetch_promise_t
	Promise for asynchronous fetch operations.
typedef struct fetch_url_search_params	fetch_url_search_params_t
	URL search parameters container.
typedef struct fetch_event_loop	fetch_event_loop_t
	Opaque event loop structure.
typedef struct fetch_config	fetch_config_t
	Global configuration for the fetch library.

Enumerations
enum	fetch_stream_result_t { FETCH_STREAM_READ = 0 , FETCH_STREAM_DONE = 1 , FETCH_STREAM_SKIP = 2 }
	Return codes for file streaming continue callback. More...
enum	fetch_flag_bit_t {   FETCH_FLAG_KEEP_ALIVE_DEFAULT = 0 , FETCH_FLAG_ACCEPT_INVALID_CERTS = 1 , FETCH_FLAG_FOLLOW_REDIRECTS = 2 , FETCH_FLAG_ENABLE_COMPRESSION = 3 ,   FETCH_FLAG_ENABLE_COOKIES = 4 , FETCH_FLAG_DEBUG_LOGGING = 5 }
	Configuration flags for the fetch library. More...
enum	http_method_t {   HTTP_METHOD_GET , HTTP_METHOD_HEAD , HTTP_METHOD_POST , HTTP_METHOD_PUT ,   HTTP_METHOD_DELETE , HTTP_METHOD_CONNECT , HTTP_METHOD_OPTIONS , HTTP_METHOD_TRACE ,   HTTP_METHOD_PATCH }
	HTTP request methods. More...
enum	fetch_mode_t { FETCH_MODE_CORS , FETCH_MODE_NO_CORS , FETCH_MODE_SAME_ORIGIN , FETCH_MODE_NAVIGATE }
	Request modes for CORS handling. More...
enum	fetch_credentials_t { FETCH_CREDENTIALS_OMIT , FETCH_CREDENTIALS_SAME_ORIGIN , FETCH_CREDENTIALS_INCLUDE }
	Credential handling modes. More...
enum	fetch_cache_t {   FETCH_CACHE_DEFAULT , FETCH_CACHE_NO_STORE , FETCH_CACHE_RELOAD , FETCH_CACHE_NO_CACHE ,   FETCH_CACHE_FORCE_CACHE , FETCH_CACHE_ONLY_IF_CACHED }
	Cache control modes. More...
enum	fetch_redirect_t { FETCH_REDIRECT_FOLLOW , FETCH_REDIRECT_ERROR , FETCH_REDIRECT_MANUAL }
	Redirect handling modes. More...
enum	fetch_promise_state_t { FETCH_PROMISE_PENDING , FETCH_PROMISE_FULFILLED , FETCH_PROMISE_REJECTED }
	Promise states for asynchronous operations. More...
enum	fetch_error_t {   FETCH_ERROR_NONE = 0 , FETCH_ERROR_NETWORK , FETCH_ERROR_TIMEOUT , FETCH_ERROR_INVALID_URL ,   FETCH_ERROR_INVALID_METHOD , FETCH_ERROR_INVALID_HEADERS , FETCH_ERROR_MEMORY , FETCH_ERROR_ABORTED ,   FETCH_ERROR_TOO_MANY_REDIRECTS , FETCH_ERROR_CONNECTION_REFUSED , FETCH_ERROR_DNS_RESOLUTION , FETCH_ERROR_PROTOCOL_ERROR }
	Error codes for fetch operations. More...
enum	fetch_body_type_t {   FETCH_BODY_NONE , FETCH_BODY_TEXT , FETCH_BODY_BINARY , FETCH_BODY_FORM_DATA ,   FETCH_BODY_JSON , FETCH_BODY_FILE }
	Types of request/response bodies. More...

Functions
static const char *	fetch_version (void)
	Get version information at runtime.
static const char *	fetch_version_string (void)
	Get clean semantic version at runtime.
static int	fetch_version_major (void)
	Get major version number at runtime.
static int	fetch_version_minor (void)
	Get minor version number at runtime.
static int	fetch_version_patch (void)
	Get patch version number at runtime.
static int	fetch_version_compare (int major, int minor, int patch)
	Compare version against another version.
static bool	fetch_version_at_least (int major, int minor, int patch)
	Check if current version is at least the specified version.
fetch_response_t *	fetch (const char *url, fetch_init_t *init)
	Make a synchronous HTTP request (BLOCKING)
fetch_promise_t *	fetch_async (const char *url, fetch_init_t *init)
	Make an asynchronous HTTP request (NON-BLOCKING)
bool	fetch_promise_poll (fetch_promise_t *promise)
	Check if a promise has completed (NON-BLOCKING)
bool	fetch_promise_await (fetch_promise_t *promise, uint32_t timeout_ms)
	Wait for a promise to complete (BLOCKING)
bool	fetch_promise_cancel (fetch_promise_t *promise, const char *reason)
	Cancel a pending promise.
bool	fetch_promise_cancelled (const fetch_promise_t *promise)
	Check if a promise was cancelled.
fetch_response_t *	fetch_promise_response (const fetch_promise_t *promise)
	Get the response from a fulfilled promise.
fetch_promise_state_t	fetch_promise_state (const fetch_promise_t *promise)
	Get the current state of a promise.
fetch_error_t	fetch_promise_error (const fetch_promise_t *promise)
	Get the error code from a rejected promise.
const char *	fetch_promise_error_message (const fetch_promise_t *promise)
	Get the error message from a rejected promise.
bool	fetch_promise_pending (const fetch_promise_t *promise)
	Check if promise is still pending.
bool	fetch_promise_fulfilled (const fetch_promise_t *promise)
	Check if promise was fulfilled successfully.
bool	fetch_promise_rejected (const fetch_promise_t *promise)
	Check if promise was rejected.
bool	fetch_event_loop_start (void)
	Start the event loop.
void	fetch_event_loop_stop (void)
	Stop the event loop.
int	fetch_event_loop_process (uint32_t timeout_ms)
	Process events in the event loop (NON-BLOCKING with timeout)
bool	fetch_event_loop_is_running (void)
	Check if the event loop is running.
fetch_headers_t *	fetch_headers_new (void)
	Create a new headers container.
void	fetch_headers_free (fetch_headers_t *headers)
	Free a headers container and all its contents.
void	fetch_headers_append (fetch_headers_t *headers, const char *name, const char *value)
	Add a header (allows duplicates)
void	fetch_headers_set (fetch_headers_t *headers, const char *name, const char *value)
	Set a header (replaces existing)
void	fetch_headers_delete (fetch_headers_t *headers, const char *name)
	Remove all headers with the given name.
const char *	fetch_headers_get (const fetch_headers_t *headers, const char *name)
	Get the first header value with the given name.
bool	fetch_headers_has (const fetch_headers_t *headers, const char *name)
	Check if a header exists.
fetch_headers_iterator_t	fetch_headers_entries (const fetch_headers_t *headers)
	Create an iterator for headers.
bool	fetch_headers_next (fetch_headers_iterator_t *iter, const char **key, const char **value)
	Get the next header from an iterator.
fetch_body_t *	fetch_body_text (const char *text)
	Create a text body.
fetch_body_t *	fetch_body_json (const char *json)
	Create a JSON body.
fetch_body_t *	fetch_body_binary (const void *data, size_t size, const char *content_type)
	Create a binary body.
fetch_body_t *	fetch_body_form_data (const char *form_data)
	Create a form data body.
fetch_body_t *	fetch_body_url_search_params (fetch_url_search_params_t *params)
	Create a body from URL search parameters.
fetch_body_t *	fetch_body_file (FETCH_FILE_HANDLE file_handle, size_t size, const char *content_type, bool close_on_free, fetch_file_continue_cb continue_cb, void *userdata)
	Create a body from a file handle for streaming.
void	fetch_body_free (fetch_body_t *body)
	Free a body object.
fetch_url_search_params_t *	fetch_url_search_params_new (void)
	Create a new URL search parameters container.
void	fetch_url_search_params_free (fetch_url_search_params_t *params)
	Free a URL search parameters container.
void	fetch_url_search_params_append (fetch_url_search_params_t *params, const char *name, const char *value)
	Add a parameter (allows duplicates)
void	fetch_url_search_params_set (fetch_url_search_params_t *params, const char *name, const char *value)
	Set a parameter (replaces existing)
void	fetch_url_search_params_delete (fetch_url_search_params_t *params, const char *name)
	Remove all parameters with the given name.
const char *	fetch_url_search_params_get (const fetch_url_search_params_t *params, const char *name)
	Get the first parameter value with the given name.
bool	fetch_url_search_params_has (const fetch_url_search_params_t *params, const char *name)
	Check if a parameter exists.
char *	fetch_url_search_params_to_string (const fetch_url_search_params_t *params)
	Convert parameters to URL-encoded string.
fetch_url_search_params_iterator_t	fetch_url_search_params_entries (const fetch_url_search_params_t *params)
	Create an iterator for URL search parameters.
bool	fetch_url_search_params_next (fetch_url_search_params_iterator_t *iter, const char **key, const char **value)
	Get the next parameter from an iterator.
const char *	fetch_response_text (fetch_response_t *response)
	Get response body as text.
const void *	fetch_response_array_buffer (fetch_response_t *response, size_t *size)
	Get response body as binary data.
const char *	fetch_response_json (fetch_response_t *response)
	Get response body as JSON text.
bool	fetch_response_ok (const fetch_response_t *response)
	Check if response is successful (2xx status)
uint16_t	fetch_response_status (const fetch_response_t *response)
	Get HTTP status code.
const char *	fetch_response_status_text (const fetch_response_t *response)
	Get HTTP status text.
const char *	fetch_response_url (const fetch_response_t *response)
	Get final URL (after redirects)
fetch_headers_t *	fetch_response_headers (const fetch_response_t *response)
	Get response headers.
fetch_response_t *	fetch_response_clone (const fetch_response_t *response)
	Clone a response object.
void	fetch_response_free (fetch_response_t *response)
	Free a response object.
fetch_abort_controller_t *	fetch_abort_controller_new (void)
	Create a new abort controller.
void	fetch_abort_controller_abort (fetch_abort_controller_t *controller, const char *reason)
	Abort operations using this controller.
bool	fetch_abort_controller_aborted (const fetch_abort_controller_t *controller)
	Check if controller has been aborted.
void	fetch_abort_controller_free (fetch_abort_controller_t *controller)
	Free an abort controller.
fetch_init_t *	fetch_init_new (void)
	Create a new request configuration.
void	fetch_init_free (fetch_init_t *init)
	Free a request configuration.
fetch_init_t *	fetch_init_method (fetch_init_t *init, http_method_t method)
	Set HTTP method (fluent interface)
fetch_init_t *	fetch_init_headers (fetch_init_t *init, fetch_headers_t *headers)
	Set request headers (fluent interface)
fetch_init_t *	fetch_init_body (fetch_init_t *init, fetch_body_t *body)
	Set request body (fluent interface)
fetch_init_t *	fetch_init_timeout (fetch_init_t *init, uint32_t timeout_ms)
	Set request timeout (fluent interface)
fetch_init_t *	fetch_init_signal (fetch_init_t *init, fetch_abort_controller_t *signal)
	Set abort signal (fluent interface)
const char *	fetch_method_to_string (http_method_t method)
	Convert HTTP method enum to string.
http_method_t	fetch_method_from_string (const char *method_str)
	Convert string to HTTP method enum.
bool	fetch_is_valid_url (const char *url)
	Check if a URL is valid.
const char *	fetch_error_to_string (fetch_error_t error)
	Convert error code to human-readable string.
static bool	fetch_config_get_flag (uint32_t flags, fetch_flag_bit_t bit)
	Get a configuration flag value.
static void	fetch_config_set_flag (fetch_config_t *config, fetch_flag_bit_t flag, bool value)
	Set or clear a configuration flag.
static fetch_config_t	fetch_config_default (void)
	Get default configuration.
void	fetch_global_init (const fetch_config_t *config)
	Initialize the fetch library with configuration.
void	fetch_global_dispose (void)
	Clean up the fetch library.
cookie_jar_t *	fetch_get_cookie_jar (void)
	Get the current cookie jar.
size_t	fetch_cookie_jar_count (const char *domain_filter)
	Count cookies in the jar.
void	fetch_cookie_jar_clear (void)
	Clear all cookies from the jar.
void	fetch_disable_cookies (void)
	Disable cookie handling.
cookie_jar_t *	fetch_create_cookie_jar (const char *persistent_file)
	Create a new cookie jar.
void	fetch_cookie_jar_free (cookie_jar_t *jar)
	Free a cookie jar.
bool	fetch_save_cookies (const char *filename, cookie_jar_t *jar)
	Save cookies to a file.
bool	fetch_load_cookies (const char *filename, cookie_jar_t *jar)
	Load cookies from a file.
void	fetch_cookie_jar_print (cookie_jar_t *jar, const char *domain_filter)
	Print cookies to stdout (for debugging)
void	fetch_promise_free (fetch_promise_t *promise)
	Free a promise object.

Detailed Description

A lightweight asynchronous HTTP/1.1 client library for C with fetch-like API.

This library provides a JavaScript fetch-like API for making HTTP requests in C. It supports both synchronous and asynchronous operations, connection pooling, cookie management, redirects, file streaming, and various HTTP methods.

Threading Model

This library is NOT thread-safe. All operations must be performed from a single thread. The event loop and all fetch operations should be called from the same thread.

Memory Management

The library uses clear ownership semantics:

• Objects returned by "new" functions must be freed by the caller
• Objects passed to functions are either borrowed (temporary) or owned (transferred)
• Check function documentation for specific ownership semantics

File Streaming

The library supports efficient file streaming for uploads without loading entire files into memory:

• Regular files: Known size, standard Content-Length header
• Streaming files: Unknown size, uses chunked transfer encoding
• Live streams: Continuous data with user-controlled completion

Macro Definition Documentation

FETCH_USER_AGENT

#define FETCH_USER_AGENT   "libfetch/" FETCH_VERSION_STRING

Default user agent string.

This macro generates the default user agent string used by the library. Format: "libfetch/VERSION"