HTTP/HTTPS server functions. More...

Data Structures
struct	http_request
	The structure is the context used for HTTP request header parsing. More...

struct	httpd_conn
	The structure is the context used for client connection. More...

Macros
#define	HTTPD_SECURE_NONE 0

#define	HTTPD_SECURE_TLS 1

#define	HTTPD_SECURE_TLS_VERIFY 2

#define	HTTPD_THREAD_SINGLE 0

#define	HTTPD_THREAD_MULTIPLE 1

#define	HTTPD_DEBUG_OFF 0

#define	HTTPD_DEBUG_ON 1

#define	HTTPD_DEBUG_VERBOSE 2

#define	HTTPD_TLS_POLARSSL 0

#define	HTTPD_TLS_MBEDTLS 1

Functions
int	httpd_start (uint16_t port, uint8_t max_conn, uint32_t stack_bytes, uint8_t thread_mode, uint8_t secure)
	This function is used to start an HTTP or HTTPS server. More...

void	httpd_stop (void)
	This function is used to stop a running server. More...

int	httpd_reg_page_callback (char path, void(callback)(struct httpd_conn *conn))
	This function is used to register a callback function for a Web page request handling. More...

void	httpd_clear_page_callbacks (void)
	This function is used to clear all registered page callback functions. More...

void	httpd_setup_debug (uint8_t debug)
	This function is used to setup httpd debug. More...

int	httpd_setup_cert (const char server_cert, const char server_key, const char *ca_certs)
	This function is used to setup certificate and key for server before starting with HTTPS. More...

int	httpd_setup_user_password (char user, char password)
	This function is used to setup authorization for server. More...

void	httpd_free (void *ptr)
	This function is used to free memory allocated by httpd API, such as httpd_request_get_header_field() and httpd_request_get_query_key(). More...

void	httpd_conn_close (struct httpd_conn *conn)
	This function is used to close a client connection and release context resource. More...

void	httpd_conn_dump_header (struct httpd_conn *conn)
	This function is used to dump the parsed HTTP header of request in connection context. More...

int	httpd_request_is_method (struct httpd_conn conn, char method)
	This function is used to check HTTP method of request in connection context. More...

int	httpd_request_read_header (struct httpd_conn *conn)
	This function is used to read HTTP header from client socket descriptor and parse content to connection context. More...

int	httpd_request_read_data (struct httpd_conn conn, uint8_t data, size_t data_len)
	This function is used to read data from HTTP/HTTPS connection. More...

int	httpd_request_get_header_field (struct httpd_conn conn, char field, char **value)
	This function is used to get a header field from HTTP header of connection context. More...

int	httpd_request_get_query_key (struct httpd_conn conn, char key, char **value)
	This function is used to get a key value from query string in HTTP header of connection context. More...

int	httpd_response_write_header_start (struct httpd_conn conn, char status, char *content_type, size_t content_len)
	This function is used to start a HTTP response in connection. More...

int	httpd_response_write_header (struct httpd_conn conn, char name, char *value)
	This function is used to add an HTTP header field to HTTP response. More...

int	httpd_response_write_header_finish (struct httpd_conn *conn)
	This function is used to write HTTP response header data to connection. More...

int	httpd_response_write_data (struct httpd_conn conn, uint8_t data, size_t data_len)
	This function is used to write HTTP response body data to connection. More...

void	httpd_response_bad_request (struct httpd_conn conn, char msg)
	This function is used to write a default HTTP response for error of 400 Bad Request. More...

void	httpd_response_unauthorized (struct httpd_conn conn, char msg)
	This function is used to write a default HTTP response for error of 401 Unauthorized. More...

void	httpd_response_not_found (struct httpd_conn conn, char msg)
	This function is used to write a default HTTP response for error of 404 Not Found. More...

void	httpd_response_method_not_allowed (struct httpd_conn conn, char msg)
	This function is used to write a default HTTP response for error of 405 Method Not Allowed. More...

void	httpd_response_too_many_requests (struct httpd_conn conn, char msg)
	This function is used to write a default HTTP response for error of 429 Too Many Requests. More...

void	httpd_response_internal_server_error (struct httpd_conn conn, char msg)
	This function is used to write a default HTTP response for error of 500 Internal Server Error. More...

Variables
uint8_t *	header

size_t	header_len

uint8_t *	method

size_t	method_len

uint8_t *	path

size_t	path_len

uint8_t *	query

size_t	query_len

uint8_t *	version

size_t	version_len

uint8_t *	host

size_t	host_len

uint8_t *	content_type

size_t	content_type_len

size_t	content_len

int	sock

struct http_request	request

void *	tls

uint8_t *	response_header

Detailed Description

HTTP/HTTPS server functions.

Macro Definition Documentation

#define HTTPD_DEBUG_OFF 0

Disable httpd debug log

#define HTTPD_DEBUG_ON 1

Enable httpd debug log

#define HTTPD_DEBUG_VERBOSE 2

Enable httpd verbose debug log

#define HTTPD_SECURE_NONE 0

Running with HTTP server

#define HTTPD_SECURE_TLS 1

Running with HTTPS server

#define HTTPD_SECURE_TLS_VERIFY 2

Running with HTTPS server and verify client

#define HTTPD_THREAD_MULTIPLE 1

Single-thread mode for request handling

#define HTTPD_THREAD_SINGLE 0

Multi-thread mode for request handling

#define HTTPD_TLS_MBEDTLS 1

Use mbedTLS for TLS when HTTPS

#define HTTPD_TLS_POLARSSL 0

Use PolarSSL for TLS when HTTPS

Function Documentation

void httpd_clear_page_callbacks ( void )

This function is used to clear all registered page callback functions.

Returns: None

Note: All page callback will be cleared automatically if httpd_stop().

void httpd_conn_close ( struct httpd_conn * conn )

This function is used to close a client connection and release context resource.

Parameters

[in] conn pointer to connection context

Returns: None

Note: Multiple requests/response can be handled in a connection before connection closed. All connections will be closed automatically if httpd_stop().

void httpd_conn_dump_header ( struct httpd_conn * conn )

This function is used to dump the parsed HTTP header of request in connection context.

Parameters

[in] conn pointer to connection context

Returns: None

void httpd_free ( void * ptr )

This function is used to free memory allocated by httpd API, such as httpd_request_get_header_field() and httpd_request_get_query_key().

Parameters

[in] ptr pointer to memory to be deallocated

Returns: None

int httpd_reg_page_callback	(	char *	path,
		void()(struct httpd_conn conn)	callback
	)

This function is used to register a callback function for a Web page request handling.

Parameters

[in]	path	resource path for a page
[in]	callback	callback function to handle the request to page

Returns: 0 : if successful; -1 : if error occurred

int httpd_request_get_header_field	(	struct httpd_conn *	conn,
		char *	field,
		char **	value
	)

This function is used to get a header field from HTTP header of connection context.

Parameters

[in]	conn	pointer to connection context
[in]	field	header field string to search
[out]	value	search result stored in memory allocated

Returns: 0 : if found; -1 : if not found

Note: The search result memory should be free by httpd_free().

int httpd_request_get_query_key	(	struct httpd_conn *	conn,
		char *	key,
		char **	value
	)

This function is used to get a key value from query string in HTTP header of connection context.

Parameters

[in]	conn	pointer to connection context
[in]	key	key name string to search
[out]	value	search result stored in memory allocated

Returns: 0 : if found; -1 : if not found

Note: The search result memory should be free by httpd_free().

int httpd_request_is_method	(	struct httpd_conn *	conn,
		char *	method
	)

This function is used to check HTTP method of request in connection context.

Parameters

[in]	conn	pointer to connection context
[in]	method	HTTP method string to compare with

Returns: 0 : if different; 1 : if matched

int httpd_request_read_data	(	struct httpd_conn *	conn,
		uint8_t *	data,
		size_t	data_len
	)

This function is used to read data from HTTP/HTTPS connection.

Parameters

[in]	conn	pointer to connection context
[out]	data	buffer for data read
[in]	data_len	buffer length

Returns: return value of lwip socket read() for HTTP and PolarSSL ssl_read() for HTTPS

int httpd_request_read_header ( struct httpd_conn * conn )

This function is used to read HTTP header from client socket descriptor and parse content to connection context.

Parameters

[in] conn pointer to connection context

Returns: 0 : if successful; -1 : if error occurred

Note: httpd_request_read_header() is automatically invoked by httpd server to parse request before executing page callback

void httpd_response_bad_request	(	struct httpd_conn *	conn,
		char *	msg
	)

This function is used to write a default HTTP response for error of 400 Bad Request.

Parameters

[in]	conn	pointer to connection context
[in]	msg	message write to HTTP response body. A default message will be used if NULL.

Returns: None

void httpd_response_internal_server_error	(	struct httpd_conn *	conn,
		char *	msg
	)

This function is used to write a default HTTP response for error of 500 Internal Server Error.

Parameters

[in]	conn	pointer to connection context
[in]	msg	message write to HTTP response body. A default message will be used if NULL.

Returns: None

void httpd_response_method_not_allowed	(	struct httpd_conn *	conn,
		char *	msg
	)

This function is used to write a default HTTP response for error of 405 Method Not Allowed.

Parameters

[in]	conn	pointer to connection context
[in]	msg	message write to HTTP response body. A default message will be used if NULL.

Returns: None

void httpd_response_not_found	(	struct httpd_conn *	conn,
		char *	msg
	)

This function is used to write a default HTTP response for error of 404 Not Found.

Parameters

[in]	conn	pointer to connection context
[in]	msg	message write to HTTP response body. A default message will be used if NULL.

Returns: None

void httpd_response_too_many_requests	(	struct httpd_conn *	conn,
		char *	msg
	)

This function is used to write a default HTTP response for error of 429 Too Many Requests.

Parameters

[in]	conn	pointer to connection context
[in]	msg	message write to HTTP response body. A default message will be used if NULL.

Returns: None

void httpd_response_unauthorized	(	struct httpd_conn *	conn,
		char *	msg
	)

This function is used to write a default HTTP response for error of 401 Unauthorized.

Parameters

[in]	conn	pointer to connection context
[in]	msg	message write to HTTP response body. A default message will be used if NULL.

Returns: None

int httpd_response_write_data	(	struct httpd_conn *	conn,
		uint8_t *	data,
		size_t	data_len
	)

This function is used to write HTTP response body data to connection.

Parameters

[in]	conn	pointer to connection context
[in]	data	data to be written
[in]	data_len	data length

Returns: return value of lwip socket write() for HTTP and PolarSSL ssl_write() for HTTPS

int httpd_response_write_header	(	struct httpd_conn *	conn,
		char *	name,
		char *	value
	)

This function is used to add an HTTP header field to HTTP response.

Parameters

[in]	conn	pointer to connection context
[in]	name	HTTP header field name string
[in]	value	HTTP header field value

Returns: 0 : if successful; -1 : if error occurred

int httpd_response_write_header_finish ( struct httpd_conn * conn )

This function is used to write HTTP response header data to connection.

Parameters

[in] conn pointer to connection context

Returns: return value of lwip socket write() for HTTP and PolarSSL ssl_write() for HTTPS

int httpd_response_write_header_start	(	struct httpd_conn *	conn,
		char *	status,
		char *	content_type,
		size_t	content_len
	)

This function is used to start a HTTP response in connection.

Parameters

[in]	conn	pointer to connection context
[in]	status	string of status code in HTTP response
[in]	content_type	string of Content-Type header field written to HTTP response. No Content-Type in HTTP response if NULL.
[in]	content_len	value of Content-Length header field written to HTTP response. No Content-Length in HTTP response if NULL.

Returns: 0 : if successful; -1 : if error occurred

int httpd_setup_cert	(	const char *	server_cert,
		const char *	server_key,
		const char *	ca_certs
	)

This function is used to setup certificate and key for server before starting with HTTPS.

Parameters

[in]	server_cert	string of server certificate
[in]	server_key	string of server private key
[in]	ca_certs	string including certificates in CA trusted chain

Returns: 0 : if successful; -1 : if error occurred

Note: Must be used before httpd_start() if staring HTTPS server

void httpd_setup_debug ( uint8_t debug )

This function is used to setup httpd debug.

Parameters

[in] debug flag to enable/disable httpd debug. Must be HTTPD_DEBUG_OFF, HTTPD_DEBUG_ON, HTTPD_DEBUG_VERBOSE.

Returns: None

int httpd_setup_user_password	(	char *	user,
		char *	password
	)

This function is used to setup authorization for server.

Parameters

[in]	user	string of user name for authorization
[in]	password	string of password for authorization

Returns: 0 : if successful; -1 : if error occurred

Note: Must be used before httpd_start() if basic authorization is used

int httpd_start	(	uint16_t	port,
		uint8_t	max_conn,
		uint32_t	stack_bytes,
		uint8_t	thread_mode,
		uint8_t	secure
	)

This function is used to start an HTTP or HTTPS server.

Parameters

[in]	port	service port
[in]	max_conn	max client connections allowed
[in]	stack_bytes	thread stack size in bytes
[in]	thread_mode	server running thread mode. Must be HTTPD_THREAD_SINGLE, HTTPD_THREAD_MULTIPLE.
[in]	secure	security mode for HTTP or HTTPS. Must be HTTPD_SECURE_NONE, HTTPD_SECURE_TLS, HTTPD_SECURE_TLS_VERIFY.

Returns: 0 : if successful; -1 : if error occurred

void httpd_stop ( void )

This function is used to stop a running server.

Returns: None

Variable Documentation

size_t content_len

Value of Content-Length header field parsed in HTTP header string

uint8_t* content_type

Pointer to Content-Type header field in the parsed HTTP header string

size_t content_type_len

Content-Type header field data length

uint8_t* header

HTTP header string parsed in HTTP request

size_t header_len

HTTP header string length

uint8_t* host

Pointer to Host header field in the parsed HTTP header string

size_t host_len

Host header field data length

uint8_t* method

Pointer to HTTP method in the parsed HTTP header string

size_t method_len

HTTP method data length

uint8_t* path

Pointer to resource path in the parsed HTTP header string

size_t path_len

Resource path data length

uint8_t* query

Pointer to query string in the parsed HTTP header string

size_t query_len

Query string data length

struct http_request request

Context for HTTP request

uint8_t* response_header

Pointer to transmission buffer of HTTP response header

int sock

Client socket descriptor for connection

void* tls

Context for TLS connection

uint8_t* version

Pointer to HTTP version in the parsed HTTP header string

size_t version_len

HTTP version data length

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

Function Documentation

Variable Documentation