Wed Jan 8 2020 09:49:48

Asterisk developer's documentation


http.h
Go to the documentation of this file.
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 */
57  AST_HTTP_UNKNOWN = -1, /*!< Unknown response */
61  AST_HTTP_PUT, /*!< Not supported in Asterisk */
62 };
63 
64 struct ast_http_uri;
65 
66 /*! \brief HTTP Callbacks
67  *
68  * \note The callback function receives server instance, uri, http method,
69  * get method (if present in URI), and http headers as arguments and should
70  * use the ast_http_send() function for sending content allocated with ast_str
71  * and/or content from an opened file descriptor.
72  *
73  * Status and status text should be sent as arguments to the ast_http_send()
74  * function to reflect the status of the request (200 or 304, for example).
75  * Content length is calculated by ast_http_send() automatically.
76  *
77  * Static content may be indicated to the ast_http_send() function, to indicate
78  * that it may be cached.
79  *
80  * \verbatim
81  * The return value may include additional headers at the front and MUST
82  * include a blank line with \r\n to provide separation between user headers
83  * and content (even if no content is specified)
84  * \endverbatim
85  *
86  * For an error response, the ast_http_error() function may be used.
87 */
88 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);
89 
90 /*! \brief Definition of a URI handler */
91 struct ast_http_uri {
93  const char *description;
94  const char *uri;
96  unsigned int has_subtree:1;
97  /*! Structure is malloc'd */
98  unsigned int mallocd:1;
99  /*! Data structure is malloc'd */
100  unsigned int dmallocd:1;
101  /*! Data to bind to the uri if needed */
102  void *data;
103  /*! Key to be used for unlinking if multiple URIs registered */
104  const char *key;
105 };
106 
107 /*! \brief Get cookie from Request headers */
108 struct ast_variable *ast_http_get_cookies(struct ast_variable *headers);
109 
110 /*! \brief Register a URI handler */
111 int ast_http_uri_link(struct ast_http_uri *urihandler);
112 
113 /*! \brief Unregister a URI handler */
114 void ast_http_uri_unlink(struct ast_http_uri *urihandler);
115 
116 /*! \brief Unregister all handlers with matching key */
117 void ast_http_uri_unlink_all_with_key(const char *key);
118 
119 /*!\brief Return http method name string
120  * \since 1.8
121  */
122 const char *ast_get_http_method(enum ast_http_method method) attribute_pure;
123 
124 /*!\brief Return mime type based on extension
125  * \param ftype filename extension
126  * \return String containing associated MIME type
127  * \since 1.8
128  */
129 const char *ast_http_ftype2mtype(const char *ftype) attribute_pure;
130 
131 /*!\brief Return manager id, if exist, from request headers
132  * \param headers List of HTTP headers
133  * \return 32-bit associated manager session identifier
134  * \since 1.8
135  */
136 uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure;
137 
138 /*! \brief Generic function for sending http/1.1 response.
139  * \param ser TCP/TLS session object
140  * \param method GET/POST/HEAD
141  * \param status_code HTTP response code (200/401/403/404/500)
142  * \param status_title English equivalent to the status_code parameter
143  * \param http_header An ast_str object containing all headers
144  * \param out An ast_str object containing the body of the response
145  * \param fd If out is NULL, a file descriptor where the body of the response is held (otherwise -1)
146  * \param static_content Zero if the content is dynamically generated and should not be cached; nonzero otherwise
147  *
148  * \note Function determines the HTTP response header from status_code,
149  * status_header, and http_header.
150  *
151  * Extra HTTP headers MUST be present only in the http_header argument. The
152  * argument "out" should contain only content of the response (no headers!).
153  *
154  * HTTP content can be constructed from the argument "out", if it is not NULL;
155  * otherwise, the function will read content from FD.
156  *
157  * This function calculates the content-length http header itself.
158  *
159  * Both the http_header and out arguments will be freed by this function;
160  * however, if FD is open, it will remain open.
161  *
162  * \since 1.8
163  */
164 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);
165 
166 /*!\brief Send http "401 Unauthorized" response and close socket */
167 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);
168 
169 /*!\brief Send HTTP error message and close socket */
170 void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const char *title, const char *text);
171 
172 /*!
173  * \brief Return the current prefix
174  * \param[out] buf destination buffer for previous
175  * \param[in] len length of prefix to copy
176  * \since 1.6.1
177  */
178 void ast_http_prefix(char *buf, int len);
179 
180 
181 /*!\brief Get post variables from client Request Entity-Body, if content type is application/x-www-form-urlencoded.
182  * \param ser TCP/TLS session object
183  * \param headers List of HTTP headers
184  * \return List of variables within the POST body
185  * \note Since returned list is malloc'd, list should be free'd by the calling function
186  * \since 1.8
187  */
189 
190 
191 #endif /* _ASTERISK_SRV_H */
#define attribute_pure
Definition: compiler.h:35
void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const char *title, const char *text)
Send HTTP error message and close socket.
Definition: http.c:506
ast_http_callback callback
Definition: http.h:95
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)
Send http &quot;401 Unauthorized&quot; response and close socket.
Definition: http.c:468
int ast_http_uri_link(struct ast_http_uri *urihandler)
Register a URI handler.
Definition: http.c:544
const char * ast_http_ftype2mtype(const char *ftype) attribute_pure
Return mime type based on extension.
Definition: http.c:166
Structure for variables, used for configurations and for channel variables.
Definition: config.h:75
void ast_http_uri_unlink(struct ast_http_uri *urihandler)
Unregister a URI handler.
Definition: http.c:574
Configuration File Parser.
const char * key
Definition: http.h:104
char * text
Definition: app_queue.c:1091
uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure
Return manager id, if exist, from request headers.
Definition: http.c:180
unsigned int has_subtree
Definition: http.h:96
Generic support for tcp/tls servers in Asterisk.
struct ast_http_uri::@175 entry
unsigned int mallocd
Definition: http.h:98
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)
Generic function for sending http/1.1 response.
Definition: http.c:393
A set of macros to manage forward-linked lists.
The descriptor of a dynamic string XXX storage will be optimized later if needed We use the ts field ...
Definition: strings.h:364
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
const char * description
Definition: http.h:93
#define AST_LIST_ENTRY(type)
Declare a forward link structure inside a list entry.
Definition: linkedlists.h:409
const char * ast_get_http_method(enum ast_http_method method) attribute_pure
Return http method name string.
Definition: http.c:153
static size_t get_params(va_list ap, const char ***params_ptr, const char ***vals_ptr, int warn)
Helper function to parse a va_list object into 2 dynamic arrays of strings, parameters and values...
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)
HTTP Callbacks.
Definition: http.h:88
Definition of a URI handler.
Definition: http.h:91
void ast_http_prefix(char *buf, int len)
Return the current prefix.
Definition: http.c:196
struct ast_variable * ast_http_get_post_vars(struct ast_tcptls_session_instance *ser, struct ast_variable *headers)
Get post variables from client Request Entity-Body, if content type is application/x-www-form-urlenco...
Definition: http.c:624
void ast_http_uri_unlink_all_with_key(const char *key)
Unregister all handlers with matching key.
Definition: http.c:581
unsigned int dmallocd
Definition: http.h:100
const char * uri
Definition: http.h:94
ast_http_method
HTTP Request methods known by Asterisk.
Definition: http.h:56
void * data
Definition: http.h:102
jack_status_t status
Definition: app_jack.c:143
struct ast_variable * ast_http_get_cookies(struct ast_variable *headers)
Get cookie from Request headers.
Definition: http.c:862