Skip to content

Commit dfef9d5

Browse files
committed
feat(esp_http_server): Added httpd URI handler docs
Added docs to clarify the working of httpd URI handler
1 parent 7f88aa2 commit dfef9d5

File tree

1 file changed

+35
-0
lines changed

1 file changed

+35
-0
lines changed

docs/en/api-reference/protocols/esp_http_server.rst

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,41 @@ RESTful API
106106

107107
:example:`protocols/http_server/restful_server` demonstrates how to implement a RESTful API server and HTTP server, with a frontend browser UI, and designs several APIs to fetch resources, using mDNS to parse the domain name, and deploying the webpage to host PC via semihost technology or to SPI flash or SD Card.
108108

109+
URI Handlers
110+
------------
111+
112+
The HTTP server allows you to register URI handlers to handle different HTTP requests. Each URI handler is associated with a specific URI and HTTP method (GET, POST, etc.). The handler function is called whenever a request matching the URI and method is received.
113+
114+
The handler function should return an :cpp:type:`esp_err_t` value.
115+
116+
.. code-block:: c
117+
118+
esp_err_t my_uri_handler(httpd_req_t *req)
119+
{
120+
// Handle the request
121+
// ...
122+
123+
// Return ESP_OK if the request was handled successfully
124+
return ESP_OK;
125+
126+
// Return an error code to close the connection
127+
// return ESP_FAIL;
128+
}
129+
130+
void register_uri_handlers(httpd_handle_t server)
131+
{
132+
httpd_uri_t my_uri = {
133+
.uri = "/my_uri",
134+
.method = HTTP_GET,
135+
.handler = my_uri_handler,
136+
.user_ctx = NULL
137+
};
138+
139+
httpd_register_uri_handler(server, &my_uri);
140+
}
141+
142+
In this example, the `my_uri_handler` function handles requests to the `/my_uri` URI. If the handler returns :c:macro:`ESP_OK`, the connection remains open. If it returns any other value, the connection is closed. This behavior allows the application to manage connection closure based on specific events or conditions.
143+
109144
API Reference
110145
-------------
111146

0 commit comments

Comments
 (0)