00001 /* 00002 * Asterisk -- An open source telephony toolkit. 00003 * 00004 * Copyright (C) 1999 - 2006, Digium, Inc. 00005 * 00006 * Mark Spencer <markster@digium.com> 00007 * 00008 * See http://www.asterisk.org for more information about 00009 * the Asterisk project. Please do not directly contact 00010 * any of the maintainers of this project for assistance; 00011 * the project provides a web site, mailing lists and IRC 00012 * channels for your use. 00013 * 00014 * This program is free software, distributed under the terms of 00015 * the GNU General Public License Version 2. See the LICENSE file 00016 * at the top of the source tree. 00017 */ 00018 00019 #ifndef _ASTERISK_HTTP_H 00020 #define _ASTERISK_HTTP_H 00021 00022 #include "asterisk/config.h" 00023 #include "asterisk/tcptls.h" 00024 #include "asterisk/linkedlists.h" 00025 00026 /*! 00027 * \file http.h 00028 * \brief Support for Private Asterisk HTTP Servers. 00029 * \note Note: The Asterisk HTTP servers are extremely simple and minimal and 00030 * only support the "GET" method. 00031 * 00032 * \author Mark Spencer <markster@digium.com> 00033 * 00034 * \note In order to have TLS/SSL support, we need the openssl libraries. 00035 * Still we can decide whether or not to use them by commenting 00036 * in or out the DO_SSL macro. 00037 * TLS/SSL support is basically implemented by reading from a config file 00038 * (currently http.conf) the names of the certificate and cipher to use, 00039 * and then run ssl_setup() to create an appropriate SSL_CTX (ssl_ctx) 00040 * If we support multiple domains, presumably we need to read multiple 00041 * certificates. 00042 * When we are requested to open a TLS socket, we run make_file_from_fd() 00043 * on the socket, to do the necessary setup. At the moment the context's name 00044 * is hardwired in the function, but we can certainly make it into an extra 00045 * parameter to the function. 00046 * We declare most of ssl support variables unconditionally, 00047 * because their number is small and this simplifies the code. 00048 * 00049 * \note: the ssl-support variables (ssl_ctx, do_ssl, certfile, cipher) 00050 * and their setup should be moved to a more central place, e.g. asterisk.conf 00051 * and the source files that processes it. Similarly, ssl_setup() should 00052 * be run earlier in the startup process so modules have it available. 00053 */ 00054 00055 /*! \brief HTTP Request methods known by Asterisk */ 00056 enum ast_http_method { 00057 AST_HTTP_UNKNOWN = -1, /*!< Unknown response */ 00058 AST_HTTP_GET = 0, 00059 AST_HTTP_POST, 00060 AST_HTTP_HEAD, 00061 AST_HTTP_PUT, /*!< Not supported in Asterisk */ 00062 }; 00063 00064 struct ast_http_uri; 00065 00066 /*! \brief HTTP Callbacks 00067 * 00068 * \note The callback function receives server instance, uri, http method, 00069 * get method (if present in URI), and http headers as arguments and should 00070 * use the ast_http_send() function for sending content allocated with ast_str 00071 * and/or content from an opened file descriptor. 00072 * 00073 * Status and status text should be sent as arguments to the ast_http_send() 00074 * function to reflect the status of the request (200 or 304, for example). 00075 * Content length is calculated by ast_http_send() automatically. 00076 * 00077 * Static content may be indicated to the ast_http_send() function, to indicate 00078 * that it may be cached. 00079 * 00080 * \verbatim 00081 * The return value may include additional headers at the front and MUST 00082 * include a blank line with \r\n to provide separation between user headers 00083 * and content (even if no content is specified) 00084 * \endverbatim 00085 * 00086 * For an error response, the ast_http_error() function may be used. 00087 */ 00088 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); 00089 00090 /*! \brief Definition of a URI handler */ 00091 struct ast_http_uri { 00092 AST_LIST_ENTRY(ast_http_uri) entry; 00093 const char *description; 00094 const char *uri; 00095 ast_http_callback callback; 00096 unsigned int has_subtree:1; 00097 /*! Structure is malloc'd */ 00098 unsigned int mallocd:1; 00099 /*! Data structure is malloc'd */ 00100 unsigned int dmallocd:1; 00101 /*! Data to bind to the uri if needed */ 00102 void *data; 00103 /*! Key to be used for unlinking if multiple URIs registered */ 00104 const char *key; 00105 }; 00106 00107 /*! \brief Get cookie from Request headers */ 00108 struct ast_variable *ast_http_get_cookies(struct ast_variable *headers); 00109 00110 /*! \brief Register a URI handler */ 00111 int ast_http_uri_link(struct ast_http_uri *urihandler); 00112 00113 /*! \brief Unregister a URI handler */ 00114 void ast_http_uri_unlink(struct ast_http_uri *urihandler); 00115 00116 /*! \brief Unregister all handlers with matching key */ 00117 void ast_http_uri_unlink_all_with_key(const char *key); 00118 00119 /*!\brief Return http method name string 00120 * \since 1.8 00121 */ 00122 const char *ast_get_http_method(enum ast_http_method method) attribute_pure; 00123 00124 /*!\brief Return mime type based on extension 00125 * \param ftype filename extension 00126 * \return String containing associated MIME type 00127 * \since 1.8 00128 */ 00129 const char *ast_http_ftype2mtype(const char *ftype) attribute_pure; 00130 00131 /*!\brief Return manager id, if exist, from request headers 00132 * \param headers List of HTTP headers 00133 * \return 32-bit associated manager session identifier 00134 * \since 1.8 00135 */ 00136 uint32_t ast_http_manid_from_vars(struct ast_variable *headers) attribute_pure; 00137 00138 /*! \brief Generic function for sending http/1.1 response. 00139 * \param ser TCP/TLS session object 00140 * \param method GET/POST/HEAD 00141 * \param status_code HTTP response code (200/401/403/404/500) 00142 * \param status_title English equivalent to the status_code parameter 00143 * \param http_header An ast_str object containing all headers 00144 * \param out An ast_str object containing the body of the response 00145 * \param fd If out is NULL, a file descriptor where the body of the response is held (otherwise -1) 00146 * \param static_content Zero if the content is dynamically generated and should not be cached; nonzero otherwise 00147 * 00148 * \note Function determines the HTTP response header from status_code, 00149 * status_header, and http_header. 00150 * 00151 * Extra HTTP headers MUST be present only in the http_header argument. The 00152 * argument "out" should contain only content of the response (no headers!). 00153 * 00154 * HTTP content can be constructed from the argument "out", if it is not NULL; 00155 * otherwise, the function will read content from FD. 00156 * 00157 * This function calculates the content-length http header itself. 00158 * 00159 * Both the http_header and out arguments will be freed by this function; 00160 * however, if FD is open, it will remain open. 00161 * 00162 * \since 1.8 00163 */ 00164 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); 00165 00166 /*!\brief Send http "401 Unauthorized" response and close socket */ 00167 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); 00168 00169 /*!\brief Send HTTP error message and close socket */ 00170 void ast_http_error(struct ast_tcptls_session_instance *ser, int status, const char *title, const char *text); 00171 00172 /*! 00173 * \brief Return the current prefix 00174 * \param[out] buf destination buffer for previous 00175 * \param[in] len length of prefix to copy 00176 * \since 1.6.1 00177 */ 00178 void ast_http_prefix(char *buf, int len); 00179 00180 00181 /*!\brief Get post variables from client Request Entity-Body, if content type is application/x-www-form-urlencoded. 00182 * \param ser TCP/TLS session object 00183 * \param headers List of HTTP headers 00184 * \return List of variables within the POST body 00185 * \note Since returned list is malloc'd, list should be free'd by the calling function 00186 * \since 1.8 00187 */ 00188 struct ast_variable *ast_http_get_post_vars(struct ast_tcptls_session_instance *ser, struct ast_variable *headers); 00189 00190 00191 #endif /* _ASTERISK_SRV_H */