HTTP headers: create

Macros
#define	LWSAHH_CODE_MASK   ((1 << 16) - 1)
#define	LWSAHH_FLAG_NO_SERVER_NAME   (1 << 30)
#define	LWS_ILLEGAL_HTTP_CONTENT_LEN   ((lws_filepos_t)-1ll)

Enumerations
enum	{   LWSHUMETH_GET , LWSHUMETH_POST , LWSHUMETH_OPTIONS , LWSHUMETH_PUT ,   LWSHUMETH_PATCH , LWSHUMETH_DELETE , LWSHUMETH_CONNECT , LWSHUMETH_HEAD ,   LWSHUMETH_COLON_PATH }

Functions
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_add_http_header_status (struct lws *wsi, unsigned int code, unsigned char **p, unsigned char *end)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_add_http_header_by_name (struct lws *wsi, const unsigned char *name, const unsigned char *value, int length, unsigned char **p, unsigned char *end)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_add_http_header_by_token (struct lws *wsi, enum lws_token_indexes token, const unsigned char *value, int length, unsigned char **p, unsigned char *end)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_add_http_header_content_length (struct lws *wsi, lws_filepos_t content_length, unsigned char **p, unsigned char *end)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_finalize_http_header (struct lws *wsi, unsigned char **p, unsigned char *end)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_finalize_write_http_header (struct lws *wsi, unsigned char *start, unsigned char **p, unsigned char *end)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_add_http_common_headers (struct lws *wsi, unsigned int code, const char *content_type, lws_filepos_t content_len, unsigned char **p, unsigned char *end)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_http_get_uri_and_method (struct lws *wsi, char **puri_ptr, int *puri_len)

Detailed Description

HTTP headers: Create

These apis allow you to create HTTP response headers in a way compatible with both HTTP/1.x and HTTP/2.

They each append to a buffer taking care about the buffer end, which is passed in as a pointer. When data is written to the buffer, the current position p is updated accordingly.

All of these apis are LWS_WARN_UNUSED_RESULT as they can run out of space and fail with nonzero return.

Macro Definition Documentation

LWSAHH_CODE_MASK

#define LWSAHH_CODE_MASK   ((1 << 16) - 1)

#include <lws-http.h>

Definition at line 756 of file lws-http.h.

LWSAHH_FLAG_NO_SERVER_NAME

#define LWSAHH_FLAG_NO_SERVER_NAME   (1 << 30)

#include <lws-http.h>

Definition at line 757 of file lws-http.h.

LWS_ILLEGAL_HTTP_CONTENT_LEN

#define LWS_ILLEGAL_HTTP_CONTENT_LEN   ((lws_filepos_t)-1ll)

#include <lws-http.h>

Definition at line 875 of file lws-http.h.

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <lws-http.h>

Enumerator
LWSHUMETH_GET
LWSHUMETH_POST
LWSHUMETH_OPTIONS
LWSHUMETH_PUT
LWSHUMETH_PATCH
LWSHUMETH_DELETE
LWSHUMETH_CONNECT
LWSHUMETH_HEAD
LWSHUMETH_COLON_PATH

Definition at line 908 of file lws-http.h.

     {
        LWSHUMETH_GET,
        LWSHUMETH_POST,
        LWSHUMETH_OPTIONS,
        LWSHUMETH_PUT,
        LWSHUMETH_PATCH,
        LWSHUMETH_DELETE,
        LWSHUMETH_CONNECT,
        LWSHUMETH_HEAD,
        LWSHUMETH_COLON_PATH,
};

Function Documentation

lws_add_http_header_status()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_add_http_header_status	(	struct lws *	wsi,
		unsigned int	code,
		unsigned char **	p,
		unsigned char *	end )

#include <lws-http.h>

lws_add_http_header_status() - add the HTTP response status code

Parameters

wsi	the connection to check
code	an HTTP code like 200, 404 etc (see enum http_status)
p	pointer to current position in buffer pointer
end	pointer to end of buffer

Adds the initial response code, so should be called first.

Code may additionally take OR'd flags:

LWSAHH_FLAG_NO_SERVER_NAME: don't apply server name header this time

References LWS_EXTERN, LWS_VISIBLE, and LWS_WARN_UNUSED_RESULT.

lws_add_http_header_by_name()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_add_http_header_by_name	(	struct lws *	wsi,
		const unsigned char *	name,
		const unsigned char *	value,
		int	length,
		unsigned char **	p,
		unsigned char *	end )

#include <lws-http.h>

lws_add_http_header_by_name() - append named header and value

Parameters

wsi	the connection to check
name	the hdr name, like "my-header:"
value	the value after the = for this header
length	the length of the value
p	pointer to current position in buffer pointer
end	pointer to end of buffer

Appends name: value to the headers

The add fails (returns 1, nothing emitted) if the name or the value contains a C0 control byte other than TAB, or DEL: header values are RFC 9110 field-content (VCHAR / SP / HTAB / obs-text), and emitting such bytes is at best invalid and at worst response splitting over h1. This also fences misconfiguration (CR/LF in vhost header strings).

A NULL name composes the value with no field name (used for the h1 status line); h2/h3 have no such representation (the status is the :status pseudo-header from the _status helpers), so over h2/h3 a NULL name fails the add (returns 1, nothing emitted).

References LWS_EXTERN, LWS_VISIBLE, and LWS_WARN_UNUSED_RESULT.

lws_add_http_header_by_token()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_add_http_header_by_token	(	struct lws *	wsi,
		enum lws_token_indexes	token,
		const unsigned char *	value,
		int	length,
		unsigned char **	p,
		unsigned char *	end )

#include <lws-http.h>

lws_add_http_header_by_token() - append given header and value

Parameters

wsi	the connection to check
token	the token index for the hdr
value	the value after the = for this header
length	the length of the value
p	pointer to current position in buffer pointer
end	pointer to end of buffer

Appends name=value to the headers, but is able to take advantage of better HTTP/2 coding mechanisms where possible.

As with lws_add_http_header_by_name(), the add fails (returns 1, nothing emitted) if the value contains a C0 control byte other than TAB, or DEL.

References LWS_EXTERN, LWS_VISIBLE, and LWS_WARN_UNUSED_RESULT.

lws_add_http_header_content_length()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_add_http_header_content_length	(	struct lws *	wsi,
		lws_filepos_t	content_length,
		unsigned char **	p,
		unsigned char *	end )

#include <lws-http.h>

lws_add_http_header_content_length() - append content-length helper

Parameters

wsi	the connection to check
content_length	the content length to use
p	pointer to current position in buffer pointer
end	pointer to end of buffer

Appends content-length: content_length to the headers

References LWS_EXTERN, LWS_VISIBLE, and LWS_WARN_UNUSED_RESULT.

lws_finalize_http_header()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_finalize_http_header	(	struct lws *	wsi,
		unsigned char **	p,
		unsigned char *	end )

#include <lws-http.h>

lws_finalize_http_header() - terminate header block

Parameters

wsi	the connection to check
p	pointer to current position in buffer pointer
end	pointer to end of buffer

Indicates no more headers will be added

References LWS_EXTERN, LWS_VISIBLE, and LWS_WARN_UNUSED_RESULT.

lws_finalize_write_http_header()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_finalize_write_http_header	(	struct lws *	wsi,
		unsigned char *	start,
		unsigned char **	p,
		unsigned char *	end )

#include <lws-http.h>

lws_finalize_write_http_header() - Helper finalizing and writing http headers

Parameters

wsi	the connection to check
start	pointer to the start of headers in the buffer, eg &buf[LWS_PRE]
p	pointer to current position in buffer pointer
end	pointer to end of buffer

Terminates the headers correctly according to the protocol in use (h1 / h2) and writes the headers. Returns nonzero for error.

This is a convenience wrapper around lws_finalize_write_http_header_flags() (declared in lws-write.h, alongside the write-protocol enum) that passes plain LWS_WRITE_HTTP_HEADERS, suitable for responses that will send a body afterwards. For a headers-only response (eg a 302 with no body), use lws_finalize_write_http_header_flags() with LWS_WRITE_HTTP_HEADERS | LWS_WRITE_H2_STREAM_END so that under h2 / h3 the HEADERS frame carries END_STREAM – otherwise the stream hangs open waiting for a body that never comes and the client sees no response.

lws_add_http_common_headers()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_add_http_common_headers	(	struct lws *	wsi,
		unsigned int	code,
		const char *	content_type,
		lws_filepos_t	content_len,
		unsigned char **	p,
		unsigned char *	end )

#include <lws-http.h>

lws_add_http_common_headers() - Helper preparing common http headers

Parameters

wsi	the connection to check
code	an HTTP code like 200, 404 etc (see enum http_status)
content_type	the content type, like "text/html"
content_len	the content length, in bytes
p	pointer to current position in buffer pointer
end	pointer to end of buffer

Adds the initial response code, so should be called first.

Code may additionally take OR'd flags:

LWSAHH_FLAG_NO_SERVER_NAME: don't apply server name header this time

This helper just calls public apis to simplify adding headers that are commonly needed. If it doesn't fit your case, or you want to add additional headers just call the public apis directly yourself for what you want.

You can miss out the content length header by providing the constant LWS_ILLEGAL_HTTP_CONTENT_LEN for the content_len.

It does not call lws_finalize_http_header(), to allow you to add further headers after calling this. You will need to call that yourself at the end.

lws_http_get_uri_and_method()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_http_get_uri_and_method	(	struct lws *	wsi,
		char **	puri_ptr,
		int *	puri_len )

#include <lws-http.h>

lws_http_get_uri_and_method() - Get information on method and url

Parameters

wsi	the connection to get information on
puri_ptr	points to pointer to set to url
puri_len	points to int to set to uri length

Returns -1 or method index as one of the LWSHUMETH_ constants

If returns method, *puri_ptr is set to the method's URI string and *puri_len to its length

References LWS_EXTERN, and LWS_VISIBLE.