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  {
  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
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