mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
586207207f
UDP application sends packet using esp_netif, underlying transport such as Wi-Fi may drop the packet due to higher load. New error code represent transient, non-fatal packet drop error. udp application may use such errtype, for example to rate limit.
1817 lines
70 KiB
C
1817 lines
70 KiB
C
/*
|
|
* SPDX-FileCopyrightText: 2018-2024 Espressif Systems (Shanghai) CO LTD
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#ifndef _ESP_HTTP_SERVER_H_
|
|
#define _ESP_HTTP_SERVER_H_
|
|
|
|
#include <stdio.h>
|
|
#include <string.h>
|
|
#include <freertos/FreeRTOS.h>
|
|
#include <freertos/task.h>
|
|
#include <http_parser.h>
|
|
#include <sdkconfig.h>
|
|
#include <esp_err.h>
|
|
#include <esp_event.h>
|
|
#include <esp_event_base.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#define ESP_HTTPD_DEF_CTRL_PORT (32768) /*!< HTTP Server control socket port*/
|
|
|
|
ESP_EVENT_DECLARE_BASE(ESP_HTTP_SERVER_EVENT);
|
|
|
|
/**
|
|
* @brief HTTP Server events id
|
|
*/
|
|
typedef enum {
|
|
HTTP_SERVER_EVENT_ERROR = 0, /*!< This event occurs when there are any errors during execution */
|
|
HTTP_SERVER_EVENT_START, /*!< This event occurs when HTTP Server is started */
|
|
HTTP_SERVER_EVENT_ON_CONNECTED, /*!< Once the HTTP Server has been connected to the client, no data exchange has been performed */
|
|
HTTP_SERVER_EVENT_ON_HEADER, /*!< Occurs when receiving each header sent from the client */
|
|
HTTP_SERVER_EVENT_HEADERS_SENT, /*!< After sending all the headers to the client */
|
|
HTTP_SERVER_EVENT_ON_DATA, /*!< Occurs when receiving data from the client */
|
|
HTTP_SERVER_EVENT_SENT_DATA, /*!< Occurs when an ESP HTTP server session is finished */
|
|
HTTP_SERVER_EVENT_DISCONNECTED, /*!< The connection has been disconnected */
|
|
HTTP_SERVER_EVENT_STOP, /*!< This event occurs when HTTP Server is stopped */
|
|
} esp_http_server_event_id_t;
|
|
|
|
/** Argument structure for HTTP_SERVER_EVENT_ON_DATA and HTTP_SERVER_EVENT_SENT_DATA event */
|
|
typedef struct {
|
|
int fd; /*!< Session socket file descriptor */
|
|
int data_len; /*!< Data length */
|
|
} esp_http_server_event_data;
|
|
|
|
/*
|
|
note: esp_https_server.h includes a customized copy of this
|
|
initializer that should be kept in sync
|
|
*/
|
|
#define HTTPD_DEFAULT_CONFIG() { \
|
|
.task_priority = tskIDLE_PRIORITY+5, \
|
|
.stack_size = 4096, \
|
|
.core_id = tskNO_AFFINITY, \
|
|
.task_caps = (MALLOC_CAP_INTERNAL | MALLOC_CAP_8BIT), \
|
|
.server_port = 80, \
|
|
.ctrl_port = ESP_HTTPD_DEF_CTRL_PORT, \
|
|
.max_open_sockets = 7, \
|
|
.max_uri_handlers = 8, \
|
|
.max_resp_headers = 8, \
|
|
.backlog_conn = 5, \
|
|
.lru_purge_enable = false, \
|
|
.recv_wait_timeout = 5, \
|
|
.send_wait_timeout = 5, \
|
|
.global_user_ctx = NULL, \
|
|
.global_user_ctx_free_fn = NULL, \
|
|
.global_transport_ctx = NULL, \
|
|
.global_transport_ctx_free_fn = NULL, \
|
|
.enable_so_linger = false, \
|
|
.linger_timeout = 0, \
|
|
.keep_alive_enable = false, \
|
|
.keep_alive_idle = 0, \
|
|
.keep_alive_interval = 0, \
|
|
.keep_alive_count = 0, \
|
|
.open_fn = NULL, \
|
|
.close_fn = NULL, \
|
|
.uri_match_fn = NULL \
|
|
}
|
|
|
|
#define ESP_ERR_HTTPD_BASE (0xb000) /*!< Starting number of HTTPD error codes */
|
|
#define ESP_ERR_HTTPD_HANDLERS_FULL (ESP_ERR_HTTPD_BASE + 1) /*!< All slots for registering URI handlers have been consumed */
|
|
#define ESP_ERR_HTTPD_HANDLER_EXISTS (ESP_ERR_HTTPD_BASE + 2) /*!< URI handler with same method and target URI already registered */
|
|
#define ESP_ERR_HTTPD_INVALID_REQ (ESP_ERR_HTTPD_BASE + 3) /*!< Invalid request pointer */
|
|
#define ESP_ERR_HTTPD_RESULT_TRUNC (ESP_ERR_HTTPD_BASE + 4) /*!< Result string truncated */
|
|
#define ESP_ERR_HTTPD_RESP_HDR (ESP_ERR_HTTPD_BASE + 5) /*!< Response header field larger than supported */
|
|
#define ESP_ERR_HTTPD_RESP_SEND (ESP_ERR_HTTPD_BASE + 6) /*!< Error occurred while sending response packet */
|
|
#define ESP_ERR_HTTPD_ALLOC_MEM (ESP_ERR_HTTPD_BASE + 7) /*!< Failed to dynamically allocate memory for resource */
|
|
#define ESP_ERR_HTTPD_TASK (ESP_ERR_HTTPD_BASE + 8) /*!< Failed to launch server task/thread */
|
|
|
|
/* Symbol to be used as length parameter in httpd_resp_send APIs
|
|
* for setting buffer length to string length */
|
|
#define HTTPD_RESP_USE_STRLEN -1
|
|
|
|
/* ************** Group: Initialization ************** */
|
|
/** @name Initialization
|
|
* APIs related to the Initialization of the web server
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @brief HTTP Server Instance Handle
|
|
*
|
|
* Every instance of the server will have a unique handle.
|
|
*/
|
|
typedef void* httpd_handle_t;
|
|
|
|
/**
|
|
* @brief HTTP Method Type wrapper over "enum http_method"
|
|
* available in "http_parser" library
|
|
*/
|
|
typedef enum http_method httpd_method_t;
|
|
|
|
#define HTTP_ANY INT_MAX
|
|
|
|
/**
|
|
* @brief Prototype for freeing context data (if any)
|
|
* @param[in] ctx object to free
|
|
*/
|
|
typedef void (*httpd_free_ctx_fn_t)(void *ctx);
|
|
|
|
/**
|
|
* @brief Function prototype for opening a session.
|
|
*
|
|
* Called immediately after the socket was opened to set up the send/recv functions and
|
|
* other parameters of the socket.
|
|
*
|
|
* @param[in] hd server instance
|
|
* @param[in] sockfd session socket file descriptor
|
|
* @return
|
|
* - ESP_OK : On success
|
|
* - Any value other than ESP_OK will signal the server to close the socket immediately
|
|
*/
|
|
typedef esp_err_t (*httpd_open_func_t)(httpd_handle_t hd, int sockfd);
|
|
|
|
/**
|
|
* @brief Function prototype for closing a session.
|
|
*
|
|
* @note It's possible that the socket descriptor is invalid at this point, the function
|
|
* is called for all terminated sessions. Ensure proper handling of return codes.
|
|
*
|
|
* @param[in] hd server instance
|
|
* @param[in] sockfd session socket file descriptor
|
|
*/
|
|
typedef void (*httpd_close_func_t)(httpd_handle_t hd, int sockfd);
|
|
|
|
/**
|
|
* @brief Function prototype for URI matching.
|
|
*
|
|
* @param[in] reference_uri URI/template with respect to which the other URI is matched
|
|
* @param[in] uri_to_match URI/template being matched to the reference URI/template
|
|
* @param[in] match_upto For specifying the actual length of `uri_to_match` up to
|
|
* which the matching algorithm is to be applied (The maximum
|
|
* value is `strlen(uri_to_match)`, independent of the length
|
|
* of `reference_uri`)
|
|
* @return true on match
|
|
*/
|
|
typedef bool (*httpd_uri_match_func_t)(const char *reference_uri,
|
|
const char *uri_to_match,
|
|
size_t match_upto);
|
|
|
|
/**
|
|
* @brief HTTP Server Configuration Structure
|
|
*
|
|
* @note Use HTTPD_DEFAULT_CONFIG() to initialize the configuration
|
|
* to a default value and then modify only those fields that are
|
|
* specifically determined by the use case.
|
|
*/
|
|
typedef struct httpd_config {
|
|
unsigned task_priority; /*!< Priority of FreeRTOS task which runs the server */
|
|
size_t stack_size; /*!< The maximum stack size allowed for the server task */
|
|
BaseType_t core_id; /*!< The core the HTTP server task will run on */
|
|
uint32_t task_caps; /*!< The memory capabilities to use when allocating the HTTP server task's stack */
|
|
|
|
/**
|
|
* TCP Port number for receiving and transmitting HTTP traffic
|
|
*/
|
|
uint16_t server_port;
|
|
|
|
/**
|
|
* UDP Port number for asynchronously exchanging control signals
|
|
* between various components of the server
|
|
*/
|
|
uint16_t ctrl_port;
|
|
|
|
uint16_t max_open_sockets; /*!< Max number of sockets/clients connected at any time (3 sockets are reserved for internal working of the HTTP server) */
|
|
uint16_t max_uri_handlers; /*!< Maximum allowed uri handlers */
|
|
uint16_t max_resp_headers; /*!< Maximum allowed additional headers in HTTP response */
|
|
uint16_t backlog_conn; /*!< Number of backlog connections */
|
|
bool lru_purge_enable; /*!< Purge "Least Recently Used" connection */
|
|
uint16_t recv_wait_timeout; /*!< Timeout for recv function (in seconds)*/
|
|
uint16_t send_wait_timeout; /*!< Timeout for send function (in seconds)*/
|
|
|
|
/**
|
|
* Global user context.
|
|
*
|
|
* This field can be used to store arbitrary user data within the server context.
|
|
* The value can be retrieved using the server handle, available e.g. in the httpd_req_t struct.
|
|
*
|
|
* When shutting down, the server frees up the user context by
|
|
* calling free() on the global_user_ctx field. If you wish to use a custom
|
|
* function for freeing the global user context, please specify that here.
|
|
*/
|
|
void * global_user_ctx;
|
|
|
|
/**
|
|
* Free function for global user context
|
|
*/
|
|
httpd_free_ctx_fn_t global_user_ctx_free_fn;
|
|
|
|
/**
|
|
* Global transport context.
|
|
*
|
|
* Similar to global_user_ctx, but used for session encoding or encryption (e.g. to hold the SSL context).
|
|
* It will be freed using free(), unless global_transport_ctx_free_fn is specified.
|
|
*/
|
|
void * global_transport_ctx;
|
|
|
|
/**
|
|
* Free function for global transport context
|
|
*/
|
|
httpd_free_ctx_fn_t global_transport_ctx_free_fn;
|
|
|
|
bool enable_so_linger; /*!< bool to enable/disable linger */
|
|
int linger_timeout; /*!< linger timeout (in seconds) */
|
|
bool keep_alive_enable; /*!< Enable keep-alive timeout */
|
|
int keep_alive_idle; /*!< Keep-alive idle time. Default is 5 (second) */
|
|
int keep_alive_interval;/*!< Keep-alive interval time. Default is 5 (second) */
|
|
int keep_alive_count; /*!< Keep-alive packet retry send count. Default is 3 counts */
|
|
/**
|
|
* Custom session opening callback.
|
|
*
|
|
* Called on a new session socket just after accept(), but before reading any data.
|
|
*
|
|
* This is an opportunity to set up e.g. SSL encryption using global_transport_ctx
|
|
* and the send/recv/pending session overrides.
|
|
*
|
|
* If a context needs to be maintained between these functions, store it in the session using
|
|
* httpd_sess_set_transport_ctx() and retrieve it later with httpd_sess_get_transport_ctx()
|
|
*
|
|
* Returning a value other than ESP_OK will immediately close the new socket.
|
|
*/
|
|
httpd_open_func_t open_fn;
|
|
|
|
/**
|
|
* Custom session closing callback.
|
|
*
|
|
* Called when a session is deleted, before freeing user and transport contexts and before
|
|
* closing the socket. This is a place for custom de-init code common to all sockets.
|
|
*
|
|
* The server will only close the socket if no custom session closing callback is set.
|
|
* If a custom callback is used, `close(sockfd)` should be called in here for most cases.
|
|
*
|
|
* Set the user or transport context to NULL if it was freed here, so the server does not
|
|
* try to free it again.
|
|
*
|
|
* This function is run for all terminated sessions, including sessions where the socket
|
|
* was closed by the network stack - that is, the file descriptor may not be valid anymore.
|
|
*/
|
|
httpd_close_func_t close_fn;
|
|
|
|
/**
|
|
* URI matcher function.
|
|
*
|
|
* Called when searching for a matching URI:
|
|
* 1) whose request handler is to be executed right
|
|
* after an HTTP request is successfully parsed
|
|
* 2) in order to prevent duplication while registering
|
|
* a new URI handler using `httpd_register_uri_handler()`
|
|
*
|
|
* Available options are:
|
|
* 1) NULL : Internally do basic matching using `strncmp()`
|
|
* 2) `httpd_uri_match_wildcard()` : URI wildcard matcher
|
|
*
|
|
* Users can implement their own matching functions (See description
|
|
* of the `httpd_uri_match_func_t` function prototype)
|
|
*/
|
|
httpd_uri_match_func_t uri_match_fn;
|
|
} httpd_config_t;
|
|
|
|
/**
|
|
* @brief Starts the web server
|
|
*
|
|
* Create an instance of HTTP server and allocate memory/resources for it
|
|
* depending upon the specified configuration.
|
|
*
|
|
* Example usage:
|
|
* @code{c}
|
|
*
|
|
* //Function for starting the webserver
|
|
* httpd_handle_t start_webserver(void)
|
|
* {
|
|
* // Generate default configuration
|
|
* httpd_config_t config = HTTPD_DEFAULT_CONFIG();
|
|
*
|
|
* // Empty handle to http_server
|
|
* httpd_handle_t server = NULL;
|
|
*
|
|
* // Start the httpd server
|
|
* if (httpd_start(&server, &config) == ESP_OK) {
|
|
* // Register URI handlers
|
|
* httpd_register_uri_handler(server, &uri_get);
|
|
* httpd_register_uri_handler(server, &uri_post);
|
|
* }
|
|
* // If server failed to start, handle will be NULL
|
|
* return server;
|
|
* }
|
|
*
|
|
* @endcode
|
|
*
|
|
* @param[in] config Configuration for new instance of the server
|
|
* @param[out] handle Handle to newly created instance of the server. NULL on error
|
|
* @return
|
|
* - ESP_OK : Instance created successfully
|
|
* - ESP_ERR_INVALID_ARG : Null argument(s)
|
|
* - ESP_ERR_HTTPD_ALLOC_MEM : Failed to allocate memory for instance
|
|
* - ESP_ERR_HTTPD_TASK : Failed to launch server task
|
|
*/
|
|
esp_err_t httpd_start(httpd_handle_t *handle, const httpd_config_t *config);
|
|
|
|
/**
|
|
* @brief Stops the web server
|
|
*
|
|
* Deallocates memory/resources used by an HTTP server instance and
|
|
* deletes it. Once deleted the handle can no longer be used for accessing
|
|
* the instance.
|
|
*
|
|
* Example usage:
|
|
* @code{c}
|
|
*
|
|
* // Function for stopping the webserver
|
|
* void stop_webserver(httpd_handle_t server)
|
|
* {
|
|
* // Ensure handle is non NULL
|
|
* if (server != NULL) {
|
|
* // Stop the httpd server
|
|
* httpd_stop(server);
|
|
* }
|
|
* }
|
|
*
|
|
* @endcode
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @return
|
|
* - ESP_OK : Server stopped successfully
|
|
* - ESP_ERR_INVALID_ARG : Handle argument is Null
|
|
*/
|
|
esp_err_t httpd_stop(httpd_handle_t handle);
|
|
|
|
/** End of Group Initialization
|
|
* @}
|
|
*/
|
|
|
|
/* ************** Group: URI Handlers ************** */
|
|
/** @name URI Handlers
|
|
* APIs related to the URI handlers
|
|
* @{
|
|
*/
|
|
|
|
/* Max supported HTTP request header length */
|
|
#define HTTPD_MAX_REQ_HDR_LEN CONFIG_HTTPD_MAX_REQ_HDR_LEN
|
|
|
|
/* Max supported HTTP request URI length */
|
|
#define HTTPD_MAX_URI_LEN CONFIG_HTTPD_MAX_URI_LEN
|
|
|
|
/**
|
|
* @brief HTTP Request Data Structure
|
|
*/
|
|
typedef struct httpd_req {
|
|
httpd_handle_t handle; /*!< Handle to server instance */
|
|
int method; /*!< The type of HTTP request, -1 if unsupported method, HTTP_ANY for wildcard method to support every method */
|
|
const char uri[HTTPD_MAX_URI_LEN + 1]; /*!< The URI of this request (1 byte extra for null termination) */
|
|
size_t content_len; /*!< Length of the request body */
|
|
void *aux; /*!< Internally used members */
|
|
|
|
/**
|
|
* User context pointer passed during URI registration.
|
|
*/
|
|
void *user_ctx;
|
|
|
|
/**
|
|
* Session Context Pointer
|
|
*
|
|
* A session context. Contexts are maintained across 'sessions' for a
|
|
* given open TCP connection. One session could have multiple request
|
|
* responses. The web server will ensure that the context persists
|
|
* across all these request and responses.
|
|
*
|
|
* By default, this is NULL. URI Handlers can set this to any meaningful
|
|
* value.
|
|
*
|
|
* If the underlying socket gets closed, and this pointer is non-NULL,
|
|
* the web server will free up the context by calling free(), unless
|
|
* free_ctx function is set.
|
|
*/
|
|
void *sess_ctx;
|
|
|
|
/**
|
|
* Pointer to free context hook
|
|
*
|
|
* Function to free session context
|
|
*
|
|
* If the web server's socket closes, it frees up the session context by
|
|
* calling free() on the sess_ctx member. If you wish to use a custom
|
|
* function for freeing the session context, please specify that here.
|
|
*/
|
|
httpd_free_ctx_fn_t free_ctx;
|
|
|
|
/**
|
|
* Flag indicating if Session Context changes should be ignored
|
|
*
|
|
* By default, if you change the sess_ctx in some URI handler, the http server
|
|
* will internally free the earlier context (if non NULL), after the URI handler
|
|
* returns. If you want to manage the allocation/reallocation/freeing of
|
|
* sess_ctx yourself, set this flag to true, so that the server will not
|
|
* perform any checks on it. The context will be cleared by the server
|
|
* (by calling free_ctx or free()) only if the socket gets closed.
|
|
*/
|
|
bool ignore_sess_ctx_changes;
|
|
} httpd_req_t;
|
|
|
|
/**
|
|
* @brief Structure for URI handler
|
|
*/
|
|
typedef struct httpd_uri {
|
|
const char *uri; /*!< The URI to handle */
|
|
httpd_method_t method; /*!< Method supported by the URI, HTTP_ANY for wildcard method to support all methods*/
|
|
|
|
/**
|
|
* Handler to call for supported request method. This must
|
|
* return ESP_OK, or else the underlying socket will be closed.
|
|
*/
|
|
esp_err_t (*handler)(httpd_req_t *r);
|
|
|
|
/**
|
|
* Pointer to user context data which will be available to handler
|
|
*/
|
|
void *user_ctx;
|
|
|
|
#ifdef CONFIG_HTTPD_WS_SUPPORT
|
|
/**
|
|
* Flag for indicating a WebSocket endpoint.
|
|
* If this flag is true, then method must be HTTP_GET. Otherwise the handshake will not be handled.
|
|
*/
|
|
bool is_websocket;
|
|
|
|
/**
|
|
* Flag indicating that control frames (PING, PONG, CLOSE) are also passed to the handler
|
|
* This is used if a custom processing of the control frames is needed
|
|
*/
|
|
bool handle_ws_control_frames;
|
|
|
|
/**
|
|
* Pointer to subprotocol supported by URI
|
|
*/
|
|
const char *supported_subprotocol;
|
|
#endif
|
|
} httpd_uri_t;
|
|
|
|
/**
|
|
* @brief Registers a URI handler
|
|
*
|
|
* @note URI handlers can be registered in real time as long as the
|
|
* server handle is valid.
|
|
*
|
|
* Example usage:
|
|
* @code{c}
|
|
*
|
|
* esp_err_t my_uri_handler(httpd_req_t* req)
|
|
* {
|
|
* // Recv , Process and Send
|
|
* ....
|
|
* ....
|
|
* ....
|
|
*
|
|
* // Fail condition
|
|
* if (....) {
|
|
* // Return fail to close session //
|
|
* return ESP_FAIL;
|
|
* }
|
|
*
|
|
* // On success
|
|
* return ESP_OK;
|
|
* }
|
|
*
|
|
* // URI handler structure
|
|
* httpd_uri_t my_uri {
|
|
* .uri = "/my_uri/path/xyz",
|
|
* .method = HTTPD_GET,
|
|
* .handler = my_uri_handler,
|
|
* .user_ctx = NULL
|
|
* };
|
|
*
|
|
* // Register handler
|
|
* if (httpd_register_uri_handler(server_handle, &my_uri) != ESP_OK) {
|
|
* // If failed to register handler
|
|
* ....
|
|
* }
|
|
*
|
|
* @endcode
|
|
*
|
|
* @param[in] handle handle to HTTPD server instance
|
|
* @param[in] uri_handler pointer to handler that needs to be registered
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully registering the handler
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_HANDLERS_FULL : If no slots left for new handler
|
|
* - ESP_ERR_HTTPD_HANDLER_EXISTS : If handler with same URI and
|
|
* method is already registered
|
|
*/
|
|
esp_err_t httpd_register_uri_handler(httpd_handle_t handle,
|
|
const httpd_uri_t *uri_handler);
|
|
|
|
/**
|
|
* @brief Unregister a URI handler
|
|
*
|
|
* @param[in] handle handle to HTTPD server instance
|
|
* @param[in] uri URI string
|
|
* @param[in] method HTTP method
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully deregistering the handler
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_NOT_FOUND : Handler with specified URI and method not found
|
|
*/
|
|
esp_err_t httpd_unregister_uri_handler(httpd_handle_t handle,
|
|
const char *uri, httpd_method_t method);
|
|
|
|
/**
|
|
* @brief Unregister all URI handlers with the specified uri string
|
|
*
|
|
* @param[in] handle handle to HTTPD server instance
|
|
* @param[in] uri uri string specifying all handlers that need
|
|
* to be deregisterd
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully deregistering all such handlers
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_NOT_FOUND : No handler registered with specified uri string
|
|
*/
|
|
esp_err_t httpd_unregister_uri(httpd_handle_t handle, const char* uri);
|
|
|
|
/** End of URI Handlers
|
|
* @}
|
|
*/
|
|
|
|
/* ************** Group: HTTP Error ************** */
|
|
/** @name HTTP Error
|
|
* Prototype for HTTP errors and error handling functions
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @brief Error codes sent as HTTP response in case of errors
|
|
* encountered during processing of an HTTP request
|
|
*/
|
|
typedef enum {
|
|
/* For any unexpected errors during parsing, like unexpected
|
|
* state transitions, or unhandled errors.
|
|
*/
|
|
HTTPD_500_INTERNAL_SERVER_ERROR = 0,
|
|
|
|
/* For methods not supported by http_parser. Presently
|
|
* http_parser halts parsing when such methods are
|
|
* encountered and so the server responds with 400 Bad
|
|
* Request error instead.
|
|
*/
|
|
HTTPD_501_METHOD_NOT_IMPLEMENTED,
|
|
|
|
/* When HTTP version is not 1.1 */
|
|
HTTPD_505_VERSION_NOT_SUPPORTED,
|
|
|
|
/* Returned when http_parser halts parsing due to incorrect
|
|
* syntax of request, unsupported method in request URI or
|
|
* due to chunked encoding / upgrade field present in headers
|
|
*/
|
|
HTTPD_400_BAD_REQUEST,
|
|
|
|
/* This response means the client must authenticate itself
|
|
* to get the requested response.
|
|
*/
|
|
HTTPD_401_UNAUTHORIZED,
|
|
|
|
/* The client does not have access rights to the content,
|
|
* so the server is refusing to give the requested resource.
|
|
* Unlike 401, the client's identity is known to the server.
|
|
*/
|
|
HTTPD_403_FORBIDDEN,
|
|
|
|
/* When requested URI is not found */
|
|
HTTPD_404_NOT_FOUND,
|
|
|
|
/* When URI found, but method has no handler registered */
|
|
HTTPD_405_METHOD_NOT_ALLOWED,
|
|
|
|
/* Intended for recv timeout. Presently it's being sent
|
|
* for other recv errors as well. Client should expect the
|
|
* server to immediately close the connection after
|
|
* responding with this.
|
|
*/
|
|
HTTPD_408_REQ_TIMEOUT,
|
|
|
|
/* Intended for responding to chunked encoding, which is
|
|
* not supported currently. Though unhandled http_parser
|
|
* callback for chunked request returns "400 Bad Request"
|
|
*/
|
|
HTTPD_411_LENGTH_REQUIRED,
|
|
|
|
/* Incoming payload is too large */
|
|
HTTPD_413_CONTENT_TOO_LARGE,
|
|
|
|
/* URI length greater than CONFIG_HTTPD_MAX_URI_LEN */
|
|
HTTPD_414_URI_TOO_LONG,
|
|
|
|
/* Headers section larger than CONFIG_HTTPD_MAX_REQ_HDR_LEN */
|
|
HTTPD_431_REQ_HDR_FIELDS_TOO_LARGE,
|
|
|
|
/* Used internally for retrieving the total count of errors */
|
|
HTTPD_ERR_CODE_MAX
|
|
} httpd_err_code_t;
|
|
|
|
/**
|
|
* @brief Function prototype for HTTP error handling.
|
|
*
|
|
* This function is executed upon HTTP errors generated during
|
|
* internal processing of an HTTP request. This is used to override
|
|
* the default behavior on error, which is to send HTTP error response
|
|
* and close the underlying socket.
|
|
*
|
|
* @note
|
|
* - If implemented, the server will not automatically send out HTTP
|
|
* error response codes, therefore, httpd_resp_send_err() must be
|
|
* invoked inside this function if user wishes to generate HTTP
|
|
* error responses.
|
|
* - When invoked, the validity of `uri`, `method`, `content_len`
|
|
* and `user_ctx` fields of the httpd_req_t parameter is not
|
|
* guaranteed as the HTTP request may be partially received/parsed.
|
|
* - The function must return ESP_OK if underlying socket needs to
|
|
* be kept open. Any other value will ensure that the socket is
|
|
* closed. The return value is ignored when error is of type
|
|
* `HTTPD_500_INTERNAL_SERVER_ERROR` and the socket closed anyway.
|
|
*
|
|
* @param[in] req HTTP request for which the error needs to be handled
|
|
* @param[in] error Error type
|
|
*
|
|
* @return
|
|
* - ESP_OK : error handled successful
|
|
* - ESP_FAIL : failure indicates that the underlying socket needs to be closed
|
|
*/
|
|
typedef esp_err_t (*httpd_err_handler_func_t)(httpd_req_t *req,
|
|
httpd_err_code_t error);
|
|
|
|
/**
|
|
* @brief Function for registering HTTP error handlers
|
|
*
|
|
* This function maps a handler function to any supported error code
|
|
* given by `httpd_err_code_t`. See prototype `httpd_err_handler_func_t`
|
|
* above for details.
|
|
*
|
|
* @param[in] handle HTTP server handle
|
|
* @param[in] error Error type
|
|
* @param[in] handler_fn User implemented handler function
|
|
* (Pass NULL to unset any previously set handler)
|
|
*
|
|
* @return
|
|
* - ESP_OK : handler registered successfully
|
|
* - ESP_ERR_INVALID_ARG : invalid error code or server handle
|
|
*/
|
|
esp_err_t httpd_register_err_handler(httpd_handle_t handle,
|
|
httpd_err_code_t error,
|
|
httpd_err_handler_func_t handler_fn);
|
|
|
|
/** End of HTTP Error
|
|
* @}
|
|
*/
|
|
|
|
/* ************** Group: TX/RX ************** */
|
|
/** @name TX / RX
|
|
* Prototype for HTTPDs low-level send/recv functions
|
|
* @{
|
|
*/
|
|
|
|
#define HTTPD_SOCK_ERR_FAIL -1
|
|
#define HTTPD_SOCK_ERR_INVALID -2
|
|
#define HTTPD_SOCK_ERR_TIMEOUT -3
|
|
|
|
/**
|
|
* @brief Prototype for HTTPDs low-level send function
|
|
*
|
|
* @note User specified send function must handle errors internally,
|
|
* depending upon the set value of errno, and return specific
|
|
* HTTPD_SOCK_ERR_ codes, which will eventually be conveyed as
|
|
* return value of httpd_send() function
|
|
*
|
|
* @param[in] hd server instance
|
|
* @param[in] sockfd session socket file descriptor
|
|
* @param[in] buf buffer with bytes to send
|
|
* @param[in] buf_len data size
|
|
* @param[in] flags flags for the send() function
|
|
* @return
|
|
* - Bytes : The number of bytes sent successfully
|
|
* - HTTPD_SOCK_ERR_INVALID : Invalid arguments
|
|
* - HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket send()
|
|
* - HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket send()
|
|
*/
|
|
typedef int (*httpd_send_func_t)(httpd_handle_t hd, int sockfd, const char *buf, size_t buf_len, int flags);
|
|
|
|
/**
|
|
* @brief Prototype for HTTPDs low-level recv function
|
|
*
|
|
* @note User specified recv function must handle errors internally,
|
|
* depending upon the set value of errno, and return specific
|
|
* HTTPD_SOCK_ERR_ codes, which will eventually be conveyed as
|
|
* return value of httpd_req_recv() function
|
|
*
|
|
* @param[in] hd server instance
|
|
* @param[in] sockfd session socket file descriptor
|
|
* @param[in] buf buffer with bytes to send
|
|
* @param[in] buf_len data size
|
|
* @param[in] flags flags for the send() function
|
|
* @return
|
|
* - Bytes : The number of bytes received successfully
|
|
* - 0 : Buffer length parameter is zero / connection closed by peer
|
|
* - HTTPD_SOCK_ERR_INVALID : Invalid arguments
|
|
* - HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket recv()
|
|
* - HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket recv()
|
|
*/
|
|
typedef int (*httpd_recv_func_t)(httpd_handle_t hd, int sockfd, char *buf, size_t buf_len, int flags);
|
|
|
|
/**
|
|
* @brief Prototype for HTTPDs low-level "get pending bytes" function
|
|
*
|
|
* @note User specified pending function must handle errors internally,
|
|
* depending upon the set value of errno, and return specific
|
|
* HTTPD_SOCK_ERR_ codes, which will be handled accordingly in
|
|
* the server task.
|
|
*
|
|
* @param[in] hd server instance
|
|
* @param[in] sockfd session socket file descriptor
|
|
* @return
|
|
* - Bytes : The number of bytes waiting to be received
|
|
* - HTTPD_SOCK_ERR_INVALID : Invalid arguments
|
|
* - HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket pending()
|
|
* - HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket pending()
|
|
*/
|
|
typedef int (*httpd_pending_func_t)(httpd_handle_t hd, int sockfd);
|
|
|
|
/** End of TX / RX
|
|
* @}
|
|
*/
|
|
|
|
/* ************** Group: Request/Response ************** */
|
|
/** @name Request / Response
|
|
* APIs related to the data send/receive by URI handlers.
|
|
* These APIs are supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @brief Override web server's receive function (by session FD)
|
|
*
|
|
* This function overrides the web server's receive function. This same function is
|
|
* used to read HTTP request packets.
|
|
*
|
|
* @note This API is supposed to be called either from the context of
|
|
* - an http session APIs where sockfd is a valid parameter
|
|
* - a URI handler where sockfd is obtained using httpd_req_to_sockfd()
|
|
*
|
|
* @param[in] hd HTTPD instance handle
|
|
* @param[in] sockfd Session socket FD
|
|
* @param[in] recv_func The receive function to be set for this session
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully registering override
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
*/
|
|
esp_err_t httpd_sess_set_recv_override(httpd_handle_t hd, int sockfd, httpd_recv_func_t recv_func);
|
|
|
|
/**
|
|
* @brief Override web server's send function (by session FD)
|
|
*
|
|
* This function overrides the web server's send function. This same function is
|
|
* used to send out any response to any HTTP request.
|
|
*
|
|
* @note This API is supposed to be called either from the context of
|
|
* - an http session APIs where sockfd is a valid parameter
|
|
* - a URI handler where sockfd is obtained using httpd_req_to_sockfd()
|
|
*
|
|
* @param[in] hd HTTPD instance handle
|
|
* @param[in] sockfd Session socket FD
|
|
* @param[in] send_func The send function to be set for this session
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully registering override
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
*/
|
|
esp_err_t httpd_sess_set_send_override(httpd_handle_t hd, int sockfd, httpd_send_func_t send_func);
|
|
|
|
/**
|
|
* @brief Override web server's pending function (by session FD)
|
|
*
|
|
* This function overrides the web server's pending function. This function is
|
|
* used to test for pending bytes in a socket.
|
|
*
|
|
* @note This API is supposed to be called either from the context of
|
|
* - an http session APIs where sockfd is a valid parameter
|
|
* - a URI handler where sockfd is obtained using httpd_req_to_sockfd()
|
|
*
|
|
* @param[in] hd HTTPD instance handle
|
|
* @param[in] sockfd Session socket FD
|
|
* @param[in] pending_func The receive function to be set for this session
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully registering override
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
*/
|
|
esp_err_t httpd_sess_set_pending_override(httpd_handle_t hd, int sockfd, httpd_pending_func_t pending_func);
|
|
|
|
/**
|
|
* @brief Start an asynchronous request. This function can be called
|
|
* in a request handler to get a request copy that can be used on a async thread.
|
|
*
|
|
* @note
|
|
* - This function is necessary in order to handle multiple requests simultaneously.
|
|
* See examples/async_requests for example usage.
|
|
* - You must call httpd_req_async_handler_complete() when you are done with the request.
|
|
*
|
|
* @param[in] r The request to create an async copy of
|
|
* @param[out] out A newly allocated request which can be used on an async thread
|
|
*
|
|
* @return
|
|
* - ESP_OK : async request object created
|
|
*/
|
|
esp_err_t httpd_req_async_handler_begin(httpd_req_t *r, httpd_req_t **out);
|
|
|
|
/**
|
|
* @brief Mark an asynchronous request as completed. This will
|
|
* - free the request memory
|
|
* - relinquish ownership of the underlying socket, so it can be reused.
|
|
* - allow the http server to close our socket if needed (lru_purge_enable)
|
|
*
|
|
* @note If async requests are not marked completed, eventually the server
|
|
* will no longer accept incoming connections. The server will log a
|
|
* "httpd_accept_conn: error in accept (23)" message if this happens.
|
|
*
|
|
* @param[in] r The request to mark async work as completed
|
|
*
|
|
* @return
|
|
* - ESP_OK : async request was marked completed
|
|
*/
|
|
esp_err_t httpd_req_async_handler_complete(httpd_req_t *r);
|
|
|
|
/**
|
|
* @brief Get the Socket Descriptor from the HTTP request
|
|
*
|
|
* This API will return the socket descriptor of the session for
|
|
* which URI handler was executed on reception of HTTP request.
|
|
* This is useful when user wants to call functions that require
|
|
* session socket fd, from within a URI handler, ie. :
|
|
* httpd_sess_get_ctx(),
|
|
* httpd_sess_trigger_close(),
|
|
* httpd_sess_update_lru_counter().
|
|
*
|
|
* @note This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
*
|
|
* @param[in] r The request whose socket descriptor should be found
|
|
*
|
|
* @return
|
|
* - Socket descriptor : The socket descriptor for this request
|
|
* - -1 : Invalid/NULL request pointer
|
|
*/
|
|
int httpd_req_to_sockfd(httpd_req_t *r);
|
|
|
|
/**
|
|
* @brief API to read content data from the HTTP request
|
|
*
|
|
* This API will read HTTP content data from the HTTP request into
|
|
* provided buffer. Use content_len provided in httpd_req_t structure
|
|
* to know the length of data to be fetched. If content_len is too
|
|
* large for the buffer then user may have to make multiple calls to
|
|
* this function, each time fetching 'buf_len' number of bytes,
|
|
* while the pointer to content data is incremented internally by
|
|
* the same number.
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - If an error is returned, the URI handler must further return an error.
|
|
* This will ensure that the erroneous socket is closed and cleaned up by
|
|
* the web server.
|
|
* - Presently Chunked Encoding is not supported
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] buf Pointer to a buffer that the data will be read into
|
|
* @param[in] buf_len Length of the buffer
|
|
*
|
|
* @return
|
|
* - Bytes : Number of bytes read into the buffer successfully
|
|
* - 0 : Buffer length parameter is zero / connection closed by peer
|
|
* - HTTPD_SOCK_ERR_INVALID : Invalid arguments
|
|
* - HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket recv()
|
|
* - HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket recv()
|
|
*/
|
|
int httpd_req_recv(httpd_req_t *r, char *buf, size_t buf_len);
|
|
|
|
/**
|
|
* @brief Search for a field in request headers and
|
|
* return the string length of it's value
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - Once httpd_resp_send() API is called all request headers
|
|
* are purged, so request headers need be copied into separate
|
|
* buffers if they are required later.
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] field The header field to be searched in the request
|
|
*
|
|
* @return
|
|
* - Length : If field is found in the request URL
|
|
* - Zero : Field not found / Invalid request / Null arguments
|
|
*/
|
|
size_t httpd_req_get_hdr_value_len(httpd_req_t *r, const char *field);
|
|
|
|
/**
|
|
* @brief Get the value string of a field from the request headers
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - Once httpd_resp_send() API is called all request headers
|
|
* are purged, so request headers need be copied into separate
|
|
* buffers if they are required later.
|
|
* - If output size is greater than input, then the value is truncated,
|
|
* accompanied by truncation error as return value.
|
|
* - Use httpd_req_get_hdr_value_len() to know the right buffer length
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] field The field to be searched in the header
|
|
* @param[out] val Pointer to the buffer into which the value will be copied if the field is found
|
|
* @param[in] val_size Size of the user buffer "val"
|
|
*
|
|
* @return
|
|
* - ESP_OK : Field found in the request header and value string copied
|
|
* - ESP_ERR_NOT_FOUND : Key not found
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid HTTP request pointer
|
|
* - ESP_ERR_HTTPD_RESULT_TRUNC : Value string truncated
|
|
*/
|
|
esp_err_t httpd_req_get_hdr_value_str(httpd_req_t *r, const char *field, char *val, size_t val_size);
|
|
|
|
/**
|
|
* @brief Get Query string length from the request URL
|
|
*
|
|
* @note This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid
|
|
*
|
|
* @param[in] r The request being responded to
|
|
*
|
|
* @return
|
|
* - Length : Query is found in the request URL
|
|
* - Zero : Query not found / Null arguments / Invalid request
|
|
*/
|
|
size_t httpd_req_get_url_query_len(httpd_req_t *r);
|
|
|
|
/**
|
|
* @brief Get Query string from the request URL
|
|
*
|
|
* @note
|
|
* - Presently, the user can fetch the full URL query string, but decoding
|
|
* will have to be performed by the user. Request headers can be read using
|
|
* httpd_req_get_hdr_value_str() to know the 'Content-Type' (eg. Content-Type:
|
|
* application/x-www-form-urlencoded) and then the appropriate decoding
|
|
* algorithm needs to be applied.
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid
|
|
* - If output size is greater than input, then the value is truncated,
|
|
* accompanied by truncation error as return value
|
|
* - Prior to calling this function, one can use httpd_req_get_url_query_len()
|
|
* to know the query string length beforehand and hence allocate the buffer
|
|
* of right size (usually query string length + 1 for null termination)
|
|
* for storing the query string
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[out] buf Pointer to the buffer into which the query string will be copied (if found)
|
|
* @param[in] buf_len Length of output buffer
|
|
*
|
|
* @return
|
|
* - ESP_OK : Query is found in the request URL and copied to buffer
|
|
* - ESP_ERR_NOT_FOUND : Query not found
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid HTTP request pointer
|
|
* - ESP_ERR_HTTPD_RESULT_TRUNC : Query string truncated
|
|
*/
|
|
esp_err_t httpd_req_get_url_query_str(httpd_req_t *r, char *buf, size_t buf_len);
|
|
|
|
/**
|
|
* @brief Helper function to get a URL query tag from a query
|
|
* string of the type param1=val1¶m2=val2
|
|
*
|
|
* @note
|
|
* - The components of URL query string (keys and values) are not URLdecoded.
|
|
* The user must check for 'Content-Type' field in the request headers and
|
|
* then depending upon the specified encoding (URLencoded or otherwise) apply
|
|
* the appropriate decoding algorithm.
|
|
* - If actual value size is greater than val_size, then the value is truncated,
|
|
* accompanied by truncation error as return value.
|
|
*
|
|
* @param[in] qry Pointer to query string
|
|
* @param[in] key The key to be searched in the query string
|
|
* @param[out] val Pointer to the buffer into which the value will be copied if the key is found
|
|
* @param[in] val_size Size of the user buffer "val"
|
|
*
|
|
* @return
|
|
* - ESP_OK : Key is found in the URL query string and copied to buffer
|
|
* - ESP_ERR_NOT_FOUND : Key not found
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_RESULT_TRUNC : Value string truncated
|
|
*/
|
|
esp_err_t httpd_query_key_value(const char *qry, const char *key, char *val, size_t val_size);
|
|
|
|
/**
|
|
* @brief Get the value string of a cookie value from the "Cookie" request headers by cookie name.
|
|
*
|
|
* @param[in] req Pointer to the HTTP request
|
|
* @param[in] cookie_name The cookie name to be searched in the request
|
|
* @param[out] val Pointer to the buffer into which the value of cookie will be copied if the cookie is found
|
|
* @param[inout] val_size Pointer to size of the user buffer "val". This variable will contain cookie length if
|
|
* ESP_OK is returned and required buffer length in case ESP_ERR_HTTPD_RESULT_TRUNC is returned.
|
|
*
|
|
* @return
|
|
* - ESP_OK : Key is found in the cookie string and copied to buffer
|
|
* - ESP_ERR_NOT_FOUND : Key not found
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_RESULT_TRUNC : Value string truncated
|
|
* - ESP_ERR_NO_MEM : Memory allocation failure
|
|
*/
|
|
esp_err_t httpd_req_get_cookie_val(httpd_req_t *req, const char *cookie_name, char *val, size_t *val_size);
|
|
|
|
/**
|
|
* @brief Test if a URI matches the given wildcard template.
|
|
*
|
|
* Template may end with '?' to make the previous character optional (typically a slash),
|
|
* '*' for a wildcard match, and '?*' to make the previous character optional, and if present,
|
|
* allow anything to follow.
|
|
*
|
|
* Example:
|
|
* - * matches everything
|
|
* - /api/? matches /api and /api/
|
|
* - /api/\* (sans the backslash) matches /api/ and /api/status, but not /api or /ap
|
|
* - /api/?* or /api/\*? (sans the backslash) matches /api/, /api/status, and also /api, but not /apix or /ap
|
|
*
|
|
* The special characters '?' and '*' anywhere else in the template will be taken literally.
|
|
*
|
|
* @param[in] uri_template URI template (pattern)
|
|
* @param[in] uri_to_match URI to be matched
|
|
* @param[in] match_upto how many characters of the URI buffer to test
|
|
* (there may be trailing query string etc.)
|
|
*
|
|
* @return true if a match was found
|
|
*/
|
|
bool httpd_uri_match_wildcard(const char *uri_template, const char *uri_to_match, size_t match_upto);
|
|
|
|
/**
|
|
* @brief API to send a complete HTTP response.
|
|
*
|
|
* This API will send the data as an HTTP response to the request.
|
|
* This assumes that you have the entire response ready in a single
|
|
* buffer. If you wish to send response in incremental chunks use
|
|
* httpd_resp_send_chunk() instead.
|
|
*
|
|
* If no status code and content-type were set, by default this
|
|
* will send 200 OK status code and content type as text/html.
|
|
* You may call the following functions before this API to configure
|
|
* the response headers :
|
|
* httpd_resp_set_status() - for setting the HTTP status string,
|
|
* httpd_resp_set_type() - for setting the Content Type,
|
|
* httpd_resp_set_hdr() - for appending any additional field
|
|
* value entries in the response header
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - Once this API is called, the request has been responded to.
|
|
* - No additional data can then be sent for the request.
|
|
* - Once this API is called, all request headers are purged, so
|
|
* request headers need be copied into separate buffers if
|
|
* they are required later.
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] buf Buffer from where the content is to be fetched
|
|
* @param[in] buf_len Length of the buffer, HTTPD_RESP_USE_STRLEN to use strlen()
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully sending the response packet
|
|
* - ESP_ERR_INVALID_ARG : Null request pointer
|
|
* - ESP_ERR_HTTPD_RESP_HDR : Essential headers are too large for internal buffer
|
|
* - ESP_ERR_HTTPD_RESP_SEND : Error in raw send
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request
|
|
*/
|
|
esp_err_t httpd_resp_send(httpd_req_t *r, const char *buf, ssize_t buf_len);
|
|
|
|
/**
|
|
* @brief API to send one HTTP chunk
|
|
*
|
|
* This API will send the data as an HTTP response to the
|
|
* request. This API will use chunked-encoding and send the response
|
|
* in the form of chunks. If you have the entire response contained in
|
|
* a single buffer, please use httpd_resp_send() instead.
|
|
*
|
|
* If no status code and content-type were set, by default this will
|
|
* send 200 OK status code and content type as text/html. You may
|
|
* call the following functions before this API to configure the
|
|
* response headers
|
|
* httpd_resp_set_status() - for setting the HTTP status string,
|
|
* httpd_resp_set_type() - for setting the Content Type,
|
|
* httpd_resp_set_hdr() - for appending any additional field
|
|
* value entries in the response header
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - When you are finished sending all your chunks, you must call
|
|
* this function with buf_len as 0.
|
|
* - Once this API is called, all request headers are purged, so
|
|
* request headers need be copied into separate buffers if they
|
|
* are required later.
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] buf Pointer to a buffer that stores the data
|
|
* @param[in] buf_len Length of the buffer, HTTPD_RESP_USE_STRLEN to use strlen()
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully sending the response packet chunk
|
|
* - ESP_ERR_INVALID_ARG : Null request pointer
|
|
* - ESP_ERR_HTTPD_RESP_HDR : Essential headers are too large for internal buffer
|
|
* - ESP_ERR_HTTPD_RESP_SEND : Error in raw send
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
|
|
*/
|
|
esp_err_t httpd_resp_send_chunk(httpd_req_t *r, const char *buf, ssize_t buf_len);
|
|
|
|
/**
|
|
* @brief API to send a complete string as HTTP response.
|
|
*
|
|
* This API simply calls http_resp_send with buffer length
|
|
* set to string length assuming the buffer contains a null
|
|
* terminated string
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] str String to be sent as response body
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully sending the response packet
|
|
* - ESP_ERR_INVALID_ARG : Null request pointer
|
|
* - ESP_ERR_HTTPD_RESP_HDR : Essential headers are too large for internal buffer
|
|
* - ESP_ERR_HTTPD_RESP_SEND : Error in raw send
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request
|
|
*/
|
|
static inline esp_err_t httpd_resp_sendstr(httpd_req_t *r, const char *str) {
|
|
return httpd_resp_send(r, str, (str == NULL) ? 0 : HTTPD_RESP_USE_STRLEN);
|
|
}
|
|
|
|
/**
|
|
* @brief API to send a string as an HTTP response chunk.
|
|
*
|
|
* This API simply calls http_resp_send_chunk with buffer length
|
|
* set to string length assuming the buffer contains a null
|
|
* terminated string
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] str String to be sent as response body (NULL to finish response packet)
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully sending the response packet
|
|
* - ESP_ERR_INVALID_ARG : Null request pointer
|
|
* - ESP_ERR_HTTPD_RESP_HDR : Essential headers are too large for internal buffer
|
|
* - ESP_ERR_HTTPD_RESP_SEND : Error in raw send
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request
|
|
*/
|
|
static inline esp_err_t httpd_resp_sendstr_chunk(httpd_req_t *r, const char *str) {
|
|
return httpd_resp_send_chunk(r, str, (str == NULL) ? 0 : HTTPD_RESP_USE_STRLEN);
|
|
}
|
|
|
|
/* Some commonly used status codes */
|
|
#define HTTPD_200 "200 OK" /*!< HTTP Response 200 */
|
|
#define HTTPD_204 "204 No Content" /*!< HTTP Response 204 */
|
|
#define HTTPD_207 "207 Multi-Status" /*!< HTTP Response 207 */
|
|
#define HTTPD_400 "400 Bad Request" /*!< HTTP Response 400 */
|
|
#define HTTPD_404 "404 Not Found" /*!< HTTP Response 404 */
|
|
#define HTTPD_408 "408 Request Timeout" /*!< HTTP Response 408 */
|
|
#define HTTPD_500 "500 Internal Server Error" /*!< HTTP Response 500 */
|
|
|
|
/**
|
|
* @brief API to set the HTTP status code
|
|
*
|
|
* This API sets the status of the HTTP response to the value specified.
|
|
* By default, the '200 OK' response is sent as the response.
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - This API only sets the status to this value. The status isn't
|
|
* sent out until any of the send APIs is executed.
|
|
* - Make sure that the lifetime of the status string is valid till
|
|
* send function is called.
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] status The HTTP status code of this response
|
|
*
|
|
* @return
|
|
* - ESP_OK : On success
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
|
|
*/
|
|
esp_err_t httpd_resp_set_status(httpd_req_t *r, const char *status);
|
|
|
|
/* Some commonly used content types */
|
|
#define HTTPD_TYPE_JSON "application/json" /*!< HTTP Content type JSON */
|
|
#define HTTPD_TYPE_TEXT "text/html" /*!< HTTP Content type text/HTML */
|
|
#define HTTPD_TYPE_OCTET "application/octet-stream" /*!< HTTP Content type octext-stream */
|
|
|
|
/**
|
|
* @brief API to set the HTTP content type
|
|
*
|
|
* This API sets the 'Content Type' field of the response.
|
|
* The default content type is 'text/html'.
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - This API only sets the content type to this value. The type
|
|
* isn't sent out until any of the send APIs is executed.
|
|
* - Make sure that the lifetime of the type string is valid till
|
|
* send function is called.
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] type The Content Type of the response
|
|
*
|
|
* @return
|
|
* - ESP_OK : On success
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
|
|
*/
|
|
esp_err_t httpd_resp_set_type(httpd_req_t *r, const char *type);
|
|
|
|
/**
|
|
* @brief API to append any additional headers
|
|
*
|
|
* This API sets any additional header fields that need to be sent in the response.
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - The header isn't sent out until any of the send APIs is executed.
|
|
* - The maximum allowed number of additional headers is limited to
|
|
* value of max_resp_headers in config structure.
|
|
* - Make sure that the lifetime of the field value strings are valid till
|
|
* send function is called.
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] field The field name of the HTTP header
|
|
* @param[in] value The value of this HTTP header
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully appending new header
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_RESP_HDR : Total additional headers exceed max allowed
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
|
|
*/
|
|
esp_err_t httpd_resp_set_hdr(httpd_req_t *r, const char *field, const char *value);
|
|
|
|
/**
|
|
* @brief For sending out error code in response to HTTP request.
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - Once this API is called, all request headers are purged, so
|
|
* request headers need be copied into separate buffers if
|
|
* they are required later.
|
|
* - If you wish to send additional data in the body of the
|
|
* response, please use the lower-level functions directly.
|
|
*
|
|
* @param[in] req Pointer to the HTTP request for which the response needs to be sent
|
|
* @param[in] error Error type to send
|
|
* @param[in] msg Error message string (pass NULL for default message)
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully sending the response packet
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_RESP_SEND : Error in raw send
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
|
|
*/
|
|
esp_err_t httpd_resp_send_err(httpd_req_t *req, httpd_err_code_t error, const char *msg);
|
|
|
|
/**
|
|
* @brief For sending out custom error code in response to HTTP request.
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - Once this API is called, all request headers are purged, so
|
|
* request headers need be copied into separate buffers if
|
|
* they are required later.
|
|
* - If you wish to send additional data in the body of the
|
|
* response, please use the lower-level functions directly.
|
|
*
|
|
* @param[in] req Pointer to the HTTP request for which the response needs to be sent
|
|
* @param[in] status Error status to send
|
|
* @param[in] msg Error message string
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully sending the response packet
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_RESP_SEND : Error in raw send
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
|
|
*/
|
|
esp_err_t httpd_resp_send_custom_err(httpd_req_t *req, const char *status, const char *msg);
|
|
|
|
/**
|
|
* @brief Helper function for HTTP 404
|
|
*
|
|
* Send HTTP 404 message. If you wish to send additional data in the body of the
|
|
* response, please use the lower-level functions directly.
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - Once this API is called, all request headers are purged, so
|
|
* request headers need be copied into separate buffers if
|
|
* they are required later.
|
|
*
|
|
* @param[in] r The request being responded to
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully sending the response packet
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_RESP_SEND : Error in raw send
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
|
|
*/
|
|
static inline esp_err_t httpd_resp_send_404(httpd_req_t *r) {
|
|
return httpd_resp_send_err(r, HTTPD_404_NOT_FOUND, NULL);
|
|
}
|
|
|
|
/**
|
|
* @brief Helper function for HTTP 408
|
|
*
|
|
* Send HTTP 408 message. If you wish to send additional data in the body of the
|
|
* response, please use the lower-level functions directly.
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - Once this API is called, all request headers are purged, so
|
|
* request headers need be copied into separate buffers if
|
|
* they are required later.
|
|
*
|
|
* @param[in] r The request being responded to
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully sending the response packet
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_RESP_SEND : Error in raw send
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
|
|
*/
|
|
static inline esp_err_t httpd_resp_send_408(httpd_req_t *r) {
|
|
return httpd_resp_send_err(r, HTTPD_408_REQ_TIMEOUT, NULL);
|
|
}
|
|
|
|
/**
|
|
* @brief Helper function for HTTP 500
|
|
*
|
|
* Send HTTP 500 message. If you wish to send additional data in the body of the
|
|
* response, please use the lower-level functions directly.
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - Once this API is called, all request headers are purged, so
|
|
* request headers need be copied into separate buffers if
|
|
* they are required later.
|
|
*
|
|
* @param[in] r The request being responded to
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully sending the response packet
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
* - ESP_ERR_HTTPD_RESP_SEND : Error in raw send
|
|
* - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer
|
|
*/
|
|
static inline esp_err_t httpd_resp_send_500(httpd_req_t *r) {
|
|
return httpd_resp_send_err(r, HTTPD_500_INTERNAL_SERVER_ERROR, NULL);
|
|
}
|
|
|
|
/**
|
|
* @brief Raw HTTP send
|
|
*
|
|
* Call this API if you wish to construct your custom response packet.
|
|
* When using this, all essential header, eg. HTTP version, Status Code,
|
|
* Content Type and Length, Encoding, etc. will have to be constructed
|
|
* manually, and HTTP delimiters (CRLF) will need to be placed correctly
|
|
* for separating sub-sections of the HTTP response packet.
|
|
*
|
|
* If the send override function is set, this API will end up
|
|
* calling that function eventually to send data out.
|
|
*
|
|
* @note
|
|
* - This API is supposed to be called only from the context of
|
|
* a URI handler where httpd_req_t* request pointer is valid.
|
|
* - Unless the response has the correct HTTP structure (which the
|
|
* user must now ensure) it is not guaranteed that it will be
|
|
* recognized by the client. For most cases, you wouldn't have
|
|
* to call this API, but you would rather use either of :
|
|
* httpd_resp_send(),
|
|
* httpd_resp_send_chunk()
|
|
*
|
|
* @param[in] r The request being responded to
|
|
* @param[in] buf Buffer from where the fully constructed packet is to be read
|
|
* @param[in] buf_len Length of the buffer
|
|
*
|
|
* @return
|
|
* - Bytes : Number of bytes that were sent successfully
|
|
* - HTTPD_SOCK_ERR_INVALID : Invalid arguments
|
|
* - HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket send()
|
|
* - HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket send()
|
|
*/
|
|
int httpd_send(httpd_req_t *r, const char *buf, size_t buf_len);
|
|
|
|
/**
|
|
* A low level API to send data on a given socket
|
|
*
|
|
* @note This API is not recommended to be used in any request handler.
|
|
* Use this only for advanced use cases, wherein some asynchronous
|
|
* data is to be sent over a socket.
|
|
*
|
|
* This internally calls the default send function, or the function registered by
|
|
* httpd_sess_set_send_override().
|
|
*
|
|
* @param[in] hd server instance
|
|
* @param[in] sockfd session socket file descriptor
|
|
* @param[in] buf buffer with bytes to send
|
|
* @param[in] buf_len data size
|
|
* @param[in] flags flags for the send() function
|
|
* @return
|
|
* - Bytes : The number of bytes sent successfully
|
|
* - HTTPD_SOCK_ERR_INVALID : Invalid arguments
|
|
* - HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket send()
|
|
* - HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket send()
|
|
*/
|
|
int httpd_socket_send(httpd_handle_t hd, int sockfd, const char *buf, size_t buf_len, int flags);
|
|
|
|
/**
|
|
* A low level API to receive data from a given socket
|
|
*
|
|
* @note This API is not recommended to be used in any request handler.
|
|
* Use this only for advanced use cases, wherein some asynchronous
|
|
* communication is required.
|
|
*
|
|
* This internally calls the default recv function, or the function registered by
|
|
* httpd_sess_set_recv_override().
|
|
*
|
|
* @param[in] hd server instance
|
|
* @param[in] sockfd session socket file descriptor
|
|
* @param[in] buf buffer with bytes to send
|
|
* @param[in] buf_len data size
|
|
* @param[in] flags flags for the send() function
|
|
* @return
|
|
* - Bytes : The number of bytes received successfully
|
|
* - 0 : Buffer length parameter is zero / connection closed by peer
|
|
* - HTTPD_SOCK_ERR_INVALID : Invalid arguments
|
|
* - HTTPD_SOCK_ERR_TIMEOUT : Timeout/interrupted while calling socket recv()
|
|
* - HTTPD_SOCK_ERR_FAIL : Unrecoverable error while calling socket recv()
|
|
*/
|
|
int httpd_socket_recv(httpd_handle_t hd, int sockfd, char *buf, size_t buf_len, int flags);
|
|
|
|
/** End of Request / Response
|
|
* @}
|
|
*/
|
|
|
|
/* ************** Group: Session ************** */
|
|
/** @name Session
|
|
* Functions for controlling sessions and accessing context data
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @brief Get session context from socket descriptor
|
|
*
|
|
* Typically if a session context is created, it is available to URI handlers
|
|
* through the httpd_req_t structure. But, there are cases where the web
|
|
* server's send/receive functions may require the context (for example, for
|
|
* accessing keying information etc). Since the send/receive function only have
|
|
* the socket descriptor at their disposal, this API provides them with a way to
|
|
* retrieve the session context.
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @param[in] sockfd The socket descriptor for which the context should be extracted.
|
|
*
|
|
* @return
|
|
* - void* : Pointer to the context associated with this session
|
|
* - NULL : Empty context / Invalid handle / Invalid socket fd
|
|
*/
|
|
void *httpd_sess_get_ctx(httpd_handle_t handle, int sockfd);
|
|
|
|
/**
|
|
* @brief Set session context by socket descriptor
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @param[in] sockfd The socket descriptor for which the context should be extracted.
|
|
* @param[in] ctx Context object to assign to the session
|
|
* @param[in] free_fn Function that should be called to free the context
|
|
*/
|
|
void httpd_sess_set_ctx(httpd_handle_t handle, int sockfd, void *ctx, httpd_free_ctx_fn_t free_fn);
|
|
|
|
/**
|
|
* @brief Get session 'transport' context by socket descriptor
|
|
* @see httpd_sess_get_ctx()
|
|
*
|
|
* This context is used by the send/receive functions, for example to manage SSL context.
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @param[in] sockfd The socket descriptor for which the context should be extracted.
|
|
* @return
|
|
* - void* : Pointer to the transport context associated with this session
|
|
* - NULL : Empty context / Invalid handle / Invalid socket fd
|
|
*/
|
|
void *httpd_sess_get_transport_ctx(httpd_handle_t handle, int sockfd);
|
|
|
|
/**
|
|
* @brief Set session 'transport' context by socket descriptor
|
|
* @see httpd_sess_set_ctx()
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @param[in] sockfd The socket descriptor for which the context should be extracted.
|
|
* @param[in] ctx Transport context object to assign to the session
|
|
* @param[in] free_fn Function that should be called to free the transport context
|
|
*/
|
|
void httpd_sess_set_transport_ctx(httpd_handle_t handle, int sockfd, void *ctx, httpd_free_ctx_fn_t free_fn);
|
|
|
|
/**
|
|
* @brief Get HTTPD global user context (it was set in the server config struct)
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @return global user context
|
|
*/
|
|
void *httpd_get_global_user_ctx(httpd_handle_t handle);
|
|
|
|
/**
|
|
* @brief Get HTTPD global transport context (it was set in the server config struct)
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @return global transport context
|
|
*/
|
|
void *httpd_get_global_transport_ctx(httpd_handle_t handle);
|
|
|
|
/**
|
|
* @brief Trigger an httpd session close externally
|
|
*
|
|
* @note Calling this API is only required in special circumstances wherein
|
|
* some application requires to close an httpd client session asynchronously.
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @param[in] sockfd The socket descriptor of the session to be closed
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully initiating closure
|
|
* - ESP_FAIL : Failure to queue work
|
|
* - ESP_ERR_NOT_FOUND : Socket fd not found
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
*/
|
|
esp_err_t httpd_sess_trigger_close(httpd_handle_t handle, int sockfd);
|
|
|
|
/**
|
|
* @brief Update LRU counter for a given socket
|
|
*
|
|
* LRU Counters are internally associated with each session to monitor
|
|
* how recently a session exchanged traffic. When LRU purge is enabled,
|
|
* if a client is requesting for connection but maximum number of
|
|
* sockets/sessions is reached, then the session having the earliest
|
|
* LRU counter is closed automatically.
|
|
*
|
|
* Updating the LRU counter manually prevents the socket from being purged
|
|
* due to the Least Recently Used (LRU) logic, even though it might not
|
|
* have received traffic for some time. This is useful when all open
|
|
* sockets/session are frequently exchanging traffic but the user specifically
|
|
* wants one of the sessions to be kept open, irrespective of when it last
|
|
* exchanged a packet.
|
|
*
|
|
* @note Calling this API is only necessary if the LRU Purge Enable option
|
|
* is enabled.
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @param[in] sockfd The socket descriptor of the session for which LRU counter
|
|
* is to be updated
|
|
*
|
|
* @return
|
|
* - ESP_OK : Socket found and LRU counter updated
|
|
* - ESP_ERR_NOT_FOUND : Socket not found
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
*/
|
|
esp_err_t httpd_sess_update_lru_counter(httpd_handle_t handle, int sockfd);
|
|
|
|
/**
|
|
* @brief Returns list of current socket descriptors of active sessions
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @param[in,out] fds In: Size of provided client_fds array
|
|
* Out: Number of valid client fds returned in client_fds,
|
|
* @param[out] client_fds Array of client fds
|
|
*
|
|
* @note Size of provided array has to be equal or greater then maximum number of opened
|
|
* sockets, configured upon initialization with max_open_sockets field in
|
|
* httpd_config_t structure.
|
|
*
|
|
* @return
|
|
* - ESP_OK : Successfully retrieved session list
|
|
* - ESP_ERR_INVALID_ARG : Wrong arguments or list is longer than provided array
|
|
*/
|
|
esp_err_t httpd_get_client_list(httpd_handle_t handle, size_t *fds, int *client_fds);
|
|
|
|
/** End of Session
|
|
* @}
|
|
*/
|
|
|
|
/* ************** Group: Work Queue ************** */
|
|
/** @name Work Queue
|
|
* APIs related to the HTTPD Work Queue
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @brief Prototype of the HTTPD work function
|
|
* Please refer to httpd_queue_work() for more details.
|
|
* @param[in] arg The arguments for this work function
|
|
*/
|
|
typedef void (*httpd_work_fn_t)(void *arg);
|
|
|
|
/**
|
|
* @brief Queue execution of a function in HTTPD's context
|
|
*
|
|
* This API queues a work function for asynchronous execution
|
|
*
|
|
* @note Some protocols require that the web server generate some asynchronous data
|
|
* and send it to the persistently opened connection. This facility is for use
|
|
* by such protocols.
|
|
*
|
|
* @param[in] handle Handle to server returned by httpd_start
|
|
* @param[in] work Pointer to the function to be executed in the HTTPD's context
|
|
* @param[in] arg Pointer to the arguments that should be passed to this function
|
|
*
|
|
* @return
|
|
* - ESP_OK : On successfully queueing the work
|
|
* - ESP_FAIL : Failure in ctrl socket
|
|
* - ESP_ERR_INVALID_ARG : Null arguments
|
|
*/
|
|
esp_err_t httpd_queue_work(httpd_handle_t handle, httpd_work_fn_t work, void *arg);
|
|
|
|
/** End of Group Work Queue
|
|
* @}
|
|
*/
|
|
|
|
/* ************** Group: WebSocket ************** */
|
|
/** @name WebSocket
|
|
* Functions and structs for WebSocket server
|
|
* @{
|
|
*/
|
|
#ifdef CONFIG_HTTPD_WS_SUPPORT
|
|
/**
|
|
* @brief Enum for WebSocket packet types (Opcode in the header)
|
|
* @note Please refer to RFC6455 Section 5.4 for more details
|
|
*/
|
|
typedef enum {
|
|
HTTPD_WS_TYPE_CONTINUE = 0x0,
|
|
HTTPD_WS_TYPE_TEXT = 0x1,
|
|
HTTPD_WS_TYPE_BINARY = 0x2,
|
|
HTTPD_WS_TYPE_CLOSE = 0x8,
|
|
HTTPD_WS_TYPE_PING = 0x9,
|
|
HTTPD_WS_TYPE_PONG = 0xA
|
|
} httpd_ws_type_t;
|
|
|
|
/**
|
|
* @brief Enum for client info description
|
|
*/
|
|
typedef enum {
|
|
HTTPD_WS_CLIENT_INVALID = 0x0,
|
|
HTTPD_WS_CLIENT_HTTP = 0x1,
|
|
HTTPD_WS_CLIENT_WEBSOCKET = 0x2,
|
|
} httpd_ws_client_info_t;
|
|
|
|
/**
|
|
* @brief WebSocket frame format
|
|
*/
|
|
typedef struct httpd_ws_frame {
|
|
bool final; /*!< Final frame:
|
|
For received frames this field indicates whether the `FIN` flag was set.
|
|
For frames to be transmitted, this field is only used if the `fragmented`
|
|
option is set as well. If `fragmented` is false, the `FIN` flag is set
|
|
by default, marking the ws_frame as a complete/unfragmented message
|
|
(esp_http_server doesn't automatically fragment messages) */
|
|
bool fragmented; /*!< Indication that the frame allocated for transmission is a message fragment,
|
|
so the `FIN` flag is set manually according to the `final` option.
|
|
This flag is never set for received messages */
|
|
httpd_ws_type_t type; /*!< WebSocket frame type */
|
|
uint8_t *payload; /*!< Pre-allocated data buffer */
|
|
size_t len; /*!< Length of the WebSocket data */
|
|
} httpd_ws_frame_t;
|
|
|
|
/**
|
|
* @brief Transfer complete callback
|
|
*/
|
|
typedef void (*transfer_complete_cb)(esp_err_t err, int socket, void *arg);
|
|
|
|
/**
|
|
* @brief Receive and parse a WebSocket frame
|
|
*
|
|
* @note Calling httpd_ws_recv_frame() with max_len as 0 will give actual frame size in pkt->len.
|
|
* The user can dynamically allocate space for pkt->payload as per this length and call httpd_ws_recv_frame() again to get the actual data.
|
|
* Please refer to the corresponding example for usage.
|
|
*
|
|
* @param[in] req Current request
|
|
* @param[out] pkt WebSocket packet
|
|
* @param[in] max_len Maximum length for receive
|
|
* @return
|
|
* - ESP_OK : On successful
|
|
* - ESP_FAIL : Socket errors occurs
|
|
* - ESP_ERR_INVALID_STATE : Handshake was already done beforehand
|
|
* - ESP_ERR_INVALID_ARG : Argument is invalid (null or non-WebSocket)
|
|
*/
|
|
esp_err_t httpd_ws_recv_frame(httpd_req_t *req, httpd_ws_frame_t *pkt, size_t max_len);
|
|
|
|
/**
|
|
* @brief Construct and send a WebSocket frame
|
|
* @param[in] req Current request
|
|
* @param[in] pkt WebSocket frame
|
|
* @return
|
|
* - ESP_OK : On successful
|
|
* - ESP_FAIL : When socket errors occurs
|
|
* - ESP_ERR_INVALID_STATE : Handshake was already done beforehand
|
|
* - ESP_ERR_INVALID_ARG : Argument is invalid (null or non-WebSocket)
|
|
*/
|
|
esp_err_t httpd_ws_send_frame(httpd_req_t *req, httpd_ws_frame_t *pkt);
|
|
|
|
/**
|
|
* @brief Low level send of a WebSocket frame out of the scope of current request
|
|
* using internally configured httpd send function
|
|
*
|
|
* This API should rarely be called directly, with an exception of asynchronous send using httpd_queue_work.
|
|
*
|
|
* @param[in] hd Server instance data
|
|
* @param[in] fd Socket descriptor for sending data
|
|
* @param[in] frame WebSocket frame
|
|
* @return
|
|
* - ESP_OK : On successful
|
|
* - ESP_FAIL : When socket errors occurs
|
|
* - ESP_ERR_INVALID_STATE : Handshake was already done beforehand
|
|
* - ESP_ERR_INVALID_ARG : Argument is invalid (null or non-WebSocket)
|
|
*/
|
|
esp_err_t httpd_ws_send_frame_async(httpd_handle_t hd, int fd, httpd_ws_frame_t *frame);
|
|
|
|
/**
|
|
* @brief Checks the supplied socket descriptor if it belongs to any active client
|
|
* of this server instance and if the websoket protocol is active
|
|
*
|
|
* @param[in] hd Server instance data
|
|
* @param[in] fd Socket descriptor
|
|
* @return
|
|
* - HTTPD_WS_CLIENT_INVALID : This fd is not a client of this httpd
|
|
* - HTTPD_WS_CLIENT_HTTP : This fd is an active client, protocol is not WS
|
|
* - HTTPD_WS_CLIENT_WEBSOCKET : This fd is an active client, protocol is WS
|
|
*/
|
|
httpd_ws_client_info_t httpd_ws_get_fd_info(httpd_handle_t hd, int fd);
|
|
|
|
/**
|
|
* @brief Sends data to to specified websocket synchronously
|
|
*
|
|
* @param[in] handle Server instance data
|
|
* @param[in] socket Socket descriptor
|
|
* @param[in] frame Websocket frame
|
|
* @return
|
|
* - ESP_OK : On successful
|
|
* - ESP_FAIL : When socket errors occurs
|
|
* - ESP_ERR_NO_MEM : Unable to allocate memory
|
|
*/
|
|
esp_err_t httpd_ws_send_data(httpd_handle_t handle, int socket, httpd_ws_frame_t *frame);
|
|
|
|
/**
|
|
* @brief Sends data to to specified websocket asynchronously
|
|
*
|
|
* @param[in] handle Server instance data
|
|
* @param[in] socket Socket descriptor
|
|
* @param[in] frame Websocket frame
|
|
* @param[in] callback Callback invoked after sending data
|
|
* @param[in] arg User data passed to provided callback
|
|
* @return
|
|
* - ESP_OK : On successful
|
|
* - ESP_FAIL : When socket errors occurs
|
|
* - ESP_ERR_NO_MEM : Unable to allocate memory
|
|
*/
|
|
esp_err_t httpd_ws_send_data_async(httpd_handle_t handle, int socket, httpd_ws_frame_t *frame,
|
|
transfer_complete_cb callback, void *arg);
|
|
|
|
#endif /* CONFIG_HTTPD_WS_SUPPORT */
|
|
/** End of WebSocket related stuff
|
|
* @}
|
|
*/
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* ! _ESP_HTTP_SERVER_H_ */
|