Thu Oct 11 06:33:48 2012

Asterisk developer's documentation


http.h

Go to the documentation of this file.
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 */

Generated on Thu Oct 11 06:33:48 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6