Merge "app_voicemail.c: Support multiple file formats for forwarded messages."
[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         const char *prefix;
105         ast_http_callback callback;
106         unsigned int has_subtree:1;
107         /*! Structure is malloc'd */
108         unsigned int mallocd:1;
109         /*! Data structure is malloc'd */
110         unsigned int dmallocd:1;
111         /*! Don't automatically decode URI before passing it to the callback */
112         unsigned int no_decode_uri:1;
113         /*! Data to bind to the uri if needed */
114         void *data;
115         /*! Key to be used for unlinking if multiple URIs registered */
116         const char *key;
117 };
118
119 /*! \brief Get cookie from Request headers */
120 struct ast_variable *ast_http_get_cookies(struct ast_variable *headers);
121
122 /*! \brief HTTP authentication information. */
123 struct ast_http_auth {
124         /*! Provided userid. */
125         char *userid;
126         /*! For Basic auth, the provided password. */
127         char *password;
128 };
129
130 /*!
131  * \brief Get HTTP authentication information from headers.
132  *
133  * The returned object is AO2 managed, so clean up with ao2_cleanup().
134  *
135  * \param headers HTTP request headers.
136  * \return HTTP auth structure.
137  * \return \c NULL if no supported HTTP auth headers present.
138  * \since 12
139  */
140 struct ast_http_auth *ast_http_get_auth(struct ast_variable *headers);
141
142 /*! \brief Register a URI handler */
143 int ast_http_uri_link(struct ast_http_uri *urihandler);
144
145 /*! \brief Unregister a URI handler */
146 void ast_http_uri_unlink(struct ast_http_uri *urihandler);
147
148 /*! \brief Unregister all handlers with matching key */
149 void ast_http_uri_unlink_all_with_key(const char *key);
150
151 /*!
152  * \brief Return http method name string
153  * \since 1.8
154  */
155 const char *ast_get_http_method(enum ast_http_method method) attribute_pure;
156
157 /*!
158  * \brief Return mime type based on extension
159  * \param ftype filename extension
160  * \return String containing associated MIME type
161  * \since 1.8
162  */
163 const char *ast_http_ftype2mtype(const char *ftype) attribute_pure;
164
165 /*!
166  * \brief Return manager id, if exist, from request headers
167  * \param headers List of HTTP headers
168  * \return 32-bit associated manager session identifier
169  * \since 1.8
170  */
171 uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure;
172
173 /*!
174  * \brief Generic function for sending HTTP/1.1 response.
175  * \param ser TCP/TLS session object
176  * \param method GET/POST/HEAD
177  * \param status_code HTTP response code (200/401/403/404/500)
178  * \param status_title English equivalent to the status_code parameter
179  * \param http_header An ast_str object containing all headers
180  * \param out An ast_str object containing the body of the response
181  * \param fd If out is NULL, a file descriptor where the body of the response is held (otherwise -1)
182  * \param static_content Zero if the content is dynamically generated and should not be cached; nonzero otherwise
183  *
184  * \note Function determines the HTTP response header from status_code,
185  * status_header, and http_header.
186  *
187  * Extra HTTP headers MUST be present only in the http_header argument.  The
188  * argument "out" should contain only content of the response (no headers!).
189  *
190  * HTTP content can be constructed from the argument "out", if it is not NULL;
191  * otherwise, the function will read content from FD.
192  *
193  * This function calculates the content-length http header itself.
194  *
195  * Both the http_header and out arguments will be freed by this function;
196  * however, if FD is open, it will remain open.
197  *
198  * \since 1.8
199  */
200 void ast_http_send(struct ast_tcptls_session_instance *ser, enum ast_http_method method,
201         int status_code, const char *status_title, struct ast_str *http_header,
202         struct ast_str *out, int fd, unsigned int static_content);
203
204 /*!
205  * \brief Creates and sends a formatted http response message.
206  * \param ser                   TCP/TLS session object
207  * \param status_code           HTTP response code (200/401/403/404/500)
208  * \param status_title          English equivalent to the status_code parameter
209  * \param http_header_data      The formatted text to use in the http header
210  * \param text                  Additional informational text to use in the
211  *                              response
212  *
213  * \note Function constructs response headers from the status_code, status_title and
214  * http_header_data parameters.
215  *
216  * The response body is created as HTML content, from the status_code,
217  * status_title, and the text parameters.
218  *
219  * The http_header_data parameter will be freed as a result of calling function.
220  *
221  * \since 13.2.0
222  */
223 void ast_http_create_response(struct ast_tcptls_session_instance *ser, int status_code,
224         const char *status_title, struct ast_str *http_header_data, const char *text);
225
226 /*! \brief Send http "401 Unauthorized" response and close socket */
227 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);
228
229 /*! \brief Send HTTP error message and close socket */
230 void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const char *title, const char *text);
231
232 /*!
233  * \brief Return the current prefix
234  * \param[out] buf destination buffer for previous
235  * \param[in] len length of prefix to copy
236  * \since 1.6.1
237  */
238 void ast_http_prefix(char *buf, int len);
239
240 /*!
241  * \brief Request the HTTP connection be closed after this HTTP request.
242  * \since 12.4.0
243  *
244  * \param ser HTTP TCP/TLS session object.
245  *
246  * \note Call before ast_http_error() to make the connection close.
247  *
248  * \return Nothing
249  */
250 void ast_http_request_close_on_completion(struct ast_tcptls_session_instance *ser);
251
252 /*!
253  * \brief Update the body read success status.
254  * \since 12.4.0
255  *
256  * \param ser HTTP TCP/TLS session object.
257  * \param read_success TRUE if body was read successfully.
258  *
259  * \return Nothing
260  */
261 void ast_http_body_read_status(struct ast_tcptls_session_instance *ser, int read_success);
262
263 /*!
264  * \brief Read and discard any unread HTTP request body.
265  * \since 12.4.0
266  *
267  * \param ser HTTP TCP/TLS session object.
268  *
269  * \retval 0 on success.
270  * \retval -1 on error.
271  */
272 int ast_http_body_discard(struct ast_tcptls_session_instance *ser);
273
274 /*!
275  * \brief Get post variables from client Request Entity-Body, if content type is application/x-www-form-urlencoded.
276  * \param ser TCP/TLS session object
277  * \param headers List of HTTP headers
278  * \return List of variables within the POST body
279  * \note Since returned list is malloc'd, list should be free'd by the calling function
280  * \since 1.8
281  */
282 struct ast_variable *ast_http_get_post_vars(struct ast_tcptls_session_instance *ser, struct ast_variable *headers);
283
284 struct ast_json;
285
286 /*!
287  * \brief Get JSON from client Request Entity-Body, if content type is
288  *        application/json.
289  * \param ser TCP/TLS session object
290  * \param headers List of HTTP headers
291  * \return Parsed JSON content body
292  * \return \c NULL on error, if no content, or if different content type.
293  * \since 12
294  */
295 struct ast_json *ast_http_get_json(
296         struct ast_tcptls_session_instance *ser, struct ast_variable *headers);
297
298 /*!\brief Parse the http response status line.
299  *
300  * \param buf the http response line information
301  * \param version the expected http version (e.g. HTTP/1.1)
302  * \param code the expected status code
303  * \return -1 if version didn't match or status code conversion fails.
304  * \return status code (>0)
305  * \since 13
306  */
307 int ast_http_response_status_line(const char *buf, const char *version, int code);
308
309 /*!\brief Parse a header into the given name/value strings.
310  *
311  * \note This modifies the given buffer and the out parameters point (not
312  *       allocated) to the start of the header name and header value,
313  *       respectively.
314  *
315  * \param buf a string containing the name/value to point to
316  * \param name out parameter pointing to the header name
317  * \param value out parameter pointing to header value
318  * \return -1 if buf is empty
319  * \return 0 if buf could be separated into name and value
320  * \return 1 if name or value portion don't exist
321  * \since 13
322  */
323 int ast_http_header_parse(char *buf, char **name, char **value);
324
325 /*!\brief Check if the header and value match (case insensitive) their
326  *        associated expected values.
327  *
328  * \param name header name to check
329  * \param expected_name the expected name of the header
330  * \param value header value to check
331  * \param expected_value the expected value of the header
332  * \return 0 if the name and expected name do not match
333  * \return -1 if the value and expected value do not match
334  * \return 1 if the both the name and value match their expected value
335  * \since 13
336  */
337 int ast_http_header_match(const char *name, const char *expected_name,
338                           const char *value, const char *expected_value);
339
340 /*!\brief Check if the header name matches the expected header name.  If so,
341  *        then check to see if the value can be located in the expected value.
342  *
343  * \note Both header and value checks are case insensitive.
344  *
345  * \param name header name to check
346  * \param expected_name the expected name of the header
347  * \param value header value to check if in expected value
348  * \param expected_value the expected value(s)
349  * \return 0 if the name and expected name do not match
350  * \return -1 if the value and is not in the expected value
351  * \return 1 if the name matches expected name and value is in expected value
352  * \since 13
353  */
354 int ast_http_header_match_in(const char *name, const char *expected_name,
355                              const char *value, const char *expected_value);
356
357 #endif /* _ASTERISK_SRV_H */