Merge "res_odbc: Correct the dependency relationship with res_odbc_transaction"
[asterisk/asterisk.git] / include / asterisk / http.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 #ifndef _ASTERISK_HTTP_H
20 #define _ASTERISK_HTTP_H
21
22 #include "asterisk/config.h"
23 #include "asterisk/tcptls.h"
24 #include "asterisk/linkedlists.h"
25
26 /*!
27  * \file http.h
28  * \brief Support for Private Asterisk HTTP Servers.
29  * \note Note: The Asterisk HTTP servers are extremely simple and minimal and
30  *      only support the "GET" method.
31  *
32  * \author Mark Spencer <markster@digium.com>
33  *
34  * \note In order to have TLS/SSL support, we need the openssl libraries.
35  * Still we can decide whether or not to use them by commenting
36  * in or out the DO_SSL macro.
37  * TLS/SSL support is basically implemented by reading from a config file
38  * (currently http.conf) the names of the certificate and cipher to use,
39  * and then run ssl_setup() to create an appropriate SSL_CTX (ssl_ctx)
40  * If we support multiple domains, presumably we need to read multiple
41  * certificates.
42  * When we are requested to open a TLS socket, we run make_file_from_fd()
43  * on the socket, to do the necessary setup. At the moment the context's name
44  * is hardwired in the function, but we can certainly make it into an extra
45  * parameter to the function.
46  * We declare most of ssl support variables unconditionally,
47  * because their number is small and this simplifies the code.
48  *
49  * \note: the ssl-support variables (ssl_ctx, do_ssl, certfile, cipher)
50  * and their setup should be moved to a more central place, e.g. asterisk.conf
51  * and the source files that processes it. Similarly, ssl_setup() should
52  * be run earlier in the startup process so modules have it available.
53  */
54
55 /*! \brief HTTP Request methods known by Asterisk */
56 enum ast_http_method {
57         AST_HTTP_UNKNOWN = -1,   /*!< Unknown response */
58         AST_HTTP_GET = 0,
59         AST_HTTP_POST,
60         AST_HTTP_HEAD,
61         AST_HTTP_PUT,
62         AST_HTTP_DELETE,
63         AST_HTTP_OPTIONS,
64         AST_HTTP_MAX_METHOD, /*!< Last entry in ast_http_method enum */
65 };
66
67 struct ast_http_uri;
68
69 /*!
70  * \brief HTTP Callbacks
71  *
72  * \param ser TCP/TLS session object
73  * \param urih Registered URI handler struct for the URI.
74  * \param uri Remaining request URI path (also with the get_params removed).
75  * \param method enum ast_http_method GET, POST, etc.
76  * \param get_params URI argument list passed with the HTTP request.
77  * \param headers HTTP request header-name/value pair list
78  *
79  * \note Should use the ast_http_send() function for sending content
80  * allocated with ast_str and/or content from an opened file descriptor.
81  *
82  * Status and status text should be sent as arguments to the ast_http_send()
83  * function to reflect the status of the request (200 or 304, for example).
84  * Content length is calculated by ast_http_send() automatically.
85  *
86  * Static content may be indicated to the ast_http_send() function,
87  * to indicate that it may be cached.
88  *
89  * For a need authentication response, the ast_http_auth() function
90  * should be used.
91  *
92  * For an error response, the ast_http_error() function should be used.
93  *
94  * \retval 0 Continue and process the next HTTP request.
95  * \retval -1 Fatal HTTP connection error.  Force the HTTP connection closed.
96  */
97 typedef int (*ast_http_callback)(struct ast_tcptls_session_instance *ser, const struct ast_http_uri *urih, const char *uri, enum ast_http_method method, struct ast_variable *get_params, struct ast_variable *headers);
98
99 /*! \brief Definition of a URI handler */
100 struct ast_http_uri {
101         AST_LIST_ENTRY(ast_http_uri) entry;
102         const char *description;
103         const char *uri;
104         ast_http_callback callback;
105         unsigned int has_subtree:1;
106         /*! Structure is malloc'd */
107         unsigned int mallocd:1;
108         /*! Data structure is malloc'd */
109         unsigned int dmallocd:1;
110         /*! Don't automatically decode URI before passing it to the callback */
111         unsigned int no_decode_uri:1;
112         /*! Data to bind to the uri if needed */
113         void *data;
114         /*! Key to be used for unlinking if multiple URIs registered */
115         const char *key;
116 };
117
118 /*! \brief Get cookie from Request headers */
119 struct ast_variable *ast_http_get_cookies(struct ast_variable *headers);
120
121 /*! \brief HTTP authentication information. */
122 struct ast_http_auth {
123         /*! Provided userid. */
124         char *userid;
125         /*! For Basic auth, the provided password. */
126         char *password;
127 };
128
129 /*!
130  * \brief Get HTTP authentication information from headers.
131  *
132  * The returned object is AO2 managed, so clean up with ao2_cleanup().
133  *
134  * \param headers HTTP request headers.
135  * \return HTTP auth structure.
136  * \return \c NULL if no supported HTTP auth headers present.
137  * \since 12
138  */
139 struct ast_http_auth *ast_http_get_auth(struct ast_variable *headers);
140
141 /*! \brief Register a URI handler */
142 int ast_http_uri_link(struct ast_http_uri *urihandler);
143
144 /*! \brief Unregister a URI handler */
145 void ast_http_uri_unlink(struct ast_http_uri *urihandler);
146
147 /*! \brief Unregister all handlers with matching key */
148 void ast_http_uri_unlink_all_with_key(const char *key);
149
150 /*!
151  * \brief Return http method name string
152  * \since 1.8
153  */
154 const char *ast_get_http_method(enum ast_http_method method) attribute_pure;
155
156 /*!
157  * \brief Return mime type based on extension
158  * \param ftype filename extension
159  * \return String containing associated MIME type
160  * \since 1.8
161  */
162 const char *ast_http_ftype2mtype(const char *ftype) attribute_pure;
163
164 /*!
165  * \brief Return manager id, if exist, from request headers
166  * \param headers List of HTTP headers
167  * \return 32-bit associated manager session identifier
168  * \since 1.8
169  */
170 uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure;
171
172 /*!
173  * \brief Generic function for sending HTTP/1.1 response.
174  * \param ser TCP/TLS session object
175  * \param method GET/POST/HEAD
176  * \param status_code HTTP response code (200/401/403/404/500)
177  * \param status_title English equivalent to the status_code parameter
178  * \param http_header An ast_str object containing all headers
179  * \param out An ast_str object containing the body of the response
180  * \param fd If out is NULL, a file descriptor where the body of the response is held (otherwise -1)
181  * \param static_content Zero if the content is dynamically generated and should not be cached; nonzero otherwise
182  *
183  * \note Function determines the HTTP response header from status_code,
184  * status_header, and http_header.
185  *
186  * Extra HTTP headers MUST be present only in the http_header argument.  The
187  * argument "out" should contain only content of the response (no headers!).
188  *
189  * HTTP content can be constructed from the argument "out", if it is not NULL;
190  * otherwise, the function will read content from FD.
191  *
192  * This function calculates the content-length http header itself.
193  *
194  * Both the http_header and out arguments will be freed by this function;
195  * however, if FD is open, it will remain open.
196  *
197  * \since 1.8
198  */
199 void ast_http_send(struct ast_tcptls_session_instance *ser, enum ast_http_method method,
200         int status_code, const char *status_title, struct ast_str *http_header,
201         struct ast_str *out, int fd, unsigned int static_content);
202
203 /*!
204  * \brief Creates and sends a formatted http response message.
205  * \param ser                   TCP/TLS session object
206  * \param status_code           HTTP response code (200/401/403/404/500)
207  * \param status_title          English equivalent to the status_code parameter
208  * \param http_header_data      The formatted text to use in the http header
209  * \param text                  Additional informational text to use in the
210  *                              response
211  *
212  * \note Function constructs response headers from the status_code, status_title and
213  * http_header_data parameters.
214  *
215  * The response body is created as HTML content, from the status_code,
216  * status_title, and the text parameters.
217  *
218  * The http_header_data parameter will be freed as a result of calling function.
219  *
220  * \since 13.2.0
221  */
222 void ast_http_create_response(struct ast_tcptls_session_instance *ser, int status_code,
223         const char *status_title, struct ast_str *http_header_data, const char *text);
224
225 /*! \brief Send http "401 Unauthorized" response and close socket */
226 void ast_http_auth(struct ast_tcptls_session_instance *ser, const char *realm, const unsigned long nonce, const unsigned long opaque, int stale, const char *text);
227
228 /*! \brief Send HTTP error message and close socket */
229 void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const char *title, const char *text);
230
231 /*!
232  * \brief Return the current prefix
233  * \param[out] buf destination buffer for previous
234  * \param[in] len length of prefix to copy
235  * \since 1.6.1
236  */
237 void ast_http_prefix(char *buf, int len);
238
239 /*!
240  * \brief Request the HTTP connection be closed after this HTTP request.
241  * \since 12.4.0
242  *
243  * \param ser HTTP TCP/TLS session object.
244  *
245  * \note Call before ast_http_error() to make the connection close.
246  *
247  * \return Nothing
248  */
249 void ast_http_request_close_on_completion(struct ast_tcptls_session_instance *ser);
250
251 /*!
252  * \brief Update the body read success status.
253  * \since 12.4.0
254  *
255  * \param ser HTTP TCP/TLS session object.
256  * \param read_success TRUE if body was read successfully.
257  *
258  * \return Nothing
259  */
260 void ast_http_body_read_status(struct ast_tcptls_session_instance *ser, int read_success);
261
262 /*!
263  * \brief Read and discard any unread HTTP request body.
264  * \since 12.4.0
265  *
266  * \param ser HTTP TCP/TLS session object.
267  *
268  * \retval 0 on success.
269  * \retval -1 on error.
270  */
271 int ast_http_body_discard(struct ast_tcptls_session_instance *ser);
272
273 /*!
274  * \brief Get post variables from client Request Entity-Body, if content type is application/x-www-form-urlencoded.
275  * \param ser TCP/TLS session object
276  * \param headers List of HTTP headers
277  * \return List of variables within the POST body
278  * \note Since returned list is malloc'd, list should be free'd by the calling function
279  * \since 1.8
280  */
281 struct ast_variable *ast_http_get_post_vars(struct ast_tcptls_session_instance *ser, struct ast_variable *headers);
282
283 struct ast_json;
284
285 /*!
286  * \brief Get JSON from client Request Entity-Body, if content type is
287  *        application/json.
288  * \param ser TCP/TLS session object
289  * \param headers List of HTTP headers
290  * \return Parsed JSON content body
291  * \return \c NULL on error, if no content, or if different content type.
292  * \since 12
293  */
294 struct ast_json *ast_http_get_json(
295         struct ast_tcptls_session_instance *ser, struct ast_variable *headers);
296
297 /*!\brief Parse the http response status line.
298  *
299  * \param buf the http response line information
300  * \param version the expected http version (e.g. HTTP/1.1)
301  * \param code the expected status code
302  * \return -1 if version didn't match or status code conversion fails.
303  * \return status code (>0)
304  * \since 13
305  */
306 int ast_http_response_status_line(const char *buf, const char *version, int code);
307
308 /*!\brief Parse a header into the given name/value strings.
309  *
310  * \note This modifies the given buffer and the out parameters point (not
311  *       allocated) to the start of the header name and header value,
312  *       respectively.
313  *
314  * \param buf a string containing the name/value to point to
315  * \param name out parameter pointing to the header name
316  * \param value out parameter pointing to header value
317  * \return -1 if buf is empty
318  * \return 0 if buf could be separated into into name and value
319  * \return 1 if name or value portion don't exist
320  * \since 13
321  */
322 int ast_http_header_parse(char *buf, char **name, char **value);
323
324 /*!\brief Check if the header and value match (case insensitive) their
325  *        associated expected values.
326  *
327  * \param name header name to check
328  * \param expected_name the expected name of the header
329  * \param value header value to check
330  * \param expected_value the expected value of the header
331  * \return 0 if the name and expected name do not match
332  * \return -1 if the value and expected value do not match
333  * \return 1 if the both the name and value match their expected value
334  * \since 13
335  */
336 int ast_http_header_match(const char *name, const char *expected_name,
337                           const char *value, const char *expected_value);
338
339 /*!\brief Check if the header name matches the expected header name.  If so,
340  *        then check to see if the value can be located in the expected value.
341  *
342  * \note Both header and value checks are case insensitive.
343  *
344  * \param name header name to check
345  * \param expected_name the expected name of the header
346  * \param value header value to check if in expected value
347  * \param expected_value the expected value(s)
348  * \return 0 if the name and expected name do not match
349  * \return -1 if the value and is not in the expected value
350  * \return 1 if the name matches expected name and value is in expected value
351  * \since 13
352  */
353 int ast_http_header_match_in(const char *name, const char *expected_name,
354                              const char *value, const char *expected_value);
355
356 #endif /* _ASTERISK_SRV_H */