HTTP Server
HTTP server functions. More...
Modules | |
Types | |
HTTP server data types. | |
Macros | |
HTTP server macros. | |
Functions | |
zos_bool_t | zn_hs_is_running (void) |
Returns if the HTTP server is running. More... | |
char * | zn_hs_url_decode (char *buffer) |
Decode URL encoded string destructively (i.e. More... | |
zos_result_t | zn_hs_read_post_data (const http_server_request_t *request, uint8_t *buffer, uint16_t max_length, uint16_t *bytes_read_ptr) |
Read body of HTTP POST request. More... | |
zos_result_t | zn_hs_write_reply_header (const http_server_request_t *request, const char *mime_type, int32_t length, http_server_header_flag_t flags) |
Return HTTP response. More... | |
zos_result_t | zn_hs_write_chunked_data (const http_server_request_t *request, const void *data, uint32_t data_len, zos_bool_t flush_now) |
Write HTTP body with chunked encoding. More... | |
zos_result_t | zn_hs_write_data (const http_server_request_t *request, const void *data, uint32_t data_len, zos_bool_t flush_now) |
Write HTTP body with non-chunked encoding. More... | |
zos_bool_t | zn_hs_authorize_user (const http_server_request_t *request, char *processing_buffer, const char *user, const char *password) |
Authorize HTTP request user credentials. More... | |
zos_result_t | zn_hs_write_unauthorized_response (const http_server_request_t *request) |
Return Unauthorized HTTP response. More... | |
zos_result_t | zn_hs_write_not_found_response (const http_server_request_t *request) |
Return Not Found HTTP response. More... | |
zos_result_t | zn_hs_return_status_code (const http_server_request_t *request, uint32_t code, const char *msg) |
Return HTTP response with status code. More... | |
void | zn_hs_register_dynamic_page (const http_server_dynamic_page_t *page) |
Register dynamic URL callback. More... | |
void | zn_hs_register_header_callback (const http_custom_header_callback_t callback) |
Register custom header callback. More... | |
void | zn_hs_register_authorize_callback (const http_server_authorize_callback_t callback) |
Register unauthorized callback. More... | |
void | zn_hs_register_not_found_callback (const http_server_not_found_callback_t callback) |
Register page not found callback. More... | |
http_server_param_t * | zn_hs_get_param (const http_server_request_t *request, const char *key) |
Return GET parameter with specified key. More... | |
http_server_header_t * | zn_hs_get_header (const http_server_request_t *request, const char *key) |
Return request header with specified key. More... | |
http_server_method_t | zn_hs_get_method (const http_server_request_t *request) |
Return the method type of the HTTP request. More... | |
zos_result_t | zn_hs_get_tls_client_list (http_server_tls_client_t **client_list_ptr) |
Return list of recently connected TLS clients. More... | |
void | zn_hs_destroy_tls_client_list (http_server_tls_client_t *client_list) |
Release memory allocated by zn_hs_get_tls_client_list() More... | |
Detailed Description
HTTP server functions.
Function Documentation
zos_bool_t zn_hs_authorize_user | ( | const http_server_request_t * | request, |
char * | processing_buffer, |
||
const char * | user, |
||
const char * | password |
||
) |
Authorize HTTP request user credentials.
This validates the provided Basic credentials in an HTTP request. More info here
This should be call immediately after a http_server_request_processor_t callback. Typically zn_hs_write_unauthorized_response() would be called if this function returns ZOS_FALSE.
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback processing_buffer
This is used for internal prcoessing, it should be at least 64 bytes user
The user name to validate against, set to NULL to use the http.server.username setting password
The password to validate against, set to NULL to use the http.server.password setting
- Returns
- zos_result_t result of api call
void zn_hs_destroy_tls_client_list | ( | http_server_tls_client_t * | client_list | ) |
Release memory allocated by zn_hs_get_tls_client_list()
- Parameters
-
client_list
List returned by zn_hs_get_tls_client_list()
http_server_header_t* zn_hs_get_header | ( | const http_server_request_t * | request, |
const char * | key |
||
) |
Return request header with specified key.
This allows for returning a HTTP header with the given key. Note that only http_server_request_header_t are returned with a HTTP request by default. To return custom headers, use zn_hs_register_header_callback() This should be used in a http_server_request_processor_t callback.
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback key
The HTTP header's key value
- Returns
- http_server_header_t if header with key found, NULL else
http_server_method_t zn_hs_get_method | ( | const http_server_request_t * | request | ) |
Return the method type of the HTTP request.
This should be used in a http_server_request_processor_t callback.
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback
- Returns
- The http_server_method_t of the current HTTP request
http_server_param_t* zn_hs_get_param | ( | const http_server_request_t * | request, |
const char * | key |
||
) |
Return GET parameter with specified key.
Returns a GET parameter's value.
A GET request contains parameters of the form:
The get the request's param1, the following code would be used:
This should be used in a http_server_request_processor_t callback.
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback key
The parameter's key value
- Returns
- http_server_param_t if key found, NULL else
zos_result_t zn_hs_get_tls_client_list | ( | http_server_tls_client_t ** | client_list_ptr | ) |
Return list of recently connected TLS clients.
Return list of recently connected clients. Up to 8 clients are logged. When the log contains 8 clients and a new client is added, the oldest client is removed. Requires http.server.tls_log_clients to be enabled.
zn_hs_destroy_tls_client_list() must be called to free the memory allocated by the returned list.
See ZentriOS Command API documentation: http.server.tls_client_log.
- Parameters
-
[out] client_list_ptr
Pointer to hold linked list of http_server_tls_client_t
zos_bool_t zn_hs_is_running | ( | void |
| ) |
Returns if the HTTP server is running.
- Returns
- ZOS_TRUE if the HTTP server is running, ZOS_FALSE else
zos_result_t zn_hs_read_post_data | ( | const http_server_request_t * | request, |
uint8_t * | buffer, |
||
uint16_t | max_length, |
||
uint16_t * | bytes_read_ptr |
||
) |
Read body of HTTP POST request.
This should be used in a http_server_request_processor_t callback.
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback buffer
Buffer to hold read POST data max_length
The size of the provided buffer bytes_read_ptr
Holds the number of bytes actually read, set NULL if not used
- Returns
- zos_result_t result of api call
void zn_hs_register_authorize_callback | ( | const http_server_authorize_callback_t | callback | ) |
Register unauthorized callback.
Register callback to be called to authorized username/password of HTTP request. The callback executes in the HTTP server thread.
- Parameters
-
callback
Callback to be called before processing HTTP request, see http_server_authorize_callback_t
- Returns
- zos_result_t result of api call
void zn_hs_register_dynamic_page | ( | const http_server_dynamic_page_t * | page | ) |
Register dynamic URL callback.
The callback will be called when the specified URL is requested. The callback executes in the HTTP server thread context.
- Parameters
-
page
URL/callback to register, see http_server_dynamic_page_t
- Returns
- zos_result_t result of api call
- Examples:
- sensors/accel_interrupt/main.c.
void zn_hs_register_header_callback | ( | const http_custom_header_callback_t | callback | ) |
Register custom header callback.
Register callback to be called for each HTTP request header. This allows for storing custom HTTP headers in the HTTP request object.
The custom headers are retrieved from the http_server_request_t with zn_hs_get_header() The callback executes in the HTTP server thread BEFORE the http_server_request_processor_t is called.
- Parameters
-
callback
Callback to be called for each HTTP header, see http_custom_header_callback_t
- Returns
- zos_result_t result of api call
void zn_hs_register_not_found_callback | ( | const http_server_not_found_callback_t | callback | ) |
Register page not found callback.
Register callback to be called if requested URL is not found. The callback executes in the HTTP server thread.
- Parameters
-
callback
Callback to be called if request URL is not found, see http_server_not_found_callback_t
- Returns
- zos_result_t result of api call
zos_result_t zn_hs_return_status_code | ( | const http_server_request_t * | request, |
uint32_t | code, |
||
const char * | msg |
||
) |
Return HTTP response with status code.
Return a HTTP status code with optional message. The message is printed in the body of the response.
More info about HTTP status codes: here
This should be used in a http_server_request_processor_t callback.
- Note
- The HTTP client request is closed after the response is sent.
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback code
The http status code. msg
Optional message to print in body of response
- Returns
- zos_result_t result of api call
char* zn_hs_url_decode | ( | char * | buffer | ) |
Decode URL encoded string destructively (i.e.
in-place)
- Parameters
-
buffer
Pointer to url encoded string
- Returns
- Same pointer as buffer, with contents url decoded
zos_result_t zn_hs_write_chunked_data | ( | const http_server_request_t * | request, |
const void * | data, |
||
uint32_t | data_len, |
||
zos_bool_t | flush_now |
||
) |
Write HTTP body with chunked encoding.
Write the body of a HTTP request using 'Transfer-Encoding: chunked'.
zn_hs_write_reply_header() must be called first with its 'length' parameter set to -1.
This should be used in a http_server_request_processor_t callback.
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback data
Data to write to response data_len
Amount of data to write flush_now
Set to ZOS_FALSE if there is more data to write, ZOS_TRUE if this is the last write (which will complete the response)
- Returns
- zos_result_t result of api call
zos_result_t zn_hs_write_data | ( | const http_server_request_t * | request, |
const void * | data, |
||
uint32_t | data_len, |
||
zos_bool_t | flush_now |
||
) |
Write HTTP body with non-chunked encoding.
Write the body of the HTTP request using 'Content-Legnth: xxx'
zn_hs_write_reply_header() must be called first with its 'length' parameter > 0.
This should be used in a http_server_request_processor_t callback.
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback data
Data to write to response data_len
Amount of data to write flush_now
Set to ZOS_FALSE if there is more data to write, ZOS_TRUE if this is the last write (which will complete the response)
- Returns
- zos_result_t result of api call
zos_result_t zn_hs_write_not_found_response | ( | const http_server_request_t * | request | ) |
Return Not Found HTTP response.
Return a 404 Not Found HTTP response
This should be used in a http_server_request_processor_t callback.
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback
- Returns
- zos_result_t result of api call
zos_result_t zn_hs_write_reply_header | ( | const http_server_request_t * | request, |
const char * | mime_type, |
||
int32_t | length, |
||
http_server_header_flag_t | flags |
||
) |
Return HTTP response.
Completes a HTTP request with a 200 status code.
This should be used in a http_server_request_processor_t callback.
- Note
- To return a non-200 code, see zn_hs_return_status_code()
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback mime_type
The response 'Content-Type', set NULL if unused length
The 'Content-Length' if > 0, set to -1 for 'Transfer-Encoding: chunked' flags
Optionals flags to add to the response headers, http_server_header_flag_t
- Returns
- zos_result_t result of api call
zos_result_t zn_hs_write_unauthorized_response | ( | const http_server_request_t * | request | ) |
Return Unauthorized HTTP response.
Return a 403 Unauthorized HTTP response
This should be used in a http_server_request_processor_t callback.
- Parameters
-
request
Internal HTTP request pointer, provided by http_server_request_processor_t callback
- Returns
- zos_result_t result of api call