1 /** @file
2  * @brief HTTP client API
3  *
4  * An API for applications do HTTP requests
5  */
6 
7 /*
8  * Copyright (c) 2019 Intel Corporation
9  *
10  * SPDX-License-Identifier: Apache-2.0
11  */
12 
13 #ifndef ZEPHYR_INCLUDE_NET_HTTP_CLIENT_H_
14 #define ZEPHYR_INCLUDE_NET_HTTP_CLIENT_H_
15 
16 /**
17  * @brief HTTP client API
18  * @defgroup http_client HTTP client API
19  * @since 2.1
20  * @version 0.2.0
21  * @ingroup networking
22  * @{
23  */
24 
25 #include <zephyr/kernel.h>
26 #include <zephyr/net/net_ip.h>
27 #include <zephyr/net/http/parser.h>
28 
29 #ifdef __cplusplus
30 extern "C" {
31 #endif
32 
33 /** @cond INTERNAL_HIDDEN */
34 
35 #if !defined(HTTP_CRLF)
36 #define HTTP_CRLF "\r\n"
37 #endif
38 
39 #if !defined(HTTP_STATUS_STR_SIZE)
40 #define HTTP_STATUS_STR_SIZE	32
41 #endif
42 
43 /** @endcond */
44 
45 /** Is there more data to come */
46 enum http_final_call {
47 	HTTP_DATA_MORE = 0,  /**< More data will come */
48 	HTTP_DATA_FINAL = 1, /**< End of data */
49 };
50 
51 struct http_request;
52 struct http_response;
53 
54 /**
55  * @typedef http_payload_cb_t
56  * @brief Callback used when data needs to be sent to the server.
57  *
58  * @param sock Socket id of the connection
59  * @param req HTTP request information
60  * @param user_data User specified data specified in http_client_req()
61  *
62  * @return >=0 amount of data sent, in this case http_client_req() should
63  *             continue sending data,
64  *         <0  if http_client_req() should return the error code to the
65  *             caller.
66  */
67 typedef int (*http_payload_cb_t)(int sock,
68 				 struct http_request *req,
69 				 void *user_data);
70 
71 /**
72  * @typedef http_header_cb_t
73  * @brief Callback can be used if application wants to construct additional
74  * HTTP headers when the HTTP request is sent. Usage of this is optional.
75  *
76  * @param sock Socket id of the connection
77  * @param req HTTP request information
78  * @param user_data User specified data specified in http_client_req()
79  *
80  * @return >=0 amount of data sent, in this case http_client_req() should
81  *             continue sending data,
82  *         <0  if http_client_req() should return the error code to the
83  *             caller.
84  */
85 typedef int (*http_header_cb_t)(int sock,
86 				struct http_request *req,
87 				void *user_data);
88 
89 /**
90  * @typedef http_response_cb_t
91  * @brief Callback used when data is received from the server.
92  *
93  * @param rsp HTTP response information
94  * @param final_data Does this data buffer contain all the data or
95  *        is there still more data to come.
96  * @param user_data User specified data specified in http_client_req()
97  */
98 typedef void (*http_response_cb_t)(struct http_response *rsp,
99 				   enum http_final_call final_data,
100 				   void *user_data);
101 
102 /**
103  * HTTP response from the server.
104  */
105 struct http_response {
106 	/** HTTP parser settings for the application usage */
107 	const struct http_parser_settings *http_cb;
108 
109 	/** User provided HTTP response callback which is
110 	 * called when a response is received to a sent HTTP
111 	 * request.
112 	 */
113 	http_response_cb_t cb;
114 
115 	/**
116 	 *                       recv_buffer that contains header + body
117 	 *                       _______________________________________
118 	 *
119 	 *                                   |←-------- body_frag_len ---------→|
120 	 *                |←--------------------- data len --------------------→|
121 	 *            ---------------------------------------------------------------
122 	 *      ..header  |      header      |               body               |  body..
123 	 *            ---------------------------------------------------------------
124 	 *                ↑                  ↑
125 	 *             recv_buf          body_frag_start
126 	 *
127 	 *
128 	 *                          recv_buffer that contains body only
129 	 *                          ___________________________________
130 	 *
131 	 *                 |←------------------ body_frag_len ------------------→|
132 	 *                 |←--------------------- data len --------------------→|
133 	 *            ---------------------------------------------------------------
134 	 *  ..header/body  |                         body                        |  body..
135 	 *            ---------------------------------------------------------------
136 	 *                 ↑
137 	 *              recv_buf
138 	 *          body_frag_start
139 	 *
140 	 * body_frag_start >= recv_buf
141 	 * body_frag_len = data_len - (body_frag_start - recv_buf)
142 	 */
143 	/** Start address of the body fragment contained in the recv_buf */
144 	uint8_t *body_frag_start;
145 
146 	/** Length of the body fragment contained in the recv_buf */
147 	size_t body_frag_len;
148 
149 	/** Where the response is stored, this is to be
150 	 * provided by the user.
151 	 */
152 	uint8_t *recv_buf;
153 
154 	/** Response buffer maximum length */
155 	size_t recv_buf_len;
156 
157 	/** Length of the data in the result buf. If the value
158 	 * is larger than recv_buf_len, then it means that
159 	 * the data is truncated and could not be fully copied
160 	 * into recv_buf. This can only happen if the user
161 	 * did not set the response callback. If the callback
162 	 * is set, then the HTTP client API will call response
163 	 * callback many times so that all the data is
164 	 * delivered to the user. Will be zero in the event of
165 	 * a null response.
166 	 */
167 	size_t data_len;
168 
169 	/** HTTP Content-Length field value. Will be set to zero
170 	 * in the event of a null response.
171 	 */
172 	size_t content_length;
173 
174 	/** Amount of data given to the response callback so far, including the
175 	 * current data given to the callback. This should be equal to the
176 	 * content_length field once the entire body has been received. Will be
177 	 * zero if a null response is given.
178 	 */
179 	size_t processed;
180 
181 	/** See https://tools.ietf.org/html/rfc7230#section-3.1.2 for more information.
182 	 * The status-code element is a 3-digit integer code
183 	 *
184 	 * The reason-phrase element exists for the sole
185 	 * purpose of providing a textual description
186 	 * associated with the numeric status code. A client
187 	 * SHOULD ignore the reason-phrase content.
188 	 *
189 	 * Will be blank if a null HTTP response is given.
190 	 */
191 	char http_status[HTTP_STATUS_STR_SIZE];
192 
193 	/** Numeric HTTP status code which corresponds to the
194 	 * textual description. Set to zero if null response is
195 	 * given. Otherwise, will be a 3-digit integer code if
196 	 * valid HTTP response is given.
197 	 */
198 	uint16_t http_status_code;
199 
200 	/**
201 	 * HTTP Content-Range response field value. Consist of range_start,
202 	 * range_end and total_size. Total is set to 0 if not supplied.
203 	 */
204 	struct http_content_range content_range;
205 
206 	uint8_t cl_present : 1;       /**< Is Content-Length field present */
207 	uint8_t body_found : 1;       /**< Is message body found */
208 	uint8_t message_complete : 1; /**< Is HTTP message parsing complete */
209 	uint8_t cr_present : 1;       /**< Is Content-Range field present */
210 };
211 
212 /** HTTP client internal data that the application should not touch
213  */
214 struct http_client_internal_data {
215 	/** HTTP parser context */
216 	struct http_parser parser;
217 
218 	/** HTTP parser settings */
219 	struct http_parser_settings parser_settings;
220 
221 	/** HTTP response specific data (filled by http_client_req() when
222 	 * data is received)
223 	 */
224 	struct http_response response;
225 
226 	/** User data */
227 	void *user_data;
228 
229 	/** HTTP socket */
230 	int sock;
231 };
232 
233 /**
234  * HTTP client request. This contains all the data that is needed when doing
235  * a HTTP request.
236  */
237 struct http_request {
238 	/** HTTP client request internal data */
239 	struct http_client_internal_data internal;
240 
241 	/* User should fill in following parameters */
242 
243 	/** The HTTP method: GET, HEAD, OPTIONS, POST, ... */
244 	enum http_method method;
245 
246 	/** User supplied callback function to call when response is
247 	 * received.
248 	 */
249 	http_response_cb_t response;
250 
251 	/** User supplied list of HTTP callback functions if the
252 	 * calling application wants to know the parsing status or the HTTP
253 	 * fields. This is optional and normally not needed.
254 	 */
255 	const struct http_parser_settings *http_cb;
256 
257 	/** User supplied buffer where received data is stored */
258 	uint8_t *recv_buf;
259 
260 	/** Length of the user supplied receive buffer */
261 	size_t recv_buf_len;
262 
263 	/** The URL for this request, for example: /index.html */
264 	const char *url;
265 
266 	/** The HTTP protocol, for example "HTTP/1.1" */
267 	const char *protocol;
268 
269 	/** The HTTP header fields (application specific)
270 	 * The Content-Type may be specified here or in the next field.
271 	 * Depending on your application, the Content-Type may vary, however
272 	 * some header fields may remain constant through the application's
273 	 * life cycle. This is a NULL terminated list of header fields.
274 	 */
275 	const char **header_fields;
276 
277 	/** The value of the Content-Type header field, may be NULL */
278 	const char *content_type_value;
279 
280 	/** Hostname to be used in the request */
281 	const char *host;
282 
283 	/** Port number to be used in the request */
284 	const char *port;
285 
286 	/** User supplied callback function to call when payload
287 	 * needs to be sent. This can be NULL in which case the payload field
288 	 * in http_request is used. The idea of this payload callback is to
289 	 * allow user to send more data that is practical to store in allocated
290 	 * memory.
291 	 */
292 	http_payload_cb_t payload_cb;
293 
294 	/** Payload, may be NULL */
295 	const char *payload;
296 
297 	/** Payload length is used to calculate Content-Length. Set to 0
298 	 * for chunked transfers.
299 	 */
300 	size_t payload_len;
301 
302 	/** User supplied callback function to call when optional headers need
303 	 * to be sent. This can be NULL, in which case the optional_headers
304 	 * field in http_request is used. The idea of this optional_headers
305 	 * callback is to allow user to send more HTTP header data that is
306 	 * practical to store in allocated memory.
307 	 */
308 	http_header_cb_t optional_headers_cb;
309 
310 	/** A NULL terminated list of any optional headers that
311 	 * should be added to the HTTP request. May be NULL.
312 	 * If the optional_headers_cb is specified, then this field is ignored.
313 	 * Note that there are two similar fields that contain headers,
314 	 * the header_fields above and this optional_headers. This is done
315 	 * like this to support Websocket use case where Websocket will use
316 	 * header_fields variable and any optional application specific
317 	 * headers will be placed into this field.
318 	 */
319 	const char **optional_headers;
320 };
321 
322 /**
323  * @brief Do a HTTP request. The callback is called when data is received
324  * from the HTTP server. The caller must have created a connection to the
325  * server before calling this function so connect() call must have be done
326  * successfully for the socket.
327  *
328  * @param sock Socket id of the connection.
329  * @param req HTTP request information
330  * @param timeout Max timeout to wait for the data. The timeout value cannot be
331  *        0 as there would be no time to receive the data.
332  *        The timeout value is in milliseconds.
333  * @param user_data User specified data that is passed to the callback.
334  *
335  * @return <0 if error, >=0 amount of data sent to the server
336  */
337 int http_client_req(int sock, struct http_request *req,
338 		    int32_t timeout, void *user_data);
339 
340 #ifdef __cplusplus
341 }
342 #endif
343 
344 /**
345  * @}
346  */
347 
348 #endif /* ZEPHYR_INCLUDE_NET_HTTP_CLIENT_H_ */
349