Shuffle RESTful URL's around.
[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 /*! \brief HTTP Callbacks
70  *
71  * \note The callback function receives server instance, uri, http method,
72  * get method (if present in URI), and http headers as arguments and should
73  * use the ast_http_send() function for sending content allocated with ast_str
74  * and/or content from an opened file descriptor.
75  *
76  * Status and status text should be sent as arguments to the ast_http_send()
77  * function to reflect the status of the request (200 or 304, for example).
78  * Content length is calculated by ast_http_send() automatically.
79  *
80  * Static content may be indicated to the ast_http_send() function, to indicate
81  * that it may be cached.
82  *
83  * \verbatim
84  * The return value may include additional headers at the front and MUST
85  * include a blank line with \r\n to provide separation between user headers
86  * and content (even if no content is specified)
87  * \endverbatim
88  *
89  * For an error response, the ast_http_error() function may be used.
90 */
91 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);
92
93 /*! \brief Definition of a URI handler */
94 struct ast_http_uri {
95         AST_LIST_ENTRY(ast_http_uri) entry;
96         const char *description;
97         const char *uri;
98         ast_http_callback callback;
99         unsigned int has_subtree:1;
100         /*! Structure is malloc'd */
101         unsigned int mallocd:1;
102         /*! Data structure is malloc'd */
103         unsigned int dmallocd:1;
104         /*! Don't automatically decode URI before passing it to the callback */
105         unsigned int no_decode_uri:1;
106         /*! Data to bind to the uri if needed */
107         void *data;
108         /*! Key to be used for unlinking if multiple URIs registered */
109         const char *key;
110 };
111
112 /*! \brief Get cookie from Request headers */
113 struct ast_variable *ast_http_get_cookies(struct ast_variable *headers);
114
115 /*! \brief HTTP authentication information. */
116 struct ast_http_auth {
117         /*! Provided userid. */
118         char *userid;
119         /*! For Basic auth, the provided password. */
120         char *password;
121 };
122
123 /*!
124  * \brief Get HTTP authentication information from headers.
125  *
126  * The returned object is AO2 managed, so clean up with ao2_cleanup().
127  *
128  * \param headers HTTP request headers.
129  * \return HTTP auth structure.
130  * \return \c NULL if no supported HTTP auth headers present.
131  * \since 12
132  */
133 struct ast_http_auth *ast_http_get_auth(struct ast_variable *headers);
134
135 /*! \brief Register a URI handler */
136 int ast_http_uri_link(struct ast_http_uri *urihandler);
137
138 /*! \brief Unregister a URI handler */
139 void ast_http_uri_unlink(struct ast_http_uri *urihandler);
140
141 /*! \brief Unregister all handlers with matching key */
142 void ast_http_uri_unlink_all_with_key(const char *key);
143
144 /*!\brief Return http method name string
145  * \since 1.8
146  */
147 const char *ast_get_http_method(enum ast_http_method method) attribute_pure;
148
149 /*!\brief Return mime type based on extension
150  * \param ftype filename extension
151  * \return String containing associated MIME type
152  * \since 1.8
153  */
154 const char *ast_http_ftype2mtype(const char *ftype) attribute_pure;
155
156 /*!\brief Return manager id, if exist, from request headers
157  * \param headers List of HTTP headers
158  * \return 32-bit associated manager session identifier
159  * \since 1.8
160  */
161 uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure;
162
163 /*! \brief Generic function for sending http/1.1 response.
164  * \param ser TCP/TLS session object
165  * \param method GET/POST/HEAD
166  * \param status_code HTTP response code (200/401/403/404/500)
167  * \param status_title English equivalent to the status_code parameter
168  * \param http_header An ast_str object containing all headers
169  * \param out An ast_str object containing the body of the response
170  * \param fd If out is NULL, a file descriptor where the body of the response is held (otherwise -1)
171  * \param static_content Zero if the content is dynamically generated and should not be cached; nonzero otherwise
172  *
173  * \note Function determines the HTTP response header from status_code,
174  * status_header, and http_header.
175  *
176  * Extra HTTP headers MUST be present only in the http_header argument.  The
177  * argument "out" should contain only content of the response (no headers!).
178  *
179  * HTTP content can be constructed from the argument "out", if it is not NULL;
180  * otherwise, the function will read content from FD.
181  *
182  * This function calculates the content-length http header itself.
183  *
184  * Both the http_header and out arguments will be freed by this function;
185  * however, if FD is open, it will remain open.
186  *
187  * \since 1.8
188  */
189 void ast_http_send(struct ast_tcptls_session_instance *ser, enum ast_http_method method, int status_code, const char *status_title, struct ast_str *http_header, struct ast_str *out, const int fd, unsigned int static_content);
190
191 /*!\brief Send http "401 Unauthorized" response and close socket */
192 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);
193
194 /*!\brief Send HTTP error message and close socket */
195 void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const char *title, const char *text);
196
197 /*!
198  * \brief Return the current prefix
199  * \param[out] buf destination buffer for previous
200  * \param[in] len length of prefix to copy
201  * \since 1.6.1
202  */
203 void ast_http_prefix(char *buf, int len);
204
205
206 /*!\brief Get post variables from client Request Entity-Body, if content type is application/x-www-form-urlencoded.
207  * \param ser TCP/TLS session object
208  * \param headers List of HTTP headers
209  * \return List of variables within the POST body
210  * \note Since returned list is malloc'd, list should be free'd by the calling function
211  * \since 1.8
212  */
213 struct ast_variable *ast_http_get_post_vars(struct ast_tcptls_session_instance *ser, struct ast_variable *headers);
214
215
216 #endif /* _ASTERISK_SRV_H */