Complete reference for the weblite public API. All functions and types are declared in weblite.h and weblite_types.h.
weblite_config_t weblite_config_defaults(void);Returns a weblite_config_t with sensible defaults:
| Field | Default |
|---|---|
default_transport |
WEBLITE_TRANSPORT_AUTO |
default_timeout_ms |
30000 |
default_max_redirects |
10 |
tls_verify |
1 (enabled) |
ca_path |
NULL (auto-detect) |
thread_pool_size |
4 |
allocator |
NULL (use stdlib) |
weblite_config_t config = weblite_config_defaults();
config.tls_verify = 0; /* disable cert verification */
config.default_timeout_ms = 5000; /* 5 second timeout */weblite_error_t weblite_init(const weblite_config_t *config);Initialize the library. Must be called before any other API function. Safe to call multiple times (subsequent calls are no-ops). Pass NULL to use defaults.
Returns WEBLITE_OK on success.
weblite_config_t config = weblite_config_defaults();
weblite_error_t err = weblite_init(&config);
if (err != WEBLITE_OK) {
fprintf(stderr, "Init failed: %s\n", weblite_error_string(err));
}void weblite_cleanup(void);Release all resources held by the library. Call once when done. After cleanup, weblite_init can be called again.
weblite_cleanup();All synchronous functions block until the response is received or an error occurs. On success they return WEBLITE_OK and set *resp to a heap-allocated response that the caller must free with weblite_response_free.
weblite_error_t weblite_request(const weblite_request_t *req,
weblite_response_t **resp);Send a fully configured request. Use this when you need control over method, transport mode, timeout, or redirect limits.
weblite_request_t req = {0};
req.url = "https://api.example.com/data";
req.method = WEBLITE_METHOD_POST;
req.transport_mode = WEBLITE_TRANSPORT_HTTP_ONLY;
req.timeout_ms = 5000;
req.max_redirects = 3;
weblite_header_t headers[] = {
{ "Content-Type", "application/json" },
{ "Authorization", "Bearer token123" },
};
req.headers = headers;
req.header_count = 2;
const char *body = "{\"key\": \"value\"}";
req.body = body;
req.body_len = strlen(body);
weblite_response_t *resp = NULL;
weblite_error_t err = weblite_request(&req, &resp);
if (err == WEBLITE_OK) {
printf("Status: %d\n", resp->status_code);
printf("Transport: %s\n",
resp->transport_used == WEBLITE_USED_HTTP ? "HTTP" : "WebSocket");
}
weblite_response_free(resp);weblite_error_t weblite_get(const char *url,
const weblite_header_t *headers, size_t header_count,
weblite_response_t **resp);Send a GET request.
weblite_response_t *resp = NULL;
weblite_error_t err = weblite_get("https://httpbin.org/get", NULL, 0, &resp);
if (err == WEBLITE_OK) {
printf("Status: %d\n", resp->status_code);
printf("Body: %.*s\n", (int)resp->body_len, (char *)resp->body);
}
weblite_response_free(resp);With custom headers:
weblite_header_t headers[] = {
{ "Accept", "application/json" },
{ "Authorization", "Bearer mytoken" },
};
weblite_response_t *resp = NULL;
weblite_get("https://api.example.com/user",
headers, 2, &resp);weblite_error_t weblite_post(const char *url,
const weblite_header_t *headers, size_t header_count,
const void *body, size_t body_len,
weblite_response_t **resp);Send a POST request with a body.
const char *json = "{\"name\": \"weblite\", \"version\": \"0.1.0\"}";
weblite_header_t headers[] = {
{ "Content-Type", "application/json" },
};
weblite_response_t *resp = NULL;
weblite_post("https://httpbin.org/post",
headers, 1,
json, strlen(json),
&resp);
if (resp && resp->status_code == 200)
printf("Posted successfully\n");
weblite_response_free(resp);weblite_error_t weblite_put(const char *url,
const weblite_header_t *headers, size_t header_count,
const void *body, size_t body_len,
weblite_response_t **resp);Send a PUT request with a body.
const char *data = "{\"status\": \"active\"}";
weblite_header_t headers[] = {
{ "Content-Type", "application/json" },
};
weblite_response_t *resp = NULL;
weblite_put("https://api.example.com/user/42",
headers, 1,
data, strlen(data),
&resp);
weblite_response_free(resp);weblite_error_t weblite_delete(const char *url,
const weblite_header_t *headers, size_t header_count,
weblite_response_t **resp);Send a DELETE request.
weblite_response_t *resp = NULL;
weblite_delete("https://api.example.com/user/42", NULL, 0, &resp);
if (resp && resp->status_code == 204)
printf("Deleted\n");
weblite_response_free(resp);Async functions submit work to a thread pool and return immediately. The callback fires on a background thread when the response arrives. Use weblite_async_wait or weblite_async_poll to synchronize.
weblite_async_handle_t *weblite_request_async(const weblite_request_t *req,
weblite_callback_t callback,
void *user_data);Submit a fully configured async request. Returns a handle, or NULL on failure. The callback receives the response and the user_data pointer.
void on_response(const weblite_response_t *resp, void *ctx) {
int *request_id = ctx;
printf("Request %d completed: status %d\n", *request_id, resp->status_code);
}
weblite_request_t req = {0};
req.url = "https://api.example.com/data";
req.method = WEBLITE_METHOD_GET;
int id = 1;
weblite_async_handle_t *h = weblite_request_async(&req, on_response, &id);weblite_async_handle_t *weblite_get_async(const char *url,
const weblite_header_t *headers,
size_t header_count,
weblite_callback_t callback,
void *user_data);Submit an async GET request.
void on_done(const weblite_response_t *resp, void *ctx) {
printf("Got %d bytes\n", (int)resp->body_len);
}
weblite_get_async("https://httpbin.org/get", NULL, 0, on_done, NULL);weblite_async_handle_t *weblite_post_async(const char *url,
const weblite_header_t *headers,
size_t header_count,
const void *body, size_t body_len,
weblite_callback_t callback,
void *user_data);Submit an async POST request.
const char *payload = "{\"event\": \"click\"}";
weblite_header_t hdrs[] = {{ "Content-Type", "application/json" }};
weblite_async_handle_t *h = weblite_post_async(
"https://api.example.com/events",
hdrs, 1,
payload, strlen(payload),
on_done, NULL);
weblite_async_wait(h, 10000);weblite_async_handle_t *weblite_put_async(const char *url,
const weblite_header_t *headers,
size_t header_count,
const void *body, size_t body_len,
weblite_callback_t callback,
void *user_data);Submit an async PUT request. Same interface as weblite_post_async.
weblite_async_handle_t *weblite_delete_async(const char *url,
const weblite_header_t *headers,
size_t header_count,
weblite_callback_t callback,
void *user_data);Submit an async DELETE request.
weblite_error_t weblite_async_wait(weblite_async_handle_t *handle,
uint32_t timeout_ms);Block until the async request completes or the timeout expires. Returns WEBLITE_OK on completion, WEBLITE_ERR_TIMEOUT if the timeout is reached.
weblite_async_handle_t *h = weblite_get_async(url, NULL, 0, callback, NULL);
weblite_error_t err = weblite_async_wait(h, 5000);
if (err == WEBLITE_ERR_TIMEOUT) {
printf("Timed out, cancelling\n");
weblite_async_cancel(h);
}weblite_error_t weblite_async_cancel(weblite_async_handle_t *handle);Cancel a pending async request. The callback will not fire after cancellation.
int weblite_async_poll(void);Process completed async callbacks on the calling thread. Returns the number of callbacks dispatched. Use this in event-loop-based programs instead of weblite_async_wait.
/* Game loop / event loop pattern */
while (running) {
weblite_async_poll();
/* ... other work ... */
}void weblite_response_free(weblite_response_t *resp);Free a response returned by any request function. Safe to call with NULL.
weblite_response_t *resp = NULL;
weblite_get(url, NULL, 0, &resp);
/* use resp ... */
weblite_response_free(resp);const char *weblite_error_string(weblite_error_t err);Return a human-readable string for an error code.
weblite_error_t err = weblite_get(url, NULL, 0, &resp);
if (err != WEBLITE_OK)
fprintf(stderr, "Error: %s\n", weblite_error_string(err));const char *weblite_version(void);Return the library version string (e.g., "0.1.0").
printf("weblite %s\n", weblite_version());weblite_error_t weblite_set_platform_hooks(const weblite_platform_hooks_t *hooks);Override socket and random-byte operations for embedded targets that lack a standard POSIX or Win32 socket API. Call before weblite_init.
static int my_socket_open(const char *host, uint16_t port) {
/* Open TCP connection on your hardware */
return fd;
}
static void my_socket_close(int fd) { /* ... */ }
static int my_socket_send(int fd, const void *data, size_t len) { /* ... */ }
static int my_socket_recv(int fd, void *buf, size_t len) { /* ... */ }
static int my_random_bytes(void *buf, size_t len) { /* ... */ }
weblite_platform_hooks_t hooks = {
.socket_open = my_socket_open,
.socket_close = my_socket_close,
.socket_send = my_socket_send,
.socket_recv = my_socket_recv,
.random_bytes = my_random_bytes,
};
weblite_set_platform_hooks(&hooks);
weblite_init(NULL);Global configuration passed to weblite_init.
typedef struct {
weblite_transport_mode_t default_transport; /* AUTO, HTTP_ONLY, or WS_ONLY */
uint32_t default_timeout_ms; /* Request timeout (ms) */
uint32_t default_max_redirects;/* Max HTTP redirects to follow */
int tls_verify; /* 1 = verify server certs */
const char *ca_path; /* Custom CA bundle path, or NULL */
int thread_pool_size; /* Worker threads for async */
weblite_allocator_t *allocator; /* Custom allocator, or NULL */
} weblite_config_t;Full request configuration for weblite_request and weblite_request_async.
typedef struct {
const char *url;
weblite_method_t method; /* GET, POST, PUT, DELETE, ... */
const weblite_header_t *headers;
size_t header_count;
const void *body;
size_t body_len;
weblite_transport_mode_t transport_mode; /* Override default transport */
uint32_t timeout_ms; /* 0 = use default */
uint32_t max_redirects; /* 0 = use default */
void *user_data;
} weblite_request_t;Response returned by all request functions.
typedef struct {
int status_code; /* HTTP status (200, 404, ...) */
weblite_header_owned_t *headers; /* Response headers */
size_t header_count;
void *body; /* Response body (binary safe) */
size_t body_len;
weblite_transport_used_t transport_used; /* WEBLITE_USED_HTTP or _WS */
weblite_error_t error; /* WEBLITE_OK if successful */
char error_msg[256]; /* Human-readable error detail */
} weblite_response_t;Key-value pair for request headers. Strings are borrowed (not copied).
typedef struct {
const char *name;
const char *value;
} weblite_header_t;Callback type for async requests.
typedef void (*weblite_callback_t)(const weblite_response_t *resp, void *user_data);typedef enum {
WEBLITE_METHOD_GET,
WEBLITE_METHOD_POST,
WEBLITE_METHOD_PUT,
WEBLITE_METHOD_DELETE,
WEBLITE_METHOD_PATCH,
WEBLITE_METHOD_HEAD,
WEBLITE_METHOD_OPTIONS
} weblite_method_t;typedef enum {
WEBLITE_TRANSPORT_AUTO, /* Try HTTP, fall back to WebSocket */
WEBLITE_TRANSPORT_HTTP_ONLY, /* HTTP only */
WEBLITE_TRANSPORT_WS_ONLY /* WebSocket only */
} weblite_transport_mode_t;Custom memory allocator. Set in weblite_config_t to replace stdlib.
typedef struct {
void *(*malloc)(size_t size);
void *(*realloc)(void *ptr, size_t size);
void (*free)(void *ptr);
} weblite_allocator_t;Platform abstraction for embedded targets.
typedef struct {
int (*socket_open)(const char *host, uint16_t port);
void (*socket_close)(int fd);
int (*socket_send)(int fd, const void *data, size_t len);
int (*socket_recv)(int fd, void *buf, size_t len);
int (*random_bytes)(void *buf, size_t len);
void *user_data;
} weblite_platform_hooks_t;| Code | Description |
|---|---|
WEBLITE_OK |
Success |
WEBLITE_ERR_INVALID_ARG |
Invalid argument passed to function |
WEBLITE_ERR_ALLOC |
Memory allocation failed |
WEBLITE_ERR_DNS |
DNS resolution failed |
WEBLITE_ERR_CONNECT |
TCP connection failed |
WEBLITE_ERR_TLS |
TLS handshake or I/O error |
WEBLITE_ERR_TIMEOUT |
Operation timed out |
WEBLITE_ERR_HTTP_PARSE |
Malformed HTTP response |
WEBLITE_ERR_WS_HANDSHAKE |
WebSocket handshake failed |
WEBLITE_ERR_WS_PROTOCOL |
WebSocket protocol violation |
WEBLITE_ERR_TRANSPORT |
Transport-level I/O error |
WEBLITE_ERR_CANCELLED |
Async request was cancelled |
WEBLITE_ERR_NOT_INITIALIZED |
weblite_init was not called |
WEBLITE_ERR_IO |
General I/O error |
WEBLITE_ERR_REDIRECT_LIMIT |
Too many HTTP redirects |
WEBLITE_ERR_UNSUPPORTED |
Unsupported feature or configuration |