// Copyright 2018 Espressif Systems (Shanghai) PTE LTD // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. // You may obtain a copy of the License at // // http://www.apache.org/licenses/LICENSE-2.0 // // Unless required by applicable law or agreed to in writing, software // distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. // See the License for the specific language governing permissions and // limitations under the License. #ifndef _HTTP_SERVER_H_ #define _HTTP_SERVER_H_ #include #include #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif #define HTTPD_DEFAULT_CONFIG() { \ .task_priority = tskIDLE_PRIORITY+5, \ .stack_size = 4096, \ .server_port = 80, \ .ctrl_port = 32768, \ .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, \ }; #define ESP_ERR_HTTPD_BASE (0x8000) /*!< 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 occured 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 */ /* ************** 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; /** * @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 */ /** * 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*/ 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)*/ } 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 * @{ */ /** * @brief Function type for freeing context data (if any) */ typedef void (*httpd_free_sess_ctx_fn_t)(void *sess_ctx); /* 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 */ 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_sess_ctx_fn_t free_ctx; } 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 */ /** * 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; } 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: TX/RX ************** */ /** @name TX / RX * Prototype for HTTPDs low-level send/recv functions * @{ */ /** * @brief Prototype for HTTPDs low-level send function * @return * - Bytes : The number of bytes sent successfully * - -VE : In case of error */ typedef int (*httpd_send_func_t)(int sockfd, const char *buf, size_t buf_len, int flags); /** * @brief Prototype for HTTPDs low-level recv function * @return * - Bytes : The number of bytes received successfully * - -VE : In case of error */ typedef int (*httpd_recv_func_t)(int sockfd, char *buf, size_t buf_len, int flags); /** 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 * * This function overrides the web server's receive function. This same function is * used to read and parse HTTP headers as well as body. * * @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 * @param[in] recv_func The receive function to be set for this request * * @return * - ESP_OK : On successfully registering override * - ESP_ERR_INVALID_ARG : Null arguments * - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer */ esp_err_t httpd_set_recv_override(httpd_req_t *r, httpd_recv_func_t recv_func); /** * @brief Override web server's send function * * 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 only from the context of * a URI handler where httpd_req_t* request pointer is valid. * * @param[in] r The request being responded to * @param[in] send_func The send function to be set for this request * * @return * - ESP_OK : On successfully registering override * - ESP_ERR_INVALID_ARG : Null arguments * - ESP_ERR_HTTPD_INVALID_REQ : Invalid request pointer */ esp_err_t httpd_set_send_override(httpd_req_t *r, httpd_send_func_t send_func); /** * @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_trigger_sess_close(), * httpd_sess_update_timestamp(). * * @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 * - Zero : When no more data is left for read * - -1 : On raw recv error / Null arguments / Request pointer is invalid */ 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 * - Use httpd_req_get_url_query_len() to know the right buffer length * * @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 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 * * @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, size_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 data from the buffer that should be sent out * * @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, size_t buf_len); /* 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_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 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 */ esp_err_t httpd_resp_send_404(httpd_req_t *r); /** * @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 delimeters (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 * - -1 : Error in raw send / Invalid request / Null arguments */ int httpd_send(httpd_req_t *r, const char *buf, size_t buf_len); /** 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 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_trigger_sess_close(httpd_handle_t handle, int sockfd); /** * @brief Update timestamp for a given socket * * Timestamps 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 * timestamp is closed automatically. * * Updating the timestamp 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 timestamp * is to be updated * * @return * - ESP_OK : Socket found and timestamp updated * - ESP_ERR_NOT_FOUND : Socket not found * - ESP_ERR_INVALID_ARG : Null arguments */ esp_err_t httpd_sess_update_timestamp(httpd_handle_t handle, int sockfd); /** 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 * @} */ #ifdef __cplusplus } #endif #endif /* ! _HTTP_SERVER_H_ */