HTTP Server


HTTP server based on callback API.



Maximal number of headers we can control.

esp_http_server_write_string(hs, str)

Write string to HTTP server output.


May only be called from SSI callback function


Number of bytes written to output



  • [in] hs: HTTP handle

  • [in] str: String to write


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

CGI callback function.


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

  • [in] params: Pointer to list of parameteres and their values

  • [in] params_len: Number of parameters

typedef espr_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.


espOK on success, member of espr_t otherwise

  • [in] hs: HTTP state

  • [in] uri: POST request URI

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

typedef espr_t (*http_post_data_fn)(struct http_state *hs, esp_pbuf_p pbuf)

Post data received on request function prototype.


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


espOK on success, member of espr_t otherwise

  • [in] hs: HTTP state

  • [in] pbuf: Packet buffer wit reciveed data

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

End of POST data request function prototype.


espOK on success, member of espr_t otherwise

  • [in] hs: HTTP state

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.


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

  • [in] hs: HTTP state

  • [in] tag_name: Name of TAG to replace with user content

  • [in] tag_len: Length of TAG

Return Value
  • 1: Everything was written on this tag

  • 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.


1 if file is opened, 0 otherwise

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

  • [in] path: Path of file to open

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.


Number of bytes read or number of bytes available to read

  • [in] file: File pointer to read content

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

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

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

Close file callback function.


1 on success, 0 otherwise

  • [in] file: File to close


enum http_req_method_t

Request method type.



HTTP method is not allowed


HTTP request method GET


HTTP request method POST

enum http_ssi_state_t

List of SSI TAG parsing states.



Waiting beginning of tag


Beginning detected, parsing it


Parsing TAG value


Parsing end of TAG


espr_t esp_http_server_init(const http_init_t *init, esp_port_t port)

Initialize HTTP server at specific port.


espOK on success, member of espr_t otherwise

  • [in] init: Initialization structure for server

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

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

Write data directly to connection from callback.


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


Number of bytes written

  • [in] hs: HTTP state

  • [in] data: Data to write

  • [in] len: Length of bytes to write

struct http_param_t
#include <esp_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 <esp_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 <esp_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 <esp_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 <esp_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 <esp_http_server.h>

HTTP state structure.

Public Members

esp_conn_p conn

Connection handle

esp_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 resp_file

Response file structure

uint8_t resp_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


FATFS file system implementation for dynamic files.


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

Open a file of specific path.


1 on success, 0 otherwise

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

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

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

Read a file content.


Number of bytes read or number of bytes available to read

  • [in] file: File handle to read

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

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

uint8_t http_fs_close(http_fs_file_t *file)

Close a file handle.


1 on success, 0 otherwise

  • [in] file: File handle