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.

Function Documentation

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 <include/libwebsockets/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_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 <include/libwebsockets/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

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 <include/libwebsockets/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.

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 <include/libwebsockets/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

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 <include/libwebsockets/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

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 <include/libwebsockets/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

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 <include/libwebsockets/lws-http.h>

lws_finalize_write_http_header() - Helper finializing 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 accoring to the protocol in use (h1 / h2) and writes the headers. Returns nonzero for error.

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 <include/libwebsockets/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