libwebsockets
Lightweight C library for HTML5 websockets
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>

373 {
374 H2SET_HEADER_TABLE_SIZE = 1,
375 H2SET_ENABLE_PUSH,
376 H2SET_MAX_CONCURRENT_STREAMS,
377 H2SET_INITIAL_WINDOW_SIZE,
378 H2SET_MAX_FRAME_SIZE,
379 H2SET_MAX_HEADER_LIST_SIZE,
380 H2SET_RESERVED7,
381 H2SET_ENABLE_CONNECT_PROTOCOL, /* defined in mcmanus-httpbis-h2-ws-02 */
382
383 H2SET_COUNT /* always last */
384};

◆ lws_token_indexes

enum lws_token_indexes

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

215 {
216 WSI_TOKEN_GET_URI, /* 0 */
217 WSI_TOKEN_POST_URI,
218#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
219 WSI_TOKEN_OPTIONS_URI,
220#endif
221 WSI_TOKEN_HOST,
222 WSI_TOKEN_CONNECTION,
223 WSI_TOKEN_UPGRADE, /* 5 */
224 WSI_TOKEN_ORIGIN,
225#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
226 WSI_TOKEN_DRAFT,
227#endif
228 WSI_TOKEN_CHALLENGE,
229#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
230 WSI_TOKEN_EXTENSIONS,
231 WSI_TOKEN_KEY1, /* 10 */
232 WSI_TOKEN_KEY2,
233 WSI_TOKEN_PROTOCOL,
234 WSI_TOKEN_ACCEPT,
235 WSI_TOKEN_NONCE,
236#endif
237 WSI_TOKEN_HTTP,
238#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
239 WSI_TOKEN_HTTP2_SETTINGS, /* 16 */
240#endif
241 WSI_TOKEN_HTTP_ACCEPT,
242#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
243 WSI_TOKEN_HTTP_AC_REQUEST_HEADERS,
244#endif
245 WSI_TOKEN_HTTP_IF_MODIFIED_SINCE,
246 WSI_TOKEN_HTTP_IF_NONE_MATCH, /* 20 */
247 WSI_TOKEN_HTTP_ACCEPT_ENCODING,
248 WSI_TOKEN_HTTP_ACCEPT_LANGUAGE,
249 WSI_TOKEN_HTTP_PRAGMA,
250 WSI_TOKEN_HTTP_CACHE_CONTROL,
251 WSI_TOKEN_HTTP_AUTHORIZATION,
252 WSI_TOKEN_HTTP_COOKIE,
253 WSI_TOKEN_HTTP_CONTENT_LENGTH, /* 27 */
254 WSI_TOKEN_HTTP_CONTENT_TYPE,
255 WSI_TOKEN_HTTP_DATE,
256 WSI_TOKEN_HTTP_RANGE,
257#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
258 WSI_TOKEN_HTTP_REFERER,
259#endif
260#if defined(LWS_ROLE_WS) || defined(LWS_HTTP_HEADERS_ALL)
261 WSI_TOKEN_KEY,
262 WSI_TOKEN_VERSION,
263 WSI_TOKEN_SWORIGIN,
264#endif
265#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
266 WSI_TOKEN_HTTP_COLON_AUTHORITY,
267 WSI_TOKEN_HTTP_COLON_METHOD,
268 WSI_TOKEN_HTTP_COLON_PATH,
269 WSI_TOKEN_HTTP_COLON_SCHEME,
270 WSI_TOKEN_HTTP_COLON_STATUS,
271#endif
272
273#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
274 WSI_TOKEN_HTTP_ACCEPT_CHARSET,
275#endif
276 WSI_TOKEN_HTTP_ACCEPT_RANGES,
277#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
278 WSI_TOKEN_HTTP_ACCESS_CONTROL_ALLOW_ORIGIN,
279#endif
280 WSI_TOKEN_HTTP_AGE,
281 WSI_TOKEN_HTTP_ALLOW,
282 WSI_TOKEN_HTTP_CONTENT_DISPOSITION,
283 WSI_TOKEN_HTTP_CONTENT_ENCODING,
284 WSI_TOKEN_HTTP_CONTENT_LANGUAGE,
285 WSI_TOKEN_HTTP_CONTENT_LOCATION,
286 WSI_TOKEN_HTTP_CONTENT_RANGE,
287 WSI_TOKEN_HTTP_ETAG,
288 WSI_TOKEN_HTTP_EXPECT,
289 WSI_TOKEN_HTTP_EXPIRES,
290 WSI_TOKEN_HTTP_FROM,
291 WSI_TOKEN_HTTP_IF_MATCH,
292 WSI_TOKEN_HTTP_IF_RANGE,
293 WSI_TOKEN_HTTP_IF_UNMODIFIED_SINCE,
294 WSI_TOKEN_HTTP_LAST_MODIFIED,
295 WSI_TOKEN_HTTP_LINK,
296 WSI_TOKEN_HTTP_LOCATION,
297#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
298 WSI_TOKEN_HTTP_MAX_FORWARDS,
299 WSI_TOKEN_HTTP_PROXY_AUTHENTICATE,
300 WSI_TOKEN_HTTP_PROXY_AUTHORIZATION,
301#endif
302 WSI_TOKEN_HTTP_REFRESH,
303 WSI_TOKEN_HTTP_RETRY_AFTER,
304 WSI_TOKEN_HTTP_SERVER,
305 WSI_TOKEN_HTTP_SET_COOKIE,
306#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
307 WSI_TOKEN_HTTP_STRICT_TRANSPORT_SECURITY,
308#endif
309 WSI_TOKEN_HTTP_TRANSFER_ENCODING,
310#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
311 WSI_TOKEN_HTTP_USER_AGENT,
312 WSI_TOKEN_HTTP_VARY,
313 WSI_TOKEN_HTTP_VIA,
314 WSI_TOKEN_HTTP_WWW_AUTHENTICATE,
315#endif
316#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
317 WSI_TOKEN_PATCH_URI,
318 WSI_TOKEN_PUT_URI,
319 WSI_TOKEN_DELETE_URI,
320#endif
321
322 WSI_TOKEN_HTTP_URI_ARGS,
323#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
324 WSI_TOKEN_PROXY,
325 WSI_TOKEN_HTTP_X_REAL_IP,
326#endif
327 WSI_TOKEN_HTTP1_0,
328 WSI_TOKEN_X_FORWARDED_FOR,
329 WSI_TOKEN_CONNECT,
330 WSI_TOKEN_HEAD_URI,
331#if defined(LWS_WITH_HTTP_UNCOMMON_HEADERS) || defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
332 WSI_TOKEN_TE,
333 WSI_TOKEN_REPLAY_NONCE, /* ACME */
334#endif
335#if defined(LWS_ROLE_H2) || defined(LWS_HTTP_HEADERS_ALL)
336 WSI_TOKEN_COLON_PROTOCOL,
337#endif
338 WSI_TOKEN_X_AUTH_TOKEN,
339 WSI_TOKEN_DSS_SIGNATURE,
340
341 /****** add new things just above ---^ ******/
342
343 /* use token storage to stash these internally, not for
344 * user use */
345
346 _WSI_TOKEN_CLIENT_SENT_PROTOCOLS,
347 _WSI_TOKEN_CLIENT_PEER_ADDRESS,
348 _WSI_TOKEN_CLIENT_URI,
349 _WSI_TOKEN_CLIENT_HOST,
350 _WSI_TOKEN_CLIENT_ORIGIN,
351 _WSI_TOKEN_CLIENT_METHOD,
352 _WSI_TOKEN_CLIENT_IFACE,
353 _WSI_TOKEN_CLIENT_ALPN,
354
355 /* always last real token index*/
356 WSI_TOKEN_COUNT,
357
358 /* parser state additions, no storage associated */
359 WSI_TOKEN_NAME_PART,
360#if defined(LWS_WITH_CUSTOM_HEADERS) || defined(LWS_HTTP_HEADERS_ALL)
361 WSI_TOKEN_UNKNOWN_VALUE_PART,
362#endif
363 WSI_TOKEN_SKIPPING,
364 WSI_TOKEN_SKIPPING_SAW_CR,
365 WSI_PARSING_COMPLETE,
366 WSI_INIT_TOKEN_MUXURL,
367};

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
wsithe connection to check
namethe arg name, like "token="
bufthe buffer to receive the urlarg (including the name= part)
lenthe 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
wsithe connection to check
namethe arg name, like "token" or "token="
bufthe buffer to receive the urlarg (including the name= part)
lenthe 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
wsiwebsocket connection
destdestination buffer
lenlength of destination buffer
hwhich 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
wsiwebsocket connection
destdestination buffer
lenlength of destination buffer
hwhich header index we are interested in
frag_idxwhich 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
wsiwebsocket connection
dstpointer to buffer to receive the copy
lennumber of bytes available at dst
nameheader string (including terminating :)
nlenlength 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
wsiwebsocket connection
nameheader string (including terminating :)
nlenlength 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
wsiwebsocket connection
cbcallback for each custom header name
opaqueignored 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
wsiwebsocket connection
hwhich header index we are interested in
frag_idxwhich 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
wsiwebsocket connection
hwhich 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
tokentoken index