HTTP headers: read

Data Structures
struct	lws_tokens
struct	lws_token_limits

Typedefs
typedef void(*	lws_hdr_custom_fe_cb_t) (const char *name, int nlen, void *opaque)

Enumerations
enum	lws_token_indexes {   WSI_TOKEN_GET_URI , WSI_TOKEN_POST_URI , WSI_TOKEN_HOST , WSI_TOKEN_CONNECTION ,   WSI_TOKEN_UPGRADE , WSI_TOKEN_ORIGIN , WSI_TOKEN_CHALLENGE , WSI_TOKEN_HTTP ,   WSI_TOKEN_HTTP_ACCEPT , WSI_TOKEN_HTTP_IF_MODIFIED_SINCE , WSI_TOKEN_HTTP_IF_NONE_MATCH , WSI_TOKEN_HTTP_ACCEPT_ENCODING ,   WSI_TOKEN_HTTP_ACCEPT_LANGUAGE , WSI_TOKEN_HTTP_PRAGMA , WSI_TOKEN_HTTP_CACHE_CONTROL , WSI_TOKEN_HTTP_AUTHORIZATION ,   WSI_TOKEN_HTTP_COOKIE , WSI_TOKEN_HTTP_CONTENT_LENGTH , WSI_TOKEN_HTTP_CONTENT_TYPE , WSI_TOKEN_HTTP_DATE ,   WSI_TOKEN_HTTP_RANGE , WSI_TOKEN_HTTP_ACCEPT_RANGES , WSI_TOKEN_HTTP_AGE , WSI_TOKEN_HTTP_ALLOW ,   WSI_TOKEN_HTTP_CONTENT_DISPOSITION , WSI_TOKEN_HTTP_CONTENT_ENCODING , WSI_TOKEN_HTTP_CONTENT_LANGUAGE , WSI_TOKEN_HTTP_CONTENT_LOCATION ,   WSI_TOKEN_HTTP_CONTENT_RANGE , WSI_TOKEN_HTTP_ETAG , WSI_TOKEN_HTTP_EXPECT , WSI_TOKEN_HTTP_EXPIRES ,   WSI_TOKEN_HTTP_FROM , WSI_TOKEN_HTTP_IF_MATCH , WSI_TOKEN_HTTP_IF_RANGE , WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE ,   WSI_TOKEN_HTTP_LAST_MODIFIED , WSI_TOKEN_HTTP_LINK , WSI_TOKEN_HTTP_LOCATION , WSI_TOKEN_HTTP_REFRESH ,   WSI_TOKEN_HTTP_RETRY_AFTER , WSI_TOKEN_HTTP_SERVER , WSI_TOKEN_HTTP_SET_COOKIE , WSI_TOKEN_HTTP_TRANSFER_ENCODING ,   WSI_TOKEN_HTTP_URI_ARGS , WSI_TOKEN_HTTP1_0 , WSI_TOKEN_X_FORWARDED_FOR , WSI_TOKEN_CONNECT ,   WSI_TOKEN_HEAD_URI , WSI_TOKEN_X_AUTH_TOKEN , WSI_TOKEN_DSS_SIGNATURE , _WSI_TOKEN_CLIENT_SENT_PROTOCOLS ,   _WSI_TOKEN_CLIENT_PEER_ADDRESS , _WSI_TOKEN_CLIENT_URI , _WSI_TOKEN_CLIENT_HOST , _WSI_TOKEN_CLIENT_ORIGIN ,   _WSI_TOKEN_CLIENT_METHOD , _WSI_TOKEN_CLIENT_IFACE , _WSI_TOKEN_CLIENT_ALPN , WSI_TOKEN_COUNT ,   WSI_TOKEN_NAME_PART , WSI_TOKEN_SKIPPING , WSI_TOKEN_SKIPPING_SAW_CR , WSI_PARSING_COMPLETE ,   WSI_INIT_TOKEN_MUXURL }
enum	lws_h2_settings {   H2SET_HEADER_TABLE_SIZE = 1 , H2SET_ENABLE_PUSH , H2SET_MAX_CONCURRENT_STREAMS , H2SET_INITIAL_WINDOW_SIZE ,   H2SET_MAX_FRAME_SIZE , H2SET_MAX_HEADER_LIST_SIZE , H2SET_RESERVED7 , H2SET_ENABLE_CONNECT_PROTOCOL ,   H2SET_COUNT }

Functions
LWS_VISIBLE LWS_EXTERN const unsigned char *	lws_token_to_string (enum lws_token_indexes token)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_hdr_total_length (struct lws *wsi, enum lws_token_indexes h)
LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT	lws_hdr_fragment_length (struct lws *wsi, enum lws_token_indexes h, int frag_idx)
LWS_VISIBLE LWS_EXTERN int	lws_hdr_copy (struct lws *wsi, char *dest, int len, enum lws_token_indexes h)
LWS_VISIBLE LWS_EXTERN int	lws_hdr_copy_fragment (struct lws *wsi, char *dest, int len, enum lws_token_indexes h, int frag_idx)
LWS_VISIBLE LWS_EXTERN int	lws_hdr_custom_length (struct lws *wsi, const char *name, int nlen)
LWS_VISIBLE LWS_EXTERN int	lws_hdr_custom_copy (struct lws *wsi, char *dst, int len, const char *name, int nlen)
LWS_VISIBLE LWS_EXTERN int	lws_hdr_custom_name_foreach (struct lws *wsi, lws_hdr_custom_fe_cb_t cb, void *opaque)
LWS_VISIBLE LWS_EXTERN int	lws_get_urlarg_by_name_safe (struct lws *wsi, const char *name, char *buf, int len)
LWS_VISIBLE LWS_EXTERN const char *	lws_get_urlarg_by_name (struct lws *wsi, const char *name, char *buf, int len)

Detailed Description

HTTP header releated functions

In lws the client http headers are temporarily stored in a pool, only for the duration of the http part of the handshake. It's because in most cases, the header content is ignored for the whole rest of the connection lifetime and would then just be taking up space needlessly.

During LWS_CALLBACK_HTTP when the URI path is delivered is the last time the http headers are still allocated, you can use these apis then to look at and copy out interesting header content (cookies, etc)

Notice that the header total length reported does not include a terminating '\0', however you must allocate for it when using the _copy apis. So the length reported for a header containing "123" is 3, but you must provide a buffer of length 4 so that "123\0" may be copied into it, or the copy will fail with a nonzero return code.

In the special case of URL arguments, like ?x=1&y=2, the arguments are stored in a token named for the method, eg, WSI_TOKEN_GET_URI if it was a GET or WSI_TOKEN_POST_URI if POST. You can check the total length to confirm the method.

For URL arguments, each argument is stored urldecoded in a "fragment", so you can use the fragment-aware api lws_hdr_copy_fragment() to access each argument in turn: the fragments contain urldecoded strings like x=1 or y=2.

As a convenience, lws has an api that will find the fragment with a given name= part, lws_get_urlarg_by_name().

Enumeration Type Documentation

lws_h2_settings

enum lws_h2_settings

#include <include/libwebsockets/lws-http.h>

                     {
        H2SET_HEADER_TABLE_SIZE = 1,
        H2SET_ENABLE_PUSH,
        H2SET_MAX_CONCURRENT_STREAMS,
        H2SET_INITIAL_WINDOW_SIZE,
        H2SET_MAX_FRAME_SIZE,
        H2SET_MAX_HEADER_LIST_SIZE,
        H2SET_RESERVED7,
        H2SET_ENABLE_CONNECT_PROTOCOL, /* defined in mcmanus-httpbis-h2-ws-02 */
 
        H2SET_COUNT /* always last */
};

lws_token_indexes

enum lws_token_indexes

#include <include/libwebsockets/lws-http.h>

                       {
        WSI_TOKEN_GET_URI, /* 0 */
        WSI_TOKEN_POST_URI,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_OPTIONS_URI,
#endif
        WSI_TOKEN_HOST,
        WSI_TOKEN_CONNECTION,
        WSI_TOKEN_UPGRADE, /* 5 */
        WSI_TOKEN_ORIGIN,
#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_DRAFT,
#endif
        WSI_TOKEN_CHALLENGE,
#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_EXTENSIONS,
        WSI_TOKEN_KEY1, /* 10 */
        WSI_TOKEN_KEY2,
        WSI_TOKEN_PROTOCOL,
        WSI_TOKEN_ACCEPT,
        WSI_TOKEN_NONCE,
#endif
        WSI_TOKEN_HTTP,
#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_HTTP2_SETTINGS, /* 16 */
#endif
        WSI_TOKEN_HTTP_ACCEPT,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_HTTP_AC_REQUEST_HEADERS,
#endif
        WSI_TOKEN_HTTP_IF_MODIFIED_SINCE,
        WSI_TOKEN_HTTP_IF_NONE_MATCH, /* 20 */
        WSI_TOKEN_HTTP_ACCEPT_ENCODING,
        WSI_TOKEN_HTTP_ACCEPT_LANGUAGE,
        WSI_TOKEN_HTTP_PRAGMA,
        WSI_TOKEN_HTTP_CACHE_CONTROL,
        WSI_TOKEN_HTTP_AUTHORIZATION,
        WSI_TOKEN_HTTP_COOKIE,
        WSI_TOKEN_HTTP_CONTENT_LENGTH, /* 27 */
        WSI_TOKEN_HTTP_CONTENT_TYPE,
        WSI_TOKEN_HTTP_DATE,
        WSI_TOKEN_HTTP_RANGE,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_HTTP_REFERER,
#endif
#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_KEY,
        WSI_TOKEN_VERSION,
        WSI_TOKEN_SWORIGIN,
#endif
#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_HTTP_COLON_AUTHORITY,
        WSI_TOKEN_HTTP_COLON_METHOD,
        WSI_TOKEN_HTTP_COLON_PATH,
        WSI_TOKEN_HTTP_COLON_SCHEME,
        WSI_TOKEN_HTTP_COLON_STATUS,
#endif
 
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_HTTP_ACCEPT_CHARSET,
#endif
        WSI_TOKEN_HTTP_ACCEPT_RANGES,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_HTTP_ACCESS_CONTROL_ALLOW_ORIGIN,
#endif
        WSI_TOKEN_HTTP_AGE,
        WSI_TOKEN_HTTP_ALLOW,
        WSI_TOKEN_HTTP_CONTENT_DISPOSITION,
        WSI_TOKEN_HTTP_CONTENT_ENCODING,
        WSI_TOKEN_HTTP_CONTENT_LANGUAGE,
        WSI_TOKEN_HTTP_CONTENT_LOCATION,
        WSI_TOKEN_HTTP_CONTENT_RANGE,
        WSI_TOKEN_HTTP_ETAG,
        WSI_TOKEN_HTTP_EXPECT,
        WSI_TOKEN_HTTP_EXPIRES,
        WSI_TOKEN_HTTP_FROM,
        WSI_TOKEN_HTTP_IF_MATCH,
        WSI_TOKEN_HTTP_IF_RANGE,
        WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE,
        WSI_TOKEN_HTTP_LAST_MODIFIED,
        WSI_TOKEN_HTTP_LINK,
        WSI_TOKEN_HTTP_LOCATION,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_HTTP_MAX_FORWARDS,
        WSI_TOKEN_HTTP_PROXY_AUTHENTICATE,
        WSI_TOKEN_HTTP_PROXY_AUTHORIZATION,
#endif
        WSI_TOKEN_HTTP_REFRESH,
        WSI_TOKEN_HTTP_RETRY_AFTER,
        WSI_TOKEN_HTTP_SERVER,
        WSI_TOKEN_HTTP_SET_COOKIE,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_HTTP_STRICT_TRANSPORT_SECURITY,
#endif
        WSI_TOKEN_HTTP_TRANSFER_ENCODING,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_HTTP_USER_AGENT,
        WSI_TOKEN_HTTP_VARY,
        WSI_TOKEN_HTTP_VIA,
        WSI_TOKEN_HTTP_WWW_AUTHENTICATE,
#endif
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_PATCH_URI,
        WSI_TOKEN_PUT_URI,
        WSI_TOKEN_DELETE_URI,
#endif
 
        WSI_TOKEN_HTTP_URI_ARGS,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_PROXY,
        WSI_TOKEN_HTTP_X_REAL_IP,
#endif
        WSI_TOKEN_HTTP1_0,
        WSI_TOKEN_X_FORWARDED_FOR,
        WSI_TOKEN_CONNECT,
        WSI_TOKEN_HEAD_URI,
#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_TE,
        WSI_TOKEN_REPLAY_NONCE, /* ACME */
#endif
#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_COLON_PROTOCOL,
#endif
        WSI_TOKEN_X_AUTH_TOKEN,
        WSI_TOKEN_DSS_SIGNATURE,
 
        /****** add new things just above ---^ ******/
 
        /* use token storage to stash these internally, not for
         * user use */
 
        _WSI_TOKEN_CLIENT_SENT_PROTOCOLS,
        _WSI_TOKEN_CLIENT_PEER_ADDRESS,
        _WSI_TOKEN_CLIENT_URI,
        _WSI_TOKEN_CLIENT_HOST,
        _WSI_TOKEN_CLIENT_ORIGIN,
        _WSI_TOKEN_CLIENT_METHOD,
        _WSI_TOKEN_CLIENT_IFACE,
        _WSI_TOKEN_CLIENT_ALPN,
 
        /* always last real token index*/
        WSI_TOKEN_COUNT,
 
        /* parser state additions, no storage associated */
        WSI_TOKEN_NAME_PART,
#if defined(LWS_WITH_CUSTOM_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
        WSI_TOKEN_UNKNOWN_VALUE_PART,
#endif
        WSI_TOKEN_SKIPPING,
        WSI_TOKEN_SKIPPING_SAW_CR,
        WSI_PARSING_COMPLETE,
        WSI_INIT_TOKEN_MUXURL,
};

Function Documentation

lws_get_urlarg_by_name()

LWS_VISIBLE LWS_EXTERN const char * lws_get_urlarg_by_name	(	struct lws *	wsi,
		const char *	name,
		char *	buf,
		int	len )

#include <include/libwebsockets/lws-http.h>

lws_get_urlarg_by_name() - return pointer to arg value if present

Parameters

wsi	the connection to check
name	the arg name, like "token="
buf	the buffer to receive the urlarg (including the name= part)
len	the length of the buffer to receive the urlarg Returns NULL if not found or a pointer inside buf to just after the name= part.

This assumed the argument can be represented with a NUL-terminated string. It can't correctly deal with binary values encoded with XX, eg. %00 will be understood to terminate the string.

Use lws_get_urlarg_by_name_safe() instead of this, which returns the length.

lws_get_urlarg_by_name_safe()

LWS_VISIBLE LWS_EXTERN int lws_get_urlarg_by_name_safe	(	struct lws *	wsi,
		const char *	name,
		char *	buf,
		int	len )

#include <include/libwebsockets/lws-http.h>

lws_get_urlarg_by_name_safe() - get copy and return length of y for x=y urlargs

Parameters

wsi	the connection to check
name	the arg name, like "token" or "token="
buf	the buffer to receive the urlarg (including the name= part)
len	the length of the buffer to receive the urlarg

Returns -1 if not present, else the length of y in the urlarg name=y. If zero or greater, then buf contains a copy of the string y. Any = after the name match is trimmed off if the name does not end with = itself.

This returns the explicit length and so can deal with binary blobs that are percent-encoded. It also makes sure buf has a NUL just after the valid length so it can work with NUL-based apis if you don't care about truncation.

buf may have been written even when -1 is returned indicating no match.

Use this in place of lws_get_urlarg_by_name() that does not return an explicit length.

lws_hdr_copy()

LWS_VISIBLE LWS_EXTERN int lws_hdr_copy	(	struct lws *	wsi,
		char *	dest,
		int	len,
		enum lws_token_indexes	h )

#include <include/libwebsockets/lws-http.h>

lws_hdr_copy() - copy all fragments of the given header to a buffer The buffer length len must include space for an additional terminating '\0', or it will fail returning -1.

Parameters

wsi	websocket connection
dest	destination buffer
len	length of destination buffer
h	which header index we are interested in

copies the whole, aggregated header, even if it was delivered in several actual headers piece by piece. Returns -1 or length of the whole header.

lws_hdr_copy_fragment()

LWS_VISIBLE LWS_EXTERN int lws_hdr_copy_fragment	(	struct lws *	wsi,
		char *	dest,
		int	len,
		enum lws_token_indexes	h,
		int	frag_idx )

#include <include/libwebsockets/lws-http.h>

lws_hdr_copy_fragment() - copy a single fragment of the given header to a buffer The buffer length len must include space for an additional terminating '\0', or it will fail returning -1. If the requested fragment index is not present, it fails returning -1.

Parameters

wsi	websocket connection
dest	destination buffer
len	length of destination buffer
h	which header index we are interested in
frag_idx	which fragment of h we want to copy

Normally this is only useful to parse URI arguments like ?x=1&y=2, token index WSI_TOKEN_HTTP_URI_ARGS fragment 0 will contain "x=1" and fragment 1 "y=2"

lws_hdr_custom_copy()

LWS_VISIBLE LWS_EXTERN int lws_hdr_custom_copy	(	struct lws *	wsi,
		char *	dst,
		int	len,
		const char *	name,
		int	nlen )

#include <include/libwebsockets/lws-http.h>

lws_hdr_custom_copy() - copy value part of a custom header

Parameters

wsi	websocket connection
dst	pointer to buffer to receive the copy
len	number of bytes available at dst
name	header string (including terminating :)
nlen	length of name

Lws knows about 100 common http headers, and parses them into indexes when it recognizes them. When it meets a header that it doesn't know, it stores the name and value directly, and you can look them up using lws_hdr_custom_length() and lws_hdr_custom_copy().

This api returns -1, or the length of the string it copied into dst if it was big enough to contain both the string and an extra terminating NUL. Lws must be built with LWS_WITH_CUSTOM_HEADERS (on by default) to use this api.

lws_hdr_custom_length()

LWS_VISIBLE LWS_EXTERN int lws_hdr_custom_length	(	struct lws *	wsi,
		const char *	name,
		int	nlen )

#include <include/libwebsockets/lws-http.h>

lws_hdr_custom_length() - return length of a custom header

Parameters

wsi	websocket connection
name	header string (including terminating :)
nlen	length of name

Lws knows about 100 common http headers, and parses them into indexes when it recognizes them. When it meets a header that it doesn't know, it stores the name and value directly, and you can look them up using lws_hdr_custom_length() and lws_hdr_custom_copy().

This api returns -1, or the length of the value part of the header if it exists. Lws must be built with LWS_WITH_CUSTOM_HEADERS (on by default) to use this api.

lws_hdr_custom_name_foreach()

LWS_VISIBLE LWS_EXTERN int lws_hdr_custom_name_foreach	(	struct lws *	wsi,
		lws_hdr_custom_fe_cb_t	cb,
		void *	opaque )

#include <include/libwebsockets/lws-http.h>

lws_hdr_custom_name_foreach() - Iterate the custom header names

Parameters

wsi	websocket connection
cb	callback for each custom header name
opaque	ignored by lws except to pass to callback

Lws knows about 100 common http headers, and parses them into indexes when it recognizes them. When it meets a header that it doesn't know, it stores the name and value directly, and you can look them up using lws_hdr_custom_length() and lws_hdr_custom_copy().

This api returns -1 on error else 0. Use lws_hdr_custom_copy() to get the values of headers. Lws must be built with LWS_WITH_CUSTOM_HEADERS (on by default) to use this api.

lws_hdr_fragment_length()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_hdr_fragment_length	(	struct lws *	wsi,
		enum lws_token_indexes	h,
		int	frag_idx )

#include <include/libwebsockets/lws-http.h>

lws_hdr_fragment_length: report length of a single fragment of a header The returned length does not include the space for a terminating '\0'

Parameters

wsi	websocket connection
h	which header index we are interested in
frag_idx	which fragment of h we want to get the length of

lws_hdr_total_length()

LWS_VISIBLE LWS_EXTERN int LWS_WARN_UNUSED_RESULT lws_hdr_total_length	(	struct lws *	wsi,
		enum lws_token_indexes	h )

#include <include/libwebsockets/lws-http.h>

lws_hdr_total_length: report length of all fragments of a header totalled up The returned length does not include the space for a terminating '\0'

Parameters

wsi	websocket connection
h	which header index we are interested in

lws_token_to_string()

LWS_VISIBLE LWS_EXTERN const unsigned char * lws_token_to_string

(

enum lws_token_indexes

token

)

#include <include/libwebsockets/lws-http.h>

lws_token_to_string() - returns a textual representation of a hdr token index

Parameters

token

token index