esp_http_client.h 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614
  1. /*
  2. * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
  3. *
  4. * SPDX-License-Identifier: Apache-2.0
  5. */
  6. #ifndef _ESP_HTTP_CLIENT_H
  7. #define _ESP_HTTP_CLIENT_H
  8. #include "freertos/FreeRTOS.h"
  9. #include "sdkconfig.h"
  10. #include "esp_err.h"
  11. #include <sys/socket.h>
  12. #ifdef __cplusplus
  13. extern "C" {
  14. #endif
  15. #define DEFAULT_HTTP_BUF_SIZE (512)
  16. typedef struct esp_http_client *esp_http_client_handle_t;
  17. typedef struct esp_http_client_event *esp_http_client_event_handle_t;
  18. /**
  19. * @brief HTTP Client events id
  20. */
  21. typedef enum {
  22. HTTP_EVENT_ERROR = 0, /*!< This event occurs when there are any errors during execution */
  23. HTTP_EVENT_ON_CONNECTED, /*!< Once the HTTP has been connected to the server, no data exchange has been performed */
  24. HTTP_EVENT_HEADERS_SENT, /*!< After sending all the headers to the server */
  25. HTTP_EVENT_HEADER_SENT = HTTP_EVENT_HEADERS_SENT, /*!< This header has been kept for backward compatability
  26. and will be deprecated in future versions esp-idf */
  27. HTTP_EVENT_ON_HEADER, /*!< Occurs when receiving each header sent from the server */
  28. HTTP_EVENT_ON_DATA, /*!< Occurs when receiving data from the server, possibly multiple portions of the packet */
  29. HTTP_EVENT_ON_FINISH, /*!< Occurs when finish a HTTP session */
  30. HTTP_EVENT_DISCONNECTED, /*!< The connection has been disconnected */
  31. HTTP_EVENT_REDIRECT, /*!< Intercepting HTTP redirects to handle them manually */
  32. } esp_http_client_event_id_t;
  33. /**
  34. * @brief HTTP Client events data
  35. */
  36. typedef struct esp_http_client_event {
  37. esp_http_client_event_id_t event_id; /*!< event_id, to know the cause of the event */
  38. esp_http_client_handle_t client; /*!< esp_http_client_handle_t context */
  39. void *data; /*!< data of the event */
  40. int data_len; /*!< data length of data */
  41. void *user_data; /*!< user_data context, from esp_http_client_config_t user_data */
  42. char *header_key; /*!< For HTTP_EVENT_ON_HEADER event_id, it's store current http header key */
  43. char *header_value; /*!< For HTTP_EVENT_ON_HEADER event_id, it's store current http header value */
  44. } esp_http_client_event_t;
  45. /**
  46. * @brief HTTP Client transport
  47. */
  48. typedef enum {
  49. HTTP_TRANSPORT_UNKNOWN = 0x0, /*!< Unknown */
  50. HTTP_TRANSPORT_OVER_TCP, /*!< Transport over tcp */
  51. HTTP_TRANSPORT_OVER_SSL, /*!< Transport over ssl */
  52. } esp_http_client_transport_t;
  53. typedef esp_err_t (*http_event_handle_cb)(esp_http_client_event_t *evt);
  54. /**
  55. * @brief HTTP method
  56. */
  57. typedef enum {
  58. HTTP_METHOD_GET = 0, /*!< HTTP GET Method */
  59. HTTP_METHOD_POST, /*!< HTTP POST Method */
  60. HTTP_METHOD_PUT, /*!< HTTP PUT Method */
  61. HTTP_METHOD_PATCH, /*!< HTTP PATCH Method */
  62. HTTP_METHOD_DELETE, /*!< HTTP DELETE Method */
  63. HTTP_METHOD_HEAD, /*!< HTTP HEAD Method */
  64. HTTP_METHOD_NOTIFY, /*!< HTTP NOTIFY Method */
  65. HTTP_METHOD_SUBSCRIBE, /*!< HTTP SUBSCRIBE Method */
  66. HTTP_METHOD_UNSUBSCRIBE,/*!< HTTP UNSUBSCRIBE Method */
  67. HTTP_METHOD_OPTIONS, /*!< HTTP OPTIONS Method */
  68. HTTP_METHOD_COPY, /*!< HTTP COPY Method */
  69. HTTP_METHOD_MOVE, /*!< HTTP MOVE Method */
  70. HTTP_METHOD_LOCK, /*!< HTTP LOCK Method */
  71. HTTP_METHOD_UNLOCK, /*!< HTTP UNLOCK Method */
  72. HTTP_METHOD_PROPFIND, /*!< HTTP PROPFIND Method */
  73. HTTP_METHOD_PROPPATCH, /*!< HTTP PROPPATCH Method */
  74. HTTP_METHOD_MKCOL, /*!< HTTP MKCOL Method */
  75. HTTP_METHOD_MAX,
  76. } esp_http_client_method_t;
  77. /**
  78. * @brief HTTP Authentication type
  79. */
  80. typedef enum {
  81. HTTP_AUTH_TYPE_NONE = 0, /*!< No authention */
  82. HTTP_AUTH_TYPE_BASIC, /*!< HTTP Basic authentication */
  83. HTTP_AUTH_TYPE_DIGEST, /*!< HTTP Disgest authentication */
  84. } esp_http_client_auth_type_t;
  85. /**
  86. * @brief HTTP configuration
  87. */
  88. typedef struct {
  89. const char *url; /*!< HTTP URL, the information on the URL is most important, it overrides the other fields below, if any */
  90. const char *host; /*!< Domain or IP as string */
  91. int port; /*!< Port to connect, default depend on esp_http_client_transport_t (80 or 443) */
  92. const char *username; /*!< Using for Http authentication */
  93. const char *password; /*!< Using for Http authentication */
  94. esp_http_client_auth_type_t auth_type; /*!< Http authentication type, see `esp_http_client_auth_type_t` */
  95. const char *path; /*!< HTTP Path, if not set, default is `/` */
  96. const char *query; /*!< HTTP query */
  97. const char *cert_pem; /*!< SSL server certification, PEM format as string, if the client requires to verify server */
  98. size_t cert_len; /*!< Length of the buffer pointed to by cert_pem. May be 0 for null-terminated pem */
  99. const char *client_cert_pem; /*!< SSL client certification, PEM format as string, if the server requires to verify client */
  100. size_t client_cert_len; /*!< Length of the buffer pointed to by client_cert_pem. May be 0 for null-terminated pem */
  101. const char *client_key_pem; /*!< SSL client key, PEM format as string, if the server requires to verify client */
  102. size_t client_key_len; /*!< Length of the buffer pointed to by client_key_pem. May be 0 for null-terminated pem */
  103. const char *client_key_password; /*!< Client key decryption password string */
  104. size_t client_key_password_len; /*!< String length of the password pointed to by client_key_password */
  105. const char *user_agent; /*!< The User Agent string to send with HTTP requests */
  106. esp_http_client_method_t method; /*!< HTTP Method */
  107. int timeout_ms; /*!< Network timeout in milliseconds */
  108. bool disable_auto_redirect; /*!< Disable HTTP automatic redirects */
  109. int max_redirection_count; /*!< Max number of redirections on receiving HTTP redirect status code, using default value if zero*/
  110. int max_authorization_retries; /*!< Max connection retries on receiving HTTP unauthorized status code, using default value if zero. Disables authorization retry if -1*/
  111. http_event_handle_cb event_handler; /*!< HTTP Event Handle */
  112. esp_http_client_transport_t transport_type; /*!< HTTP transport type, see `esp_http_client_transport_t` */
  113. int buffer_size; /*!< HTTP receive buffer size */
  114. int buffer_size_tx; /*!< HTTP transmit buffer size */
  115. void *user_data; /*!< HTTP user_data context */
  116. bool is_async; /*!< Set asynchronous mode, only supported with HTTPS for now */
  117. bool use_global_ca_store; /*!< Use a global ca_store for all the connections in which this bool is set. */
  118. bool skip_cert_common_name_check; /*!< Skip any validation of server certificate CN field */
  119. esp_err_t (*crt_bundle_attach)(void *conf); /*!< Function pointer to esp_crt_bundle_attach. Enables the use of certification
  120. bundle for server verification, must be enabled in menuconfig */
  121. bool keep_alive_enable; /*!< Enable keep-alive timeout */
  122. int keep_alive_idle; /*!< Keep-alive idle time. Default is 5 (second) */
  123. int keep_alive_interval; /*!< Keep-alive interval time. Default is 5 (second) */
  124. int keep_alive_count; /*!< Keep-alive packet retry send count. Default is 3 counts */
  125. struct ifreq *if_name; /*!< The name of interface for data to go through. Use the default interface without setting */
  126. } esp_http_client_config_t;
  127. /**
  128. * Enum for the HTTP status codes.
  129. */
  130. typedef enum {
  131. /* 2xx - Success */
  132. HttpStatus_Ok = 200,
  133. /* 3xx - Redirection */
  134. HttpStatus_MultipleChoices = 300,
  135. HttpStatus_MovedPermanently = 301,
  136. HttpStatus_Found = 302,
  137. HttpStatus_SeeOther = 303,
  138. HttpStatus_TemporaryRedirect = 307,
  139. HttpStatus_PermanentRedirect = 308,
  140. /* 4xx - Client Error */
  141. HttpStatus_BadRequest = 400,
  142. HttpStatus_Unauthorized = 401,
  143. HttpStatus_Forbidden = 403,
  144. HttpStatus_NotFound = 404,
  145. /* 5xx - Server Error */
  146. HttpStatus_InternalError = 500
  147. } HttpStatus_Code;
  148. #define ESP_ERR_HTTP_BASE (0x7000) /*!< Starting number of HTTP error codes */
  149. #define ESP_ERR_HTTP_MAX_REDIRECT (ESP_ERR_HTTP_BASE + 1) /*!< The error exceeds the number of HTTP redirects */
  150. #define ESP_ERR_HTTP_CONNECT (ESP_ERR_HTTP_BASE + 2) /*!< Error open the HTTP connection */
  151. #define ESP_ERR_HTTP_WRITE_DATA (ESP_ERR_HTTP_BASE + 3) /*!< Error write HTTP data */
  152. #define ESP_ERR_HTTP_FETCH_HEADER (ESP_ERR_HTTP_BASE + 4) /*!< Error read HTTP header from server */
  153. #define ESP_ERR_HTTP_INVALID_TRANSPORT (ESP_ERR_HTTP_BASE + 5) /*!< There are no transport support for the input scheme */
  154. #define ESP_ERR_HTTP_CONNECTING (ESP_ERR_HTTP_BASE + 6) /*!< HTTP connection hasn't been established yet */
  155. #define ESP_ERR_HTTP_EAGAIN (ESP_ERR_HTTP_BASE + 7) /*!< Mapping of errno EAGAIN to esp_err_t */
  156. #define ESP_ERR_HTTP_CONNECTION_CLOSED (ESP_ERR_HTTP_BASE + 8) /*!< Read FIN from peer and the connection closed */
  157. /**
  158. * @brief Start a HTTP session
  159. * This function must be the first function to call,
  160. * and it returns a esp_http_client_handle_t that you must use as input to other functions in the interface.
  161. * This call MUST have a corresponding call to esp_http_client_cleanup when the operation is complete.
  162. *
  163. * @param[in] config The configurations, see `http_client_config_t`
  164. *
  165. * @return
  166. * - `esp_http_client_handle_t`
  167. * - NULL if any errors
  168. */
  169. esp_http_client_handle_t esp_http_client_init(const esp_http_client_config_t *config);
  170. /**
  171. * @brief Invoke this function after `esp_http_client_init` and all the options calls are made, and will perform the
  172. * transfer as described in the options. It must be called with the same esp_http_client_handle_t as input as the esp_http_client_init call returned.
  173. * esp_http_client_perform performs the entire request in either blocking or non-blocking manner. By default, the API performs request in a blocking manner and returns when done,
  174. * or if it failed, and in non-blocking manner, it returns if EAGAIN/EWOULDBLOCK or EINPROGRESS is encountered, or if it failed. And in case of non-blocking request,
  175. * the user may call this API multiple times unless request & response is complete or there is a failure. To enable non-blocking esp_http_client_perform(), `is_async` member of esp_http_client_config_t
  176. * must be set while making a call to esp_http_client_init() API.
  177. * You can do any amount of calls to esp_http_client_perform while using the same esp_http_client_handle_t. The underlying connection may be kept open if the server allows it.
  178. * If you intend to transfer more than one file, you are even encouraged to do so.
  179. * esp_http_client will then attempt to re-use the same connection for the following transfers, thus making the operations faster, less CPU intense and using less network resources.
  180. * Just note that you will have to use `esp_http_client_set_**` between the invokes to set options for the following esp_http_client_perform.
  181. *
  182. * @note You must never call this function simultaneously from two places using the same client handle.
  183. * Let the function return first before invoking it another time.
  184. * If you want parallel transfers, you must use several esp_http_client_handle_t.
  185. * This function include `esp_http_client_open` -> `esp_http_client_write` -> `esp_http_client_fetch_headers` -> `esp_http_client_read` (and option) `esp_http_client_close`.
  186. *
  187. * @param client The esp_http_client handle
  188. *
  189. * @return
  190. * - ESP_OK on successful
  191. * - ESP_FAIL on error
  192. */
  193. esp_err_t esp_http_client_perform(esp_http_client_handle_t client);
  194. /**
  195. * @brief Set URL for client, when performing this behavior, the options in the URL will replace the old ones
  196. *
  197. * @param[in] client The esp_http_client handle
  198. * @param[in] url The url
  199. *
  200. * @return
  201. * - ESP_OK
  202. * - ESP_FAIL
  203. */
  204. esp_err_t esp_http_client_set_url(esp_http_client_handle_t client, const char *url);
  205. /**
  206. * @brief Set post data, this function must be called before `esp_http_client_perform`.
  207. * Note: The data parameter passed to this function is a pointer and this function will not copy the data
  208. *
  209. * @param[in] client The esp_http_client handle
  210. * @param[in] data post data pointer
  211. * @param[in] len post length
  212. *
  213. * @return
  214. * - ESP_OK
  215. * - ESP_FAIL
  216. */
  217. esp_err_t esp_http_client_set_post_field(esp_http_client_handle_t client, const char *data, int len);
  218. /**
  219. * @brief Get current post field information
  220. *
  221. * @param[in] client The client
  222. * @param[out] data Point to post data pointer
  223. *
  224. * @return Size of post data
  225. */
  226. int esp_http_client_get_post_field(esp_http_client_handle_t client, char **data);
  227. /**
  228. * @brief Set http request header, this function must be called after esp_http_client_init and before any
  229. * perform function
  230. *
  231. * @param[in] client The esp_http_client handle
  232. * @param[in] key The header key
  233. * @param[in] value The header value
  234. *
  235. * @return
  236. * - ESP_OK
  237. * - ESP_FAIL
  238. */
  239. esp_err_t esp_http_client_set_header(esp_http_client_handle_t client, const char *key, const char *value);
  240. /**
  241. * @brief Get http request header.
  242. * The value parameter will be set to NULL if there is no header which is same as
  243. * the key specified, otherwise the address of header value will be assigned to value parameter.
  244. * This function must be called after `esp_http_client_init`.
  245. *
  246. * @param[in] client The esp_http_client handle
  247. * @param[in] key The header key
  248. * @param[out] value The header value
  249. *
  250. * @return
  251. * - ESP_OK
  252. * - ESP_FAIL
  253. */
  254. esp_err_t esp_http_client_get_header(esp_http_client_handle_t client, const char *key, char **value);
  255. /**
  256. * @brief Get http request username.
  257. * The address of username buffer will be assigned to value parameter.
  258. * This function must be called after `esp_http_client_init`.
  259. *
  260. * @param[in] client The esp_http_client handle
  261. * @param[out] value The username value
  262. *
  263. * @return
  264. * - ESP_OK
  265. * - ESP_ERR_INVALID_ARG
  266. */
  267. esp_err_t esp_http_client_get_username(esp_http_client_handle_t client, char **value);
  268. /**
  269. * @brief Set http request username.
  270. * The value of username parameter will be assigned to username buffer.
  271. * If the username parameter is NULL then username buffer will be freed.
  272. *
  273. * @param[in] client The esp_http_client handle
  274. * @param[in] username The username value
  275. *
  276. * @return
  277. * - ESP_OK
  278. * - ESP_ERR_INVALID_ARG
  279. */
  280. esp_err_t esp_http_client_set_username(esp_http_client_handle_t client, const char *username);
  281. /**
  282. * @brief Get http request password.
  283. * The address of password buffer will be assigned to value parameter.
  284. * This function must be called after `esp_http_client_init`.
  285. *
  286. * @param[in] client The esp_http_client handle
  287. * @param[out] value The password value
  288. *
  289. * @return
  290. * - ESP_OK
  291. * - ESP_ERR_INVALID_ARG
  292. */
  293. esp_err_t esp_http_client_get_password(esp_http_client_handle_t client, char **value);
  294. /**
  295. * @brief Set http request password.
  296. * The value of password parameter will be assigned to password buffer.
  297. * If the password parameter is NULL then password buffer will be freed.
  298. *
  299. * @param[in] client The esp_http_client handle
  300. * @param[in] password The password value
  301. *
  302. * @return
  303. * - ESP_OK
  304. * - ESP_ERR_INVALID_ARG
  305. */
  306. esp_err_t esp_http_client_set_password(esp_http_client_handle_t client, const char *password);
  307. /**
  308. * @brief Set http request auth_type.
  309. *
  310. * @param[in] client The esp_http_client handle
  311. * @param[in] auth_type The esp_http_client auth type
  312. *
  313. * @return
  314. * - ESP_OK
  315. * - ESP_ERR_INVALID_ARG
  316. */
  317. esp_err_t esp_http_client_set_authtype(esp_http_client_handle_t client, esp_http_client_auth_type_t auth_type);
  318. /**
  319. * @brief Get HTTP client session errno
  320. *
  321. * @param[in] client The esp_http_client handle
  322. *
  323. * @return
  324. * - (-1) if invalid argument
  325. * - errno
  326. */
  327. int esp_http_client_get_errno(esp_http_client_handle_t client);
  328. /**
  329. * @brief Set http request method
  330. *
  331. * @param[in] client The esp_http_client handle
  332. * @param[in] method The method
  333. *
  334. * @return
  335. * - ESP_OK
  336. * - ESP_ERR_INVALID_ARG
  337. */
  338. esp_err_t esp_http_client_set_method(esp_http_client_handle_t client, esp_http_client_method_t method);
  339. /**
  340. * @brief Set http request timeout
  341. *
  342. * @param[in] client The esp_http_client handle
  343. * @param[in] timeout_ms The timeout value
  344. *
  345. * @return
  346. * - ESP_OK
  347. * - ESP_ERR_INVALID_ARG
  348. */
  349. esp_err_t esp_http_client_set_timeout_ms(esp_http_client_handle_t client, int timeout_ms);
  350. /**
  351. * @brief Delete http request header
  352. *
  353. * @param[in] client The esp_http_client handle
  354. * @param[in] key The key
  355. *
  356. * @return
  357. * - ESP_OK
  358. * - ESP_FAIL
  359. */
  360. esp_err_t esp_http_client_delete_header(esp_http_client_handle_t client, const char *key);
  361. /**
  362. * @brief This function will be open the connection, write all header strings and return
  363. *
  364. * @param[in] client The esp_http_client handle
  365. * @param[in] write_len HTTP Content length need to write to the server
  366. *
  367. * @return
  368. * - ESP_OK
  369. * - ESP_FAIL
  370. */
  371. esp_err_t esp_http_client_open(esp_http_client_handle_t client, int write_len);
  372. /**
  373. * @brief This function will write data to the HTTP connection previously opened by esp_http_client_open()
  374. *
  375. * @param[in] client The esp_http_client handle
  376. * @param buffer The buffer
  377. * @param[in] len This value must not be larger than the write_len parameter provided to esp_http_client_open()
  378. *
  379. * @return
  380. * - (-1) if any errors
  381. * - Length of data written
  382. */
  383. int esp_http_client_write(esp_http_client_handle_t client, const char *buffer, int len);
  384. /**
  385. * @brief This function need to call after esp_http_client_open, it will read from http stream, process all receive headers
  386. *
  387. * @param[in] client The esp_http_client handle
  388. *
  389. * @return
  390. * - (0) if stream doesn't contain content-length header, or chunked encoding (checked by `esp_http_client_is_chunked` response)
  391. * - (-1: ESP_FAIL) if any errors
  392. * - (-ESP_ERR_HTTP_EAGAIN = -0x7007) if call is timed-out before any data was ready
  393. * - Download data length defined by content-length header
  394. */
  395. int64_t esp_http_client_fetch_headers(esp_http_client_handle_t client);
  396. /**
  397. * @brief Check response data is chunked
  398. *
  399. * @param[in] client The esp_http_client handle
  400. *
  401. * @return true or false
  402. */
  403. bool esp_http_client_is_chunked_response(esp_http_client_handle_t client);
  404. /**
  405. * @brief Read data from http stream
  406. *
  407. * @param[in] client The esp_http_client handle
  408. * @param buffer The buffer
  409. * @param[in] len The length
  410. *
  411. * @return
  412. * - (-1) if any errors
  413. * - Length of data was read
  414. *
  415. * @note (-ESP_ERR_HTTP_EAGAIN = -0x7007) is returned when call is timed-out before any data was ready
  416. */
  417. int esp_http_client_read(esp_http_client_handle_t client, char *buffer, int len);
  418. /**
  419. * @brief Get http response status code, the valid value if this function invoke after `esp_http_client_perform`
  420. *
  421. * @param[in] client The esp_http_client handle
  422. *
  423. * @return Status code
  424. */
  425. int esp_http_client_get_status_code(esp_http_client_handle_t client);
  426. /**
  427. * @brief Get http response content length (from header Content-Length)
  428. * the valid value if this function invoke after `esp_http_client_perform`
  429. *
  430. * @param[in] client The esp_http_client handle
  431. *
  432. * @return
  433. * - (-1) Chunked transfer
  434. * - Content-Length value as bytes
  435. */
  436. int64_t esp_http_client_get_content_length(esp_http_client_handle_t client);
  437. /**
  438. * @brief Close http connection, still kept all http request resources
  439. *
  440. * @param[in] client The esp_http_client handle
  441. *
  442. * @return
  443. * - ESP_OK
  444. * - ESP_FAIL
  445. */
  446. esp_err_t esp_http_client_close(esp_http_client_handle_t client);
  447. /**
  448. * @brief This function must be the last function to call for an session.
  449. * It is the opposite of the esp_http_client_init function and must be called with the same handle as input that a esp_http_client_init call returned.
  450. * This might close all connections this handle has used and possibly has kept open until now.
  451. * Don't call this function if you intend to transfer more files, re-using handles is a key to good performance with esp_http_client.
  452. *
  453. * @param[in] client The esp_http_client handle
  454. *
  455. * @return
  456. * - ESP_OK
  457. * - ESP_FAIL
  458. */
  459. esp_err_t esp_http_client_cleanup(esp_http_client_handle_t client);
  460. /**
  461. * @brief Get transport type
  462. *
  463. * @param[in] client The esp_http_client handle
  464. *
  465. * @return
  466. * - HTTP_TRANSPORT_UNKNOWN
  467. * - HTTP_TRANSPORT_OVER_TCP
  468. * - HTTP_TRANSPORT_OVER_SSL
  469. */
  470. esp_http_client_transport_t esp_http_client_get_transport_type(esp_http_client_handle_t client);
  471. /**
  472. * @brief Set redirection URL.
  473. * When received the 30x code from the server, the client stores the redirect URL provided by the server.
  474. * This function will set the current URL to redirect to enable client to execute the redirection request.
  475. *
  476. * @param[in] client The esp_http_client handle
  477. *
  478. * @return
  479. * - ESP_OK
  480. * - ESP_FAIL
  481. */
  482. esp_err_t esp_http_client_set_redirection(esp_http_client_handle_t client);
  483. /**
  484. * @brief On receiving HTTP Status code 401, this API can be invoked to add authorization
  485. * information.
  486. *
  487. * @note There is a possibility of receiving body message with redirection status codes, thus make sure
  488. * to flush off body data after calling this API.
  489. *
  490. * @param[in] client The esp_http_client handle
  491. */
  492. void esp_http_client_add_auth(esp_http_client_handle_t client);
  493. /**
  494. * @brief Checks if entire data in the response has been read without any error.
  495. *
  496. * @param[in] client The esp_http_client handle
  497. *
  498. * @return
  499. * - true
  500. * - false
  501. */
  502. bool esp_http_client_is_complete_data_received(esp_http_client_handle_t client);
  503. /**
  504. * @brief Helper API to read larger data chunks
  505. * This is a helper API which internally calls `esp_http_client_read` multiple times till the end of data is reached or till the buffer gets full.
  506. *
  507. * @param[in] client The esp_http_client handle
  508. * @param buffer The buffer
  509. * @param[in] len The buffer length
  510. *
  511. * @return
  512. * - Length of data was read
  513. */
  514. int esp_http_client_read_response(esp_http_client_handle_t client, char *buffer, int len);
  515. /**
  516. * @brief Process all remaining response data
  517. * This uses an internal buffer to repeatedly receive, parse, and discard response data until complete data is processed.
  518. * As no additional user-supplied buffer is required, this may be preferrable to `esp_http_client_read_response` in situations where the content of the response may be ignored.
  519. *
  520. * @param[in] client The esp_http_client handle
  521. * @param len Length of data discarded
  522. *
  523. * @return
  524. * - ESP_OK If successful, len will have discarded length
  525. * - ESP_FAIL If failed to read response
  526. * - ESP_ERR_INVALID_ARG If the client is NULL
  527. */
  528. esp_err_t esp_http_client_flush_response(esp_http_client_handle_t client, int *len);
  529. /**
  530. * @brief Get URL from client
  531. *
  532. * @param[in] client The esp_http_client handle
  533. * @param[inout] url The buffer to store URL
  534. * @param[in] len The buffer length
  535. *
  536. * @return
  537. * - ESP_OK
  538. * - ESP_FAIL
  539. */
  540. esp_err_t esp_http_client_get_url(esp_http_client_handle_t client, char *url, const int len);
  541. /**
  542. * @brief Get Chunk-Length from client
  543. *
  544. * @param[in] client The esp_http_client handle
  545. * @param[out] len Variable to store length
  546. *
  547. * @return
  548. * - ESP_OK If successful, len will have length of current chunk
  549. * - ESP_FAIL If the server is not a chunked server
  550. * - ESP_ERR_INVALID_ARG If the client or len are NULL
  551. */
  552. esp_err_t esp_http_client_get_chunk_length(esp_http_client_handle_t client, int *len);
  553. #ifdef __cplusplus
  554. }
  555. #endif
  556. #endif