1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
/*
* Asterisk -- An open source telephony toolkit.
*
* Copyright (C) 1999 - 2006, Digium, Inc.
*
* Mark Spencer <markster@digium.com>
*
* See http://www.asterisk.org for more information about
* the Asterisk project. Please do not directly contact
* any of the maintainers of this project for assistance;
* the project provides a web site, mailing lists and IRC
* channels for your use.
*
* This program is free software, distributed under the terms of
* the GNU General Public License Version 2. See the LICENSE file
* at the top of the source tree.
*/
#ifndef _ASTERISK_HTTP_H
#define _ASTERISK_HTTP_H
#include "asterisk/config.h"
#include "asterisk/tcptls.h"
#include "asterisk/linkedlists.h"
/*!
* \file http.h
* \brief Support for Private Asterisk HTTP Servers.
* \note Note: The Asterisk HTTP servers are extremely simple and minimal and
* only support the "GET" method.
*
* \author Mark Spencer <markster@digium.com>
*
* \note In order to have TLS/SSL support, we need the openssl libraries.
* Still we can decide whether or not to use them by commenting
* in or out the DO_SSL macro.
* TLS/SSL support is basically implemented by reading from a config file
* (currently http.conf) the names of the certificate and cipher to use,
* and then run ssl_setup() to create an appropriate SSL_CTX (ssl_ctx)
* If we support multiple domains, presumably we need to read multiple
* certificates.
* When we are requested to open a TLS socket, we run make_file_from_fd()
* on the socket, to do the necessary setup. At the moment the context's name
* is hardwired in the function, but we can certainly make it into an extra
* parameter to the function.
* We declare most of ssl support variables unconditionally,
* because their number is small and this simplifies the code.
*
* \note: the ssl-support variables (ssl_ctx, do_ssl, certfile, cipher)
* and their setup should be moved to a more central place, e.g. asterisk.conf
* and the source files that processes it. Similarly, ssl_setup() should
* be run earlier in the startup process so modules have it available.
*/
/*! \brief HTTP Request methods known by Asterisk */
enum ast_http_method {
AST_HTTP_UNKNOWN = -1, /*!< Unknown response */
AST_HTTP_GET = 0,
AST_HTTP_POST,
AST_HTTP_HEAD,
AST_HTTP_PUT, /*!< Not supported in Asterisk */
};
struct ast_http_uri;
/*! \brief HTTP Callbacks
*
* \note The callback function receives server instance, uri, http method,
* get method (if present in URI), and http headers as arguments and should
* use the ast_http_send() function for sending content allocated with ast_str
* and/or content from an opened file descriptor.
*
* Status and status text should be sent as arguments to the ast_http_send()
* function to reflect the status of the request (200 or 304, for example).
* Content length is calculated by ast_http_send() automatically.
*
* Static content may be indicated to the ast_http_send() function, to indicate
* that it may be cached.
*
* \verbatim
* The return value may include additional headers at the front and MUST
* include a blank line with \r\n to provide separation between user headers
* and content (even if no content is specified)
* \endverbatim
*
* For an error response, the ast_http_error() function may be used.
*/
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);
/*! \brief Definition of a URI handler */
struct ast_http_uri {
AST_LIST_ENTRY(ast_http_uri) entry;
const char *description;
const char *uri;
ast_http_callback callback;
unsigned int has_subtree:1;
/*! Structure is malloc'd */
unsigned int mallocd:1;
/*! Data structure is malloc'd */
unsigned int dmallocd:1;
/*! Data to bind to the uri if needed */
void *data;
/*! Key to be used for unlinking if multiple URIs registered */
const char *key;
};
/*! \brief Get cookie from Request headers */
struct ast_variable *ast_http_get_cookies(struct ast_variable *headers);
/*! \brief Register a URI handler */
int ast_http_uri_link(struct ast_http_uri *urihandler);
/*! \brief Unregister a URI handler */
void ast_http_uri_unlink(struct ast_http_uri *urihandler);
/*! \brief Unregister all handlers with matching key */
void ast_http_uri_unlink_all_with_key(const char *key);
/*!\brief Return http method name string
* \since 1.8
*/
const char *ast_get_http_method(enum ast_http_method method) attribute_pure;
/*!\brief Return mime type based on extension
* \param ftype filename extension
* \return String containing associated MIME type
* \since 1.8
*/
const char *ast_http_ftype2mtype(const char *ftype) attribute_pure;
/*!\brief Return manager id, if exist, from request headers
* \param headers List of HTTP headers
* \return 32-bit associated manager session identifier
* \since 1.8
*/
uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure;
/*! \brief Generic function for sending http/1.1 response.
* \param ser TCP/TLS session object
* \param method GET/POST/HEAD
* \param status_code HTTP response code (200/401/403/404/500)
* \param status_title English equivalent to the status_code parameter
* \param http_header An ast_str object containing all headers
* \param out An ast_str object containing the body of the response
* \param fd If out is NULL, a file descriptor where the body of the response is held (otherwise -1)
* \param static_content Zero if the content is dynamically generated and should not be cached; nonzero otherwise
*
* \note Function determines the HTTP response header from status_code,
* status_header, and http_header.
*
* Extra HTTP headers MUST be present only in the http_header argument. The
* argument "out" should contain only content of the response (no headers!).
*
* HTTP content can be constructed from the argument "out", if it is not NULL;
* otherwise, the function will read content from FD.
*
* This function calculates the content-length http header itself.
*
* Both the http_header and out arguments will be freed by this function;
* however, if FD is open, it will remain open.
*
* \since 1.8
*/
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);
/*!\brief Send http "401 Unauthorized" response and close socket */
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);
/*!\brief Send HTTP error message and close socket */
void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const char *title, const char *text);
/*!
* \brief Return the current prefix
* \param[out] buf destination buffer for previous
* \param[in] len length of prefix to copy
* \since 1.6.1
*/
void ast_http_prefix(char *buf, int len);
/*!\brief Get post variables from client Request Entity-Body, if content type is application/x-www-form-urlencoded.
* \param ser TCP/TLS session object
* \param headers List of HTTP headers
* \return List of variables within the POST body
* \note Since returned list is malloc'd, list should be free'd by the calling function
* \since 1.8
*/
struct ast_variable *ast_http_get_post_vars(struct ast_tcptls_session_instance *ser, struct ast_variable *headers);
#endif /* _ASTERISK_SRV_H */
|
