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
  56 /*! \brief HTTP Callbacks take the socket
  57
  58    \note The method and the path as arguments and should
  59    return the content, allocated with malloc().  Status should be changed to reflect
  60    the status of the request if it isn't 200 and title may be set to a malloc()'d string
  61    to an appropriate title for non-200 responses.  Content length may also be specified.
  62 \verbatim
  63    The return value may include additional headers at the front and MUST include a blank
  64    line with \r\n to provide separation between user headers and content (even if no
  65    content is specified)
  66 \endverbatim
  67 */
  68
  69 enum ast_http_method {
  70         AST_HTTP_GET = 0,
  71         AST_HTTP_POST,
  72 };
  73 struct ast_http_uri;
  74
  75 typedef struct ast_str *(*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 *params, struct ast_variable *headers, int *status, char **title, int *contentlength);
  76
  77 /*! \brief Definition of a URI handler */
  78 struct ast_http_uri {
  79         AST_LIST_ENTRY(ast_http_uri) entry;
  80         const char *description;
  81         const char *uri;
  82         ast_http_callback callback;
  83         unsigned int has_subtree:1;
  84         /*! This handler serves static content */
  85         unsigned int static_content:1;
  86         /*! This handler accepts GET requests */
  87         unsigned int supports_get:1;
  88         /*! This handler accepts POST requests */
  89         unsigned int supports_post:1;
  90         /*! Structure is malloc'd */
  91         unsigned int mallocd:1;
  92         /*! Data structure is malloc'd */
  93         unsigned int dmallocd:1;
  94         /*! Data to bind to the uri if needed */
  95         void *data;
  96         /*! Key to be used for unlinking if multiple URIs registered */
  97         const char *key;
  98 };
  99
 100 /*! \brief Register a URI handler */
 101 int ast_http_uri_link(struct ast_http_uri *urihandler);
 102
 103 /*! \brief Unregister a URI handler */
 104 void ast_http_uri_unlink(struct ast_http_uri *urihandler);
 105
 106 /*! \brief Unregister all handlers with matching key */
 107 void ast_http_uri_unlink_all_with_key(const char *key);
 108
 109 /*! \brief Return an ast_str malloc()'d string containing an HTTP error message */
 110 struct ast_str *ast_http_error(int status, const char *title, const char *extra_header, const char *text);
 111
 112 /*! \brief Return the current prefix */
 113 void ast_http_prefix(char *buf, int len);
 114
 115 #endif /* _ASTERISK_SRV_H */