HTTP Server

group LWESP_APP_HTTP_SERVER

HTTP server based on callback API.

Defines

HTTP_MAX_HEADERS

Maximal number of headers we can control.

lwesp_http_server_write_string(hs, str)

Write string to HTTP server output.

See also

lwesp_http_server_write

Note

May only be called from SSI callback function

Parameters

• hs – [in] HTTP handle

• str – [in] String to write

Returns

Number of bytes written to output

Typedefs

typedef char *(*http_cgi_fn)(http_param_t *params, size_t params_len)

CGI callback function.

Param params

[in] Pointer to list of parameteres and their values

Param params_len

[in] Number of parameters

Return

Function must return a new URI which is used later as response string, such as “/index.html” or similar

typedef lwespr_t (*http_post_start_fn)(struct http_state *hs, const char *uri, uint32_t content_length)

Post request started with non-zero content length function prototype.

Param hs

[in] HTTP state

Param uri

[in] POST request URI

Param content_length

[in] Total content length (Content-Length HTTP parameter) in units of bytes

Return

lwespOK on success, member of lwespr_t otherwise

typedef lwespr_t (*http_post_data_fn)(struct http_state *hs, lwesp_pbuf_p pbuf)

Post data received on request function prototype.

Note

This function may be called multiple time until content_length from http_post_start_fn callback is not reached

Param hs

[in] HTTP state

Param pbuf

[in] Packet buffer wit reciveed data

Return

lwespOK on success, member of lwespr_t otherwise

typedef lwespr_t (*http_post_end_fn)(struct http_state *hs)

End of POST data request function prototype.

Param hs

[in] HTTP state

Return

lwespOK on success, member of lwespr_t otherwise

typedef size_t (*http_ssi_fn)(struct http_state *hs, const char *tag_name, size_t tag_len)

SSI (Server Side Includes) callback function prototype.

Note

User can use server write functions to directly write to connection output

Param hs

[in] HTTP state

Param tag_name

[in] Name of TAG to replace with user content

Param tag_len

[in] Length of TAG

Retval 1

Everything was written on this tag

Retval 0

There are still data to write to output which means callback will be called again for user to process all the data

typedef uint8_t (*http_fs_open_fn)(struct http_fs_file *file, const char *path)

File system open file function Function is called when user file system (FAT or similar) should be invoked to open a file from specific path.

Param file

[in] Pointer to file where user has to set length of file if opening was successful

Param path

[in] Path of file to open

Return

1 if file is opened, 0 otherwise

typedef uint32_t (*http_fs_read_fn)(struct http_fs_file *file, void *buff, size_t btr)

File system read file function Function may be called for 2 purposes. First is to read data and second to get remaining length of file to read.

Param file

[in] File pointer to read content

Param buff

[in] Buffer to read data to. When parameter is set to NULL, number of remaining bytes available to read should be returned

Param btr

[in] Number of bytes to read from file. This parameter has no meaning when buff is NULL

Return

Number of bytes read or number of bytes available to read

typedef uint8_t (*http_fs_close_fn)(struct http_fs_file *file)

Close file callback function.

Param file

[in] File to close

Return

1 on success, 0 otherwise

Enums

enum http_req_method_t

Request method type.

Values:

enumerator HTTP_METHOD_NOTALLOWED

HTTP method is not allowed

enumerator HTTP_METHOD_GET

HTTP request method GET

enumerator HTTP_METHOD_POST

HTTP request method POST

enum http_ssi_state_t

List of SSI TAG parsing states.

Values:

enumerator HTTP_SSI_STATE_WAIT_BEGIN = 0x00

Waiting beginning of tag

enumerator HTTP_SSI_STATE_BEGIN = 0x01

Beginning detected, parsing it

enumerator HTTP_SSI_STATE_TAG = 0x02

Parsing TAG value

enumerator HTTP_SSI_STATE_END = 0x03

Parsing end of TAG

Functions

lwespr_t lwesp_http_server_init(const http_init_t *init, lwesp_port_t port)

Initialize HTTP server at specific port.

Parameters

• init – [in] Initialization structure for server

• port – [in] Port for HTTP server, usually 80

Returns

lwespOK on success, member of lwespr_t otherwise

size_t lwesp_http_server_write(http_state_t *hs, const void *data, size_t len)

Write data directly to connection from callback.

Note

This function may only be called from SSI callback function for HTTP server

Parameters

• hs – [in] HTTP state

• data – [in] Data to write

• len – [in] Length of bytes to write

Returns

Number of bytes written

struct http_param_t

#include <lwesp_http_server.h>

HTTP parameters on http URI in format ?param1=value1&param2=value2&...

Public Members

const char *name

Name of parameter

const char *value

Parameter value

struct http_cgi_t

#include <lwesp_http_server.h>

CGI structure to register handlers on URI paths.

Public Members

const char *uri

URI path for CGI handler

http_cgi_fn fn

Callback function to call when we have a CGI match

struct http_init_t

#include <lwesp_http_server.h>

HTTP server initialization structure.

Public Members

http_post_start_fn post_start_fn

Callback function for post start

http_post_data_fn post_data_fn

Callback functon for post data

http_post_end_fn post_end_fn

Callback functon for post end

const http_cgi_t *cgi

Pointer to array of CGI entries. Set to NULL if not used

size_t cgi_count

Length of CGI array. Set to 0 if not used

http_ssi_fn ssi_fn

SSI callback function

http_fs_open_fn fs_open

Open file function callback

http_fs_read_fn fs_read

Read file function callback

http_fs_close_fn fs_close

Close file function callback

struct http_fs_file_table_t

#include <lwesp_http_server.h>

HTTP file system table structure of static files in device memory.

Public Members

const char *path

File path, ex. “/index.html”

const void *data

Pointer to file data

uint32_t size

Size of file in units of bytes

struct http_fs_file_t

#include <lwesp_http_server.h>

HTTP response file structure.

Public Members

const uint8_t *data

Pointer to data array in case file is static

uint8_t is_static

Flag indicating file is static and no dynamic read is required

uint32_t size

Total length of file

uint32_t fptr

File pointer to indicate next read position

const uint16_t *rem_open_files

Pointer to number of remaining open files. User can use value on this pointer to get number of other opened files

void *arg

User custom argument, may be used for user specific file system object

struct http_state_t

#include <lwesp_http_server.h>

HTTP state structure.

Public Members

lwesp_conn_p conn

Connection handle

lwesp_pbuf_p p

Header received pbuf chain

size_t conn_mem_available

Available memory in connection send queue

uint32_t written_total

Total number of bytes written into send buffer

uint32_t sent_total

Number of bytes we already sent

http_req_method_t req_method

Used request method

uint8_t headers_received

Did we fully received a headers?

uint8_t process_resp

Process with response flag

uint32_t content_length

Total expected content length for request (on POST) (without headers)

uint32_t content_received

Content length received so far (POST request, without headers)

http_fs_file_t rlwesp_file

Response file structure

uint8_t rlwesp_file_opened

Status if response file is opened and ready

const uint8_t *buff

Buffer pointer with data

uint32_t buff_len

Total length of buffer

uint32_t buff_ptr

Current buffer pointer

void *arg

User optional argument

const char *dyn_hdr_strs[4]

Pointer to constant strings for dynamic header outputs

size_t dyn_hdr_idx

Current header for processing on output

size_t dyn_hdr_pos

Current position in current index for output

char dyn_hdr_cnt_len[30]

Content length header response: “Content-Length: 0123456789\r\n”

uint8_t is_ssi

Flag if current request is SSI enabled

http_ssi_state_t ssi_state

Current SSI state when parsing SSI tags

char ssi_tag_buff[5 + 3 + 10 + 1]

Temporary buffer for SSI tag storing

size_t ssi_tag_buff_ptr

Current write pointer

size_t ssi_tag_buff_written

Number of bytes written so far to output buffer in case tag is not valid

size_t ssi_tag_len

Length of SSI tag

size_t ssi_tag_process_more

Set to 1 when we have to process tag multiple times

group LWESP_APP_HTTP_SERVER_FS_FAT

FATFS file system implementation for dynamic files.

Functions

uint8_t http_fs_open(http_fs_file_t *file, const char *path)

Open a file of specific path.

Parameters

• file – [in] File structure to fill if file is successfully open

• path – [in] File path to open in format “/js/scripts.js” or “/index.html”

Returns

1 on success, 0 otherwise

uint32_t http_fs_read(http_fs_file_t *file, void *buff, size_t btr)

Read a file content.

Parameters

• file – [in] File handle to read

• buff – [out] Buffer to read data to. When set to NULL, function should return remaining available data to read

• btr – [in] Number of bytes to read. Has no meaning when buff = NULL

Returns

Number of bytes read or number of bytes available to read

uint8_t http_fs_close(http_fs_file_t *file)

Close a file handle.

Parameters

file – [in] File handle

Returns

1 on success, 0 otherwise