ESP-AT Lib  Version v0.3
Advanced AT parser for ESP8266 WiFi module
HTTP server

HTTP server based on callback API. More...

Modules

 Configuration
 Configuration of HTTP server app.
 
 FAT File System
 FATFS file system implementation for dynamic files.
 

Data Structures

struct  http_param_t
 HTTP parameters on http URI in format ?param1=value1&param2=value2&... More...
 
struct  http_cgi_t
 CGI structure to register handlers on URI paths. More...
 
struct  http_init_t
 HTTP server initialization structure. More...
 
struct  http_fs_file_table_t
 HTTP file system table structure of static files in device memory. More...
 
struct  http_fs_file_t
 HTTP response file structure. More...
 
struct  http_state_t
 HTTP state structure. More...
 

Macros

#define HTTP_MAX_HEADERS   4
 Maximal number of headers we can control.
 
#define esp_http_server_write_string(hs, str)   esp_http_server_write(hs, str, strlen(str))
 Write string to HTTP server output. More...
 

Typedefs

typedef char *(* http_cgi_fn) (http_param_t *params, size_t params_len)
 CGI callback function. More...
 
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. More...
 
typedef espr_t(* http_post_data_fn) (struct http_state *hs, esp_pbuf_p pbuf)
 Post data received on request function prototype. More...
 
typedef espr_t(* http_post_end_fn) (struct http_state *hs)
 End of POST data request function prototype. More...
 
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. More...
 
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. More...
 
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. More...
 
typedef uint8_t(* http_fs_close_fn) (struct http_fs_file *file)
 Close file callback function. More...
 

Enumerations

enum  http_req_method_t { HTTP_METHOD_NOTALLOWED, HTTP_METHOD_GET, HTTP_METHOD_POST }
 Request method type. More...
 
enum  http_ssi_state_t { HTTP_SSI_STATE_WAIT_BEGIN = 0x00, HTTP_SSI_STATE_BEGIN = 0x01, HTTP_SSI_STATE_TAG = 0x02, HTTP_SSI_STATE_END = 0x03 }
 List of SSI TAG parsing states. More...
 

Functions

espr_t esp_http_server_init (const http_init_t *init, esp_port_t port)
 Initialize HTTP server at specific port. More...
 
size_t esp_http_server_write (http_state_t *hs, const void *data, size_t len)
 Write data directly to connection from callback. More...
 

Detailed Description

HTTP server based on callback API.

SSI (Server Side Includes) tags support

SSI tags are supported on server to include user specific values as replacement of static content.

Each tag must start with HTTP_SSI_TAG_START tag and end with HTTP_SSI_TAG_END and tag must not be longer than HTTP_SSI_TAG_MAX_LEN. White spaces are not allowed and - character is not allowed in tag name. Example of valid tag is \<!--#my_tag--> (backslash is for escape only in this docs) where name of tag is my_tag.

The tag name is later sent to SSI callback function where user can send custom data as tag replacement.

CGI (Common Gateway Interface) support

CGI support allows you to hook different functions from clients to server.

Dynamic headers support

Library can (based on request filename) decide what could be a good response type header. When dynamic headers are active, server with parse input and will output up to 4 different header responses:

Note
When SSI parsing is enabled for output, Content-Length part of headers is not included. This is due to the fact that script does not know final output length as SSI tag outputs may have variable lengths. Instead, Content-Length output will be included only in case SSI parsing is not active for specific request
HTTP server example with CGI and SSI
/*
* CGI handler for CGI1,
* Called when "/cgi1.cgi" is invoked in browser
*/
static char *
cgi1_callback(http_param_t* params, size_t params_len) {
printf("CGI1 callback triggered\r\n");
return "/index.shtml";
}
/*
* CGI handler for CGI1,
* Called when "/my_cgi.cgi" is invoked in browser
*/
static char *
cgi2_callback(http_param_t* params, size_t params_len) {
printf("CGI2 callback triggered\r\n");
return "/index.shtml";
}
/*
* Create list of CGI handlers,
* it consists of uri and callback pair
*/
cgi_handlers[] = {
{ "/cgi1.cgi", cgi1_callback }, // Available on http://ip_addr/cgi1.cgi
{ "/my_cgi.cgi", cgi2_callback }, // Available on http://ip_addr/cgi2.cgi
};
/*
* Single callback function for all SSI tags,
* found in output templates
*
* User should use esp_http_server_write function,
* to write data to output as replacement for the tag
*/
static size_t
http_ssi_cb(http_state_t* hs, const char* tag_name, size_t tag_len) {
if (!strncmp("my_tag", tag_name, tag_len)) {
esp_http_server_write(hs, "my_tag replacement string");
}
return 0;
}
/*
* POST request started callback with
* content length greater than 0
*/
static espr_t
http_post_start(http_state_t* hs, const char* uri, uint32_t content_len) {
printf("POST started with content length: %d; on URI: %s\r\n", (int)content_len, uri);
return espOK;
}
/*
* POST request packet data received callback
* It may be called multiple times,
* depends on request size
*/
static espr_t
http_post_data(http_state_t* hs, esp_pbuf_p pbuf) {
printf("Data received: %d bytes\r\n", (int)esp_pbuf_length(pbuf, 1));
return espOK;
}
/*
* POST request finished callback
*/
static espr_t
http_post_end(http_state_t* hs) {
printf("Post finished!\r\n");
return espOK;
}
/*
* Define server parameters structure,
* later used by server application
*/
http_init = {
.post_start_fn = http_post_start, /* Define POST start callback */
.post_data_fn = http_post_data, /* Define POST data callback */
.post_end_fn = http_post_end, /* Define POST end callback */
.cgi = cgi_handlers, /* Define CGI handlers */
.cgi_count = ESP_ARRAYSIZE(cgi_handlers), //Set length of CGI handlers */
.ssi_fn = http_ssi_cb, /* Set global SSI tags callback */
};
/* Later, somewhere in code: */
esp_http_server_init(&http_init, 80); /* Enable server on port 80 */

Macro Definition Documentation

◆ esp_http_server_write_string

#define esp_http_server_write_string (   hs,
  str 
)    esp_http_server_write(hs, str, strlen(str))

Write string to HTTP server output.

Note
May only be called from SSI callback function
Parameters
[in]hsHTTP handle
[in]strString to write
Returns
Number of bytes written to output
See also
esp_http_server_write

Typedef Documentation

◆ http_cgi_fn

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

CGI callback function.

Parameters
[in]paramsPointer to list of parameteres and their values
[in]params_lenNumber of parameters
Returns
Function must return a new URI which is used later as response string, such as "/index.html" or similar

◆ http_fs_close_fn

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

Close file callback function.

Parameters
[in]fileFile to close
Returns
1 on success, 0 otherwise

◆ http_fs_open_fn

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.

Parameters
[in]filePointer to file where user has to set length of file if opening was successful
[in]pathPath of file to open
Returns
1 if file is opened, 0 otherwise

◆ http_fs_read_fn

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.

Parameters
[in]fileFile pointer to read content
[in]buffBuffer to read data to. When parameter is set to NULL, number of remaining bytes available to read should be returned
[in]btrNumber of bytes to read from file. This parameter has no meaning when buff is NULL
Returns
Number of bytes read or number of bytes available to read

◆ http_post_data_fn

typedef espr_t(* http_post_data_fn) (struct http_state *hs, esp_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
Parameters
[in]hsHTTP state
[in]pbufPacket buffer wit reciveed data
Returns
espOK on success, member of espr_t otherwise

◆ http_post_end_fn

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

End of POST data request function prototype.

Parameters
[in]hsHTTP state
Returns
espOK on success, member of espr_t otherwise

◆ http_post_start_fn

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.

Parameters
[in]hsHTTP state
[in]uriPOST request URI
[in]content_lengthTotal content length (Content-Length HTTP parameter) in units of bytes
Returns
espOK on success, member of espr_t otherwise

◆ http_ssi_fn

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
Parameters
[in]hsHTTP state
[in]tag_nameName of TAG to replace with user content
[in]tag_lenLength of TAG
Return values
1Everything was written on this tag
0There are still data to write to output which means callback will be called again for user to process all the data

Enumeration Type Documentation

◆ http_req_method_t

Request method type.

Enumerator
HTTP_METHOD_NOTALLOWED 

HTTP method is not allowed

HTTP_METHOD_GET 

HTTP request method GET

HTTP_METHOD_POST 

HTTP request method POST

◆ http_ssi_state_t

List of SSI TAG parsing states.

Enumerator
HTTP_SSI_STATE_WAIT_BEGIN 

Waiting beginning of tag

HTTP_SSI_STATE_BEGIN 

Beginning detected, parsing it

HTTP_SSI_STATE_TAG 

Parsing TAG value

HTTP_SSI_STATE_END 

Parsing end of TAG

Function Documentation

◆ esp_http_server_init()

espr_t esp_http_server_init ( const http_init_t init,
esp_port_t  port 
)

Initialize HTTP server at specific port.

Parameters
[in]initInitialization structure for server
[in]portPort for HTTP server, usually 80
Returns
espOK on success, member of espr_t otherwise

◆ esp_http_server_write()

size_t esp_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
[in]hsHTTP state
[in]dataData to write
[in]lenLength of bytes to write
Returns
Number of bytes written