/usr/include/asterisk/http.h is in asterisk-dev 1:13.1.0~dfsg-1.1ubuntu4.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 | /*
* 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,
AST_HTTP_DELETE,
AST_HTTP_OPTIONS,
AST_HTTP_MAX_METHOD, /*!< Last entry in ast_http_method enum */
};
struct ast_http_uri;
/*!
* \brief HTTP Callbacks
*
* \param ser TCP/TLS session object
* \param urih Registered URI handler struct for the URI.
* \param uri Remaining request URI path (also with the get_params removed).
* \param method enum ast_http_method GET, POST, etc.
* \param get_params URI argument list passed with the HTTP request.
* \param headers HTTP request header-name/value pair list
*
* \note 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.
*
* For a need authentication response, the ast_http_auth() function
* should be used.
*
* For an error response, the ast_http_error() function should be used.
*
* \retval 0 Continue and process the next HTTP request.
* \retval -1 Fatal HTTP connection error. Force the HTTP connection closed.
*/
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;
/*! Don't automatically decode URI before passing it to the callback */
unsigned int no_decode_uri: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 HTTP authentication information. */
struct ast_http_auth {
/*! Provided userid. */
char *userid;
/*! For Basic auth, the provided password. */
char *password;
};
/*!
* \brief Get HTTP authentication information from headers.
*
* The returned object is AO2 managed, so clean up with ao2_cleanup().
*
* \param headers HTTP request headers.
* \return HTTP auth structure.
* \return \c NULL if no supported HTTP auth headers present.
* \since 12
*/
struct ast_http_auth *ast_http_get_auth(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, 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 Request the HTTP connection be closed after this HTTP request.
* \since 12.4.0
*
* \param ser HTTP TCP/TLS session object.
*
* \note Call before ast_http_error() to make the connection close.
*
* \return Nothing
*/
void ast_http_request_close_on_completion(struct ast_tcptls_session_instance *ser);
/*!
* \brief Update the body read success status.
* \since 12.4.0
*
* \param ser HTTP TCP/TLS session object.
* \param read_success TRUE if body was read successfully.
*
* \return Nothing
*/
void ast_http_body_read_status(struct ast_tcptls_session_instance *ser, int read_success);
/*!
* \brief Read and discard any unread HTTP request body.
* \since 12.4.0
*
* \param ser HTTP TCP/TLS session object.
*
* \retval 0 on success.
* \retval -1 on error.
*/
int ast_http_body_discard(struct ast_tcptls_session_instance *ser);
/*!
* \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);
struct ast_json;
/*!
* \brief Get JSON from client Request Entity-Body, if content type is
* application/json.
* \param ser TCP/TLS session object
* \param headers List of HTTP headers
* \return Parsed JSON content body
* \return \c NULL on error, if no content, or if different content type.
* \since 12
*/
struct ast_json *ast_http_get_json(
struct ast_tcptls_session_instance *ser, struct ast_variable *headers);
/*!\brief Parse the http response status line.
*
* \param buf the http response line information
* \param version the expected http version (e.g. HTTP/1.1)
* \param code the expected status code
* \return -1 if version didn't match or status code conversion fails.
* \return status code (>0)
* \since 13
*/
int ast_http_response_status_line(const char *buf, const char *version, int code);
/*!\brief Parse a header into the given name/value strings.
*
* \note This modifies the given buffer and the out parameters point (not
* allocated) to the start of the header name and header value,
* respectively.
*
* \param buf a string containing the name/value to point to
* \param name out parameter pointing to the header name
* \param value out parameter pointing to header value
* \return -1 if buf is empty
* \return 0 if buf could be separated into into name and value
* \return 1 if name or value portion don't exist
* \since 13
*/
int ast_http_header_parse(char *buf, char **name, char **value);
/*!\brief Check if the header and value match (case insensitive) their
* associated expected values.
*
* \param name header name to check
* \param expected_name the expected name of the header
* \param value header value to check
* \param expected_value the expected value of the header
* \return 0 if the name and expected name do not match
* \return -1 if the value and expected value do not match
* \return 1 if the both the name and value match their expected value
* \since 13
*/
int ast_http_header_match(const char *name, const char *expected_name,
const char *value, const char *expected_value);
/*!\brief Check if the header name matches the expected header name. If so,
* then check to see if the value can be located in the expected value.
*
* \note Both header and value checks are case insensitive.
*
* \param name header name to check
* \param expected_name the expected name of the header
* \param value header value to check if in expected value
* \param expected_value the expected value(s)
* \return 0 if the name and expected name do not match
* \return -1 if the value and is not in the expected value
* \return 1 if the name matches expected name and value is in expected value
* \since 13
*/
int ast_http_header_match_in(const char *name, const char *expected_name,
const char *value, const char *expected_value);
#endif /* _ASTERISK_SRV_H */
|