Errors and utilities#

Event loop#

void lwhttp_service_events(void)#

Process lwIP-CE events and run client callbacks. Call this in the main loop instead of lwip_service_events().

It calls lwip_service_events() and then destroys sockets the clients have closed since the last call (sockets cannot be destroyed safely from inside their own callbacks). Keep calling it for a while after the last request or lwhttp_client_destroy() so retired sockets are freed.

Do not call it from inside an LWHTTP callback.

Errors#

enum lwhttp_error_t#

Result codes returned by LWHTTP functions and passed to lwhttp_client_handlers_t.on_complete.

lwhttp_error_string() gives a short English description of each.

enumerator LWHTTP_OK = 0#: Success.

enumerator LWHTTP_ERR_ARG#: Invalid argument: a required pointer was NULL, or a method, request-target, header name or header value is malformed, or the request supplied its own Content-Length or Transfer-Encoding header.

enumerator LWHTTP_ERR_MEM#: An allocation from the lwIP-CE heap failed.

enumerator LWHTTP_ERR_STATE#: The client is busy with another request, or is being destroyed.

enumerator LWHTTP_ERR_URL#: The URL could not be parsed, or a request URL has no scheme or no host. Also returned for a redirect target without a host.

enumerator LWHTTP_ERR_DNS#: lwIP-CE could not resolve the host name.

enumerator LWHTTP_ERR_CONNECT#: The connection could not be established (refused, unreachable, or the inactivity timeout expired while connecting).

enumerator LWHTTP_ERR_TLS#: The TLS handshake or TLS session failed: untrusted, expired or mismatched certificate, a server that does not offer TLS 1.3, or a certificate chain that uses a curve other than P-256.

enumerator LWHTTP_ERR_SEND#: lwIP-CE reported a write error other than “out of memory” or “closed”.

enumerator LWHTTP_ERR_CLOSED#: The connection closed (or timed out) before the response was complete. Also returned by lwhttp_parser_finish() for a truncated message.

enumerator LWHTTP_ERR_PROTOCOL#: The response violates HTTP/1.1 syntax or framing rules.

enumerator LWHTTP_ERR_VERSION#: The response is not HTTP/1.x.

enumerator LWHTTP_ERR_UNSUPPORTED#: The URL scheme is not http or https, or the response body uses a transfer coding other than chunked or a content coding other than identity.

enumerator LWHTTP_ERR_TOO_LARGE#: A length does not fit: Content-Length or a chunk size exceeds 32 bits, a chunk-size line does not fit the line buffer, or a resolved URL does not fit the output buffer.

enumerator LWHTTP_ERR_HEADERS_TOO_LARGE#: The response header section (or trailer section) does not fit the header buffer, or a single line is longer than the parser’s line buffer, or a lwhttp_headers_t store is full.

enumerator LWHTTP_ERR_REDIRECT#: A redirect Location could not be resolved against the current URL.

enumerator LWHTTP_ERR_ABORTED#: The request or parse was stopped: a callback asked to stop, lwhttp_client_cancel() was called, or a body reader returned an invalid length.

const char *lwhttp_error_string(lwhttp_error_t error)#

Short English description of a result code.

Parameters:

error – A result code.

Returns:

Static lower-case string such as "tls failure", or "unknown error" for an unknown value.

Version#

LWHTTP_VERSION_MAJOR#: Major version of the library this header belongs to.

LWHTTP_VERSION_MINOR#: Minor version of the library this header belongs to.

LWHTTP_VERSION_PATCH#: Patch version of the library this header belongs to.

LWHTTP_VERSION_STRING#

Version as a SemVer 2.0.0 string, "MAJOR.MINOR.PATCH" with an optional -prerelease suffix such as "1.0.0-rc1".

Also used in the default User-Agent ("LWHTTP/" LWHTTP_VERSION_STRING). Compare with lwhttp_version_string() to detect a header/library mismatch.

const char *lwhttp_version_string(void)#

Version of the compiled library.

Returns:: Static string equal to the library’s LWHTTP_VERSION_STRING.

Tokens#

bool lwhttp_is_token(const char *s)#

Check whether a string is an HTTP token (RFC 9110 tchar), as required for method and field names.

Parameters:

s – NUL-terminated string, may be NULL.

Returns:

true if s is non-empty and consists only of token characters; false for NULL or "".

bool lwhttp_header_has_token(const char *value, const char *token)#

Check whether a comma-separated header value contains a token, ignoring case.

Each list element is compared up to its first ; or whitespace, so parameters are ignored; quoted strings are skipped. For example "keep-alive, Upgrade" contains "upgrade", but "closed" does not contain "close".

Parameters:

value – Header value, may be NULL.
token – Token to look for, may be NULL.

Returns:

true if found; false if not or if either argument is NULL.