HTTPD
Ameba SDK » Network

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