Core Fetch API

Main functions for making HTTP requests. More...

Functions
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)

Detailed Description

Main functions for making HTTP requests.

Function Documentation

fetch()

fetch_response_t * fetch	(	const char *	url,
		fetch_init_t *	init )

Make a synchronous HTTP request (BLOCKING)

This function blocks the calling thread until the request completes or fails. The event loop runs internally during this call.

Parameters

url	The URL to fetch
init	Request configuration options (can be NULL for defaults, borrowed reference)

Returns

Response object (caller owns, must call fetch_response_free()), or NULL on memory allocation failure

Warning

This function BLOCKS the calling thread until completion

Note

Memory: Returns owned response object that must be freed

Threading: Must be called from the same thread as the event loop

// Simple blocking GET request
fetch_response_t *response = fetch("https://httpbin.org/get", NULL);
if (response) {
    if (fetch_response_ok(response)) {
        printf("Status: %d\n", fetch_response_status(response));
        const char *text = fetch_response_text(response);
        if (text) {
            printf("Body: %s\n", text);
        }
    } else {
        printf("Request failed: %d %s\n", fetch_response_status(response),
               fetch_response_status_text(response));
    }
    fetch_response_free(response); // Required: free the response
}

fetch_async()

fetch_promise_t * fetch_async	(	const char *	url,
		fetch_init_t *	init )

Make an asynchronous HTTP request (NON-BLOCKING)

Returns immediately with a promise. The request proceeds in the background and must be driven by calling fetch_event_loop_process() regularly.

Parameters

url	The URL to fetch
init	Request configuration options (can be NULL for defaults, borrowed reference)

Returns

Promise object (caller owns, must call fetch_promise_free()), or NULL on memory allocation failure

Note

This function returns immediately and does NOT block

Memory: Returns owned promise object that must be freed

Event Loop: Requires fetch_event_loop_process() to be called regularly for progress

// CORRECT: Non-blocking usage with event loop driving
if (!fetch_event_loop_start()) {
    fprintf(stderr, "Failed to start event loop\n");
    return -1;
}
 
fetch_promise_t *promise = fetch_async("https://httpbin.org/get", NULL);
if (!promise) {
    fetch_event_loop_stop();
    return -1;
}
 
// Drive the event loop until completion (non-blocking approach)
while (fetch_promise_pending(promise)) {
    int events = fetch_event_loop_process(100); // 100ms timeout
    if (events < 0) {
        printf("Event loop error\n");
        break;
    }
 
    // Do other work here while request is in progress
    printf("Request in progress...\n");
}
 
// Check result
if (fetch_promise_fulfilled(promise)) {
    fetch_response_t *response = fetch_promise_response(promise);
    if (response && fetch_response_ok(response)) {
        printf("Success: %s\n", fetch_response_text(response));
    }
    // Note: response is owned by promise, don't free it separately
} else if (fetch_promise_rejected(promise)) {
    printf("Failed: %s\n", fetch_promise_error_message(promise));
}
 
fetch_promise_free(promise); // Required: free the promise
fetch_event_loop_stop();