Body Management

Functions for creating request/response bodies. More...

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

Detailed Description

Functions for creating request/response bodies.

Function Documentation

fetch_body_binary()

fetch_body_t * fetch_body_binary	(	const void *	data,
		size_t	size,
		const char *	content_type )

Create a binary body.

Parameters

data	Binary data (will be copied)
size	Size of data in bytes
content_type	MIME type (optional, defaults to "application/octet-stream")

Returns

Body object (caller owns, must call fetch_body_free()), or NULL on failure

Note

Memory: Makes a copy of the binary data, returns owned object

uint8_t image_data[] = {0x89, 0x50, 0x4E, 0x47, ...};
fetch_body_t *body = fetch_body_binary(image_data, sizeof(image_data),
"image/png"); if (body) {
    // Use with request...
    fetch_body_free(body); // Required
}

fetch_body_file()

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.

Creates a request body that streams data directly from a file handle, avoiding the need to load large files into memory. Supports three modes:

1. Regular files (continue_cb = NULL, size > 0):
   • Uses Content-Length header with known file size
   • Most efficient for static files
2. Unknown-size files (continue_cb = NULL, size = 0):
   • Uses chunked transfer encoding
   • For files where size cannot be determined
3. Live streaming (continue_cb != NULL):
   • Uses chunked transfer encoding with user-controlled completion
   • For continuously written files, logs, or live data streams
   • The callback determines when more data is available

Parameters

file_handle	File handle to stream from (platform-specific)
size	File size in bytes (0 if unknown, enables chunked encoding)
content_type	MIME type (optional, defaults to "application/octet-stream")
close_on_free	Whether to close the file handle when body is freed
continue_cb	Callback for streaming control (NULL for regular files)
userdata	User data passed to continue_cb

Returns

Body object (caller owns, must call fetch_body_free()), or NULL on failure

Note

Memory: Body object manages file handle according to close_on_free flag

File Handle: If close_on_free is false, caller must keep handle open until request completes

Threading: File operations will be performed on the same thread as the event loop

Streaming: If continue_cb is non-NULL, uses chunked transfer encoding for unknown-length streams

// Example 1: Regular file with known size (most efficient)
FILE *file = fopen("upload.dat", "rb");
if (file) {
    fseek(file, 0, SEEK_END);
    size_t size = ftell(file);
    fseek(file, 0, SEEK_SET);
 
    // Library will close the file automatically
    fetch_body_t *body = fetch_body_file(file, size,
"application/octet-stream", true, NULL, NULL);
 
    // Use body with request...
    fetch_body_free(body); // This will close the file handle
}
 
// Example 2: Streaming a log file that's being written to
typedef struct {
    bool should_stop;
    FILE *log_file;
} LogStreamContext;
 
fetch_stream_result_t continue_log_stream(void *userdata) {
    LogStreamContext *ctx = (LogStreamContext*)userdata;
 
    if (ctx->should_stop) {
        return FETCH_STREAM_DONE;
    }
 
    // Check if new data has been written
    long current_pos = ftell(ctx->log_file);
    fseek(ctx->log_file, 0, SEEK_END);
    long end_pos = ftell(ctx->log_file);
    fseek(ctx->log_file, current_pos, SEEK_SET);
 
    if (end_pos > current_pos) {
        return FETCH_STREAM_READ;  // More data available
    }
 
    return FETCH_STREAM_SKIP;  // No new data yet, but keep trying
}
 
FILE *log_file = fopen("live.log", "rb");
LogStreamContext ctx = { .should_stop = false, .log_file = log_file };
 
// Stream with unknown size and continuous monitoring
fetch_body_t *body = fetch_body_file(log_file, 0, "text/plain", false,
                                     continue_log_stream, &ctx);
 
// Start upload...
// Later, to stop streaming: ctx.should_stop = true;
 
fetch_body_free(body);
fclose(log_file); // Manual cleanup since close_on_free was false
 
// Example 3: Windows file with automatic cleanup
#ifdef _WIN32
HANDLE file = CreateFile(L"upload.dat", GENERIC_READ, FILE_SHARE_READ,
                        NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL);
if (file != INVALID_HANDLE_VALUE) {
    LARGE_INTEGER size;
    GetFileSizeEx(file, &size);
 
    // Body will close the file handle automatically
    fetch_body_t *body = fetch_body_file(file, size.QuadPart,
                                         "application/octet-stream", true,
                                         NULL, NULL);
 
    // Use body with request...
 
    fetch_body_free(body); // This will close the file handle
}
#endif

fetch_body_form_data()

fetch_body_t * fetch_body_form_data

(

const char *

form_data

)

Create a form data body.

Parameters

form_data

URL-encoded form data (will be copied)

Returns

Body object (caller owns, must call fetch_body_free()), or NULL on failure

Note

Memory: Makes a copy of the form data, returns owned object

fetch_body_t *body = fetch_body_form_data("name=John&age=30&city=New+York");
if (body) {
    // Use with request...
    fetch_body_free(body); // Required
}

fetch_body_free()

void fetch_body_free

(

fetch_body_t *

body

)

Free a body object.

Parameters

body	Body to free (can be NULL)

Note

Memory: Frees the body and all contained data

File Handles: If body is FETCH_BODY_FILE and close_on_free is true, closes the file handle automatically

fetch_body_json()

fetch_body_t * fetch_body_json

(

const char *

json

)

Create a JSON body.

Parameters

json	JSON content (will be copied)

Returns

Body object (caller owns, must call fetch_body_free()), or NULL on failure

Note

Memory: Makes a copy of the JSON string, returns owned object

fetch_body_t *body = fetch_body_json("{\"name\": \"John\", \"age\": 30}");
if (body) {
    // Use with request...
    fetch_body_free(body); // Required
}

fetch_body_text()

fetch_body_t * fetch_body_text

(

const char *

text

)

Create a text body.

Parameters

text	Text content (will be copied)

Returns

Body object (caller owns, must call fetch_body_free()), or NULL on failure

Note

Memory: Makes a copy of the text, returns owned object

fetch_body_t *body = fetch_body_text("Hello, World!");
if (!body) {
    fprintf(stderr, "Failed to create body\n");
    return -1;
}
 
// Use with request...
fetch_body_free(body); // Required: free the body

fetch_body_url_search_params()

fetch_body_t * fetch_body_url_search_params

(

fetch_url_search_params_t *

params

)

Create a body from URL search parameters.

Parameters

params

URL search parameters object

Returns

Body object formatted as form data (caller owns, must call fetch_body_free()), or NULL on failure

Note

Memory: Creates new body object, original params unchanged

fetch_url_search_params_t *params = fetch_url_search_params_new();
fetch_url_search_params_append(params, "name", "John");
fetch_url_search_params_append(params, "age", "30");
 
fetch_body_t *body = fetch_body_url_search_params(params);
 
// Both body and params need to be freed
fetch_body_free(body); // Required
fetch_url_search_params_free(params); // Required