SDK3.5
This document shows Ameba SDK 3.5 APIs
Data Structures | Functions | Variables

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

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.

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]connpointer 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]connpointer 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]ptrpointer 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]pathresource path for a page
[in]callbackcallback 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]connpointer to connection context
[in]fieldheader field string to search
[out]valuesearch 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]connpointer to connection context
[in]keykey name string to search
[out]valuesearch 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]connpointer to connection context
[in]methodHTTP 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]connpointer to connection context
[out]databuffer for data read
[in]data_lenbuffer 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]connpointer 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]connpointer to connection context
[in]msgmessage 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]connpointer to connection context
[in]msgmessage 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]connpointer to connection context
[in]msgmessage 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]connpointer to connection context
[in]msgmessage 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]connpointer to connection context
[in]msgmessage 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]connpointer to connection context
[in]msgmessage 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]connpointer to connection context
[in]datadata to be written
[in]data_lendata 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]connpointer to connection context
[in]nameHTTP header field name string
[in]valueHTTP 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]connpointer 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]connpointer to connection context
[in]statusstring of status code in HTTP response
[in]content_typestring of Content-Type header field written to HTTP response. No Content-Type in HTTP response if NULL.
[in]content_lenvalue 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_certstring of server certificate
[in]server_keystring of server private key
[in]ca_certsstring 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]debugflag 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]userstring of user name for authorization
[in]passwordstring 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]portservice port
[in]max_connmax client connections allowed
[in]stack_bytesthread stack size in bytes
[in]thread_modeserver running thread mode. Must be HTTPD_THREAD_SINGLE, HTTPD_THREAD_MULTIPLE.
[in]securesecurity 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