libwebsockets
Lightweight C library for HTML5 websockets
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  {
  LWSBTNRGMFLAG_CLASSIFY_DOUBLECLICK = (1 << 0), LWS_TLS_REQ_ELEMENT_COUNTRY, LWS_TLS_REQ_ELEMENT_STATE, LWS_TLS_REQ_ELEMENT_LOCALITY,
  LWS_TLS_REQ_ELEMENT_ORGANIZATION, LWS_TLS_REQ_ELEMENT_COMMON_NAME, LWS_TLS_REQ_ELEMENT_SUBJECT_ALT_NAME, LWS_TLS_REQ_ELEMENT_EMAIL,
  LWS_TLS_REQ_ELEMENT_COUNT, LWS_TLS_SET_DIR_URL = LWS_TLS_REQ_ELEMENT_COUNT, LWS_TLS_SET_AUTH_PATH, LWS_TLS_SET_CERT_PATH,
  LWS_TLS_SET_KEY_PATH, LWS_TLS_TOTAL_COUNT, LDLT_READ, LDLT_WRITE,
  LDLT_NAME_RESOLUTION, LDLT_CONNECTION, LDLT_TLS_NEG_CLIENT, LDLT_TLS_NEG_SERVER,
  LDLT_USER, LAT_DUR_PROXY_CLIENT_REQ_TO_WRITE = 0, LAT_DUR_PROXY_CLIENT_WRITE_TO_PROXY_RX, LAT_DUR_PROXY_PROXY_REQ_TO_WRITE,
  LAT_DUR_PROXY_RX_TO_ONWARD_TX, LAT_DUR_USERCB, LAT_DUR_STEPS, LWSGGPIO_FL_READ = (1 << 0),
  LWSGGPIO_FL_WRITE = (1 << 1), LWSGGPIO_FL_PULLUP = (1 << 2), LWSGGPIO_FL_PULLDOWN = (1 << 3), LWSGGPIO_FL_START_LOW = (1 << 4),
  LWSHUMETH_GET, LWSHUMETH_POST, LWSHUMETH_OPTIONS, LWSHUMETH_PUT,
  LWSHUMETH_PATCH, LWSHUMETH_DELETE, LWSHUMETH_CONNECT, LWSHUMETH_HEAD,
  LWSHUMETH_COLON_PATH, LLSI_CURR, LLSI_NEXT, LLSI_TRANS,
  LWS_RXFLOW_REASON_USER_BOOL = (1 << 0), LWS_RXFLOW_REASON_HTTP_RXBUFFER = (1 << 6), LWS_RXFLOW_REASON_H2_PPS_PENDING = (1 << 7), LWS_RXFLOW_REASON_APPLIES = (1 << 14),
  LWS_RXFLOW_REASON_APPLIES_ENABLE_BIT = (1 << 13), LWS_RXFLOW_REASON_APPLIES_ENABLE, LWS_RXFLOW_REASON_APPLIES_DISABLE = LWS_RXFLOW_REASON_APPLIES, LWS_RXFLOW_REASON_FLAG_PROCESS_NOW = (1 << 12),
  LNDIW_ALG_OPEN, LNDIW_ALG_WPA2, LNDIW_MODE_STA = (1 << 0), LNDIW_MODE_AP = (1 << 1),
  LNDIW_UP = (1 << 7), LNDIW_ACQ_IPv4 = (1 << 0), LNDIW_ACQ_IPv6 = (1 << 1), LWSSS_FLAG_SOM = (1 << 0),
  LWSSS_FLAG_EOM = (1 << 1), LWSSS_FLAG_POLL = (1 << 2), LWSSS_FLAG_RELATED_START = (1 << 3), LWSSS_FLAG_RELATED_END = (1 << 4),
  LWSSS_FLAG_RIDESHARE = (1 << 5), LWSSS_SER_RXPRE_RX_PAYLOAD = 0x55, LWSSS_SER_RXPRE_CREATE_RESULT, LWSSS_SER_RXPRE_CONNSTATE,
  LWSSS_SER_RXPRE_TXCR_UPDATE, LWSSS_SER_RXPRE_TLSNEG_ENCLAVE_SIGN, LWSSS_SER_TXPRE_STREAMTYPE = 0xaa, LWSSS_SER_TXPRE_ONWARD_CONNECT,
  LWSSS_SER_TXPRE_DESTROYING, LWSSS_SER_TXPRE_TX_PAYLOAD, LWSSS_SER_TXPRE_METADATA, LWSSS_SER_TXPRE_TXCR_UPDATE,
  LWSSS_SER_TXPRE_TIMEOUT_UPDATE, LWSSS_SER_TXPRE_PAYLOAD_LENGTH_HINT, LWSSS_SER_TXPRE_TLSNEG_ENCLAVE_SIGNED, LWSSSPOLF_OPPORTUNISTIC = (1 << 0),
  LWSSSPOLF_NAILED_UP = (1 << 1), LWSSSPOLF_URGENT_TX = (1 << 2), LWSSSPOLF_URGENT_RX = (1 << 3), LWSSSPOLF_TLS = (1 << 4),
  LWSSSPOLF_LONG_POLL = (1 << 5), LWSSSPOLF_AUTH_BEARER = (1 << 6), LWSSSPOLF_HTTP_NO_CONTENT_LENGTH = (1 << 7), LWSSSPOLF_QUIRK_NGHTTP2_END_STREAM = (1 << 8),
  LWSSSPOLF_H2_QUIRK_OVERFLOWS_TXCR = (1 << 9), LWSSSPOLF_H2_QUIRK_UNCLEAN_HPACK_STATE = (1 << 10), LWSSSPOLF_HTTP_MULTIPART = (1 << 11), LWSSSPOLF_HTTP_X_WWW_FORM_URLENCODED = (1 << 12),
  LWSSSPOLF_LOCAL_SINK = (1 << 13), LWSSSPOLF_WAKE_SUSPEND__VALIDITY = (1 << 14), LWSSSPOLF_SERVER = (1 << 15), LWSSSPOLF_ALLOW_REDIRECTS = (1 << 16),
  LWSSSPOLF_HTTP_MULTIPART_IN = (1 << 17), LWSSMDCL_INTERACTION = (1 << 0), LWSSMDCL_SYSTEM_STATE = (1 << 1), LWSSMDCL_NETWORK = (1 << 2),
  LWSSPIMODE_CPOL = (1 << 0), LWSSPIMODE_CPHA = (1 << 1), LWS_SPI_BUSMODE_CLK_IDLE_LOW_SAMP_RISING = 0, LWS_SPI_BUSMODE_CLK_IDLE_HIGH_SAMP_RISING = LWSSPIMODE_CPOL,
  LWS_SPI_BUSMODE_CLK_IDLE_LOW_SAMP_FALLING = LWSSPIMODE_CPHA, LWS_SPI_BUSMODE_CLK_IDLE_HIGH_SAMP_FALLING, LWS_SPI_TXN_HALF_DUPLEX_DISCRETE = 0, LWSSTATS_C_CONNECTIONS,
  LWSSTATS_C_API_CLOSE, LWSSTATS_C_API_READ, LWSSTATS_C_API_LWS_WRITE, LWSSTATS_C_API_WRITE,
  LWSSTATS_C_WRITE_PARTIALS, LWSSTATS_C_WRITEABLE_CB_REQ, LWSSTATS_C_WRITEABLE_CB_EFF_REQ, LWSSTATS_C_WRITEABLE_CB,
  LWSSTATS_C_SSL_CONNECTIONS_FAILED, LWSSTATS_C_SSL_CONNECTIONS_ACCEPTED, LWSSTATS_C_SSL_ACCEPT_SPIN, LWSSTATS_C_SSL_CONNS_HAD_RX,
  LWSSTATS_C_TIMEOUTS, LWSSTATS_C_SERVICE_ENTRY, LWSSTATS_B_READ, LWSSTATS_B_WRITE,
  LWSSTATS_B_PARTIALS_ACCEPTED_PARTS, LWSSTATS_US_SSL_ACCEPT_LATENCY_AVG, LWSSTATS_US_WRITABLE_DELAY_AVG, LWSSTATS_US_WORST_WRITABLE_DELAY,
  LWSSTATS_US_SSL_RX_DELAY_AVG, LWSSTATS_C_PEER_LIMIT_AH_DENIED, LWSSTATS_C_PEER_LIMIT_WSI_DENIED, LWSSTATS_C_CONNS_CLIENT,
  LWSSTATS_C_CONNS_CLIENT_FAILED, LWSSTATS_SIZE, LSSERJ_FLAG_PRETTY = (1 << 0), LSSERJ_FLAG_OMIT_SCHEMA = (1 << 1),
  LSTRX_DONE, LSTRX_FILLED_OUT, LSTRX_FATAL_NAME_TOO_LONG = -1, LSTRX_FATAL_NAME_UNKNOWN = -2
}
 

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.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

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

Enumerator
LWSSSPOLF_OPPORTUNISTIC 

the connection doesn't exist unless client asks to write

LWSSSPOLF_NAILED_UP 

the connection tries to be connected the whole life of the ss

LWSSSPOLF_URGENT_TX 

this connection carries critical tx data

LWSSSPOLF_URGENT_RX 

this connection carries critical rx data

LWSSSPOLF_TLS 

stream must be connected via a tls tunnel

LWSSSPOLF_LONG_POLL 

stream used to receive async rx at arbitrary intervals

LWSSSPOLF_AUTH_BEARER 

for http, use lws_system auth token 0 in authentication: bearer

LWSSSPOLF_HTTP_NO_CONTENT_LENGTH 

don't add any content length even if we have it

LWSSSPOLF_QUIRK_NGHTTP2_END_STREAM 

set the client flag LCCSCF_H2_QUIRK_NGHTTP2_END_STREAM

LWSSSPOLF_H2_QUIRK_OVERFLOWS_TXCR 

set the client flag LCCSCF_H2_QUIRK_OVERFLOWS_TXCR

LWSSSPOLF_H2_QUIRK_UNCLEAN_HPACK_STATE 

HPACK decoder state does not end cleanly

LWSSSPOLF_HTTP_MULTIPART 

indicates stream goes out as specifically a multipart mime POST section... if the tx has LWSSS_FLAG_COALESCE_CONTINUES flag then more multipart sections are expected. Without it, the multipart wrapper is closed and the http transaction issue completed when this message finishes.

LWSSSPOLF_HTTP_X_WWW_FORM_URLENCODED 

set up lws_system client cert

LWSSSPOLF_LOCAL_SINK 

expected to bind to a local sink only

LWSSSPOLF_WAKE_SUSPEND__VALIDITY 

this stream's idle validity checks are critical enough we should arrange to wake from suspend to perform them

LWSSSPOLF_SERVER 

we listen on a socket as a server

LWSSSPOLF_ALLOW_REDIRECTS 

follow redirects

LWSSSPOLF_HTTP_MULTIPART_IN 

handle inbound multipart mime at SS level

LWSSMDCL_INTERACTION 

Any kind of event indicating a user was interacting with the device, eg, press a button, touched the screen, lifted the device etc

LWSSMDCL_SYSTEM_STATE 

The lws_system state changed, eg, to OPERATIONAL

LWSSMDCL_NETWORK 

Something happened on the network, eg, link-up or DHCP, or captive portal state update

LWS_SPI_TXN_HALF_DUPLEX_DISCRETE 

separate MISO and MOSI, but only either MISO or MOSI has data at one time... i2c style in SPI

LWSSTATS_C_CONNECTIONS 

count incoming connections

LWSSTATS_C_API_CLOSE 

count calls to close api

LWSSTATS_C_API_READ 

count calls to read from socket api

LWSSTATS_C_API_LWS_WRITE 

count calls to lws_write API

LWSSTATS_C_API_WRITE 

count calls to write API

LWSSTATS_C_WRITE_PARTIALS 

count of partial writes

LWSSTATS_C_WRITEABLE_CB_REQ 

count of writable callback requests

LWSSTATS_C_WRITEABLE_CB_EFF_REQ 

count of effective writable callback requests

LWSSTATS_C_WRITEABLE_CB 

count of writable callbacks

LWSSTATS_C_SSL_CONNECTIONS_FAILED 

count of failed SSL connections

LWSSTATS_C_SSL_CONNECTIONS_ACCEPTED 

count of accepted SSL connections

LWSSTATS_C_SSL_ACCEPT_SPIN 

count of SSL_accept() attempts

LWSSTATS_C_SSL_CONNS_HAD_RX 

count of accepted SSL conns that have had some RX

LWSSTATS_C_TIMEOUTS 

count of timed-out connections

LWSSTATS_C_SERVICE_ENTRY 

count of entries to lws service loop

LWSSTATS_B_READ 

aggregate bytes read

LWSSTATS_B_WRITE 

aggregate bytes written

LWSSTATS_B_PARTIALS_ACCEPTED_PARTS 

aggreate of size of accepted write data from new partials

LWSSTATS_US_SSL_ACCEPT_LATENCY_AVG 

aggregate delay in accepting connection

LWSSTATS_US_WRITABLE_DELAY_AVG 

aggregate delay between asking for writable and getting cb

LWSSTATS_US_WORST_WRITABLE_DELAY 

single worst delay between asking for writable and getting cb

LWSSTATS_US_SSL_RX_DELAY_AVG 

aggregate delay between ssl accept complete and first RX

LWSSTATS_C_PEER_LIMIT_AH_DENIED 

number of times we would have given an ah but for the peer limit

LWSSTATS_C_PEER_LIMIT_WSI_DENIED 

number of times we would have given a wsi but for the peer limit

LWSSTATS_C_CONNS_CLIENT 

attempted client conns

LWSSTATS_C_CONNS_CLIENT_FAILED 

failed client conns

655  {
656  LWSHUMETH_GET,
657  LWSHUMETH_POST,
658  LWSHUMETH_OPTIONS,
659  LWSHUMETH_PUT,
660  LWSHUMETH_PATCH,
661  LWSHUMETH_DELETE,
662  LWSHUMETH_CONNECT,
663  LWSHUMETH_HEAD,
664  LWSHUMETH_COLON_PATH,
665 };

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
wsithe connection to check
codean HTTP code like 200, 404 etc (see enum http_status)
content_typethe content type, like "text/html"
content_lenthe content length, in bytes
ppointer to current position in buffer pointer
endpointer 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
wsithe connection to check
namethe hdr name, like "my-header"
valuethe value after the = for this header
lengththe length of the value
ppointer to current position in buffer pointer
endpointer 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
wsithe connection to check
tokenthe token index for the hdr
valuethe value after the = for this header
lengththe length of the value
ppointer to current position in buffer pointer
endpointer 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
wsithe connection to check
content_lengththe content length to use
ppointer to current position in buffer pointer
endpointer 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
wsithe connection to check
codean HTTP code like 200, 404 etc (see enum http_status)
ppointer to current position in buffer pointer
endpointer 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
wsithe connection to check
ppointer to current position in buffer pointer
endpointer 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
wsithe connection to check
startpointer to the start of headers in the buffer, eg &buf[LWS_PRE]
ppointer to current position in buffer pointer
endpointer 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
wsithe connection to get information on
puri_ptrpoints to pointer to set to url
puri_lenpoints 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