Wed Aug 18 22:33:52 2010

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 
00056 /*! \brief HTTP Callbacks take the socket
00057 
00058    \note The method and the path as arguments and should
00059    return the content, allocated with malloc().  Status should be changed to reflect
00060    the status of the request if it isn't 200 and title may be set to a malloc()'d string
00061    to an appropriate title for non-200 responses.  Content length may also be specified.
00062 \verbatim
00063    The return value may include additional headers at the front and MUST include a blank
00064    line with \r\n to provide separation between user headers and content (even if no
00065    content is specified)
00066 \endverbatim
00067 */
00068 
00069 enum ast_http_method {
00070    AST_HTTP_GET = 0,
00071    AST_HTTP_POST,
00072 };
00073 struct ast_http_uri;
00074 
00075 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);
00076 
00077 /*! \brief Definition of a URI handler */
00078 struct ast_http_uri {
00079    AST_LIST_ENTRY(ast_http_uri) entry;
00080    const char *description;
00081    const char *uri;
00082    ast_http_callback callback;
00083    unsigned int has_subtree:1;
00084    /*! This handler serves static content */
00085    unsigned int static_content:1;
00086    /*! This handler accepts GET requests */
00087    unsigned int supports_get:1;
00088    /*! This handler accepts POST requests */
00089    unsigned int supports_post:1;
00090    /*! Structure is malloc'd */
00091    unsigned int mallocd:1;
00092    /*! Data structure is malloc'd */
00093    unsigned int dmallocd:1;
00094    /*! Data to bind to the uri if needed */
00095    void *data;
00096    /*! Key to be used for unlinking if multiple URIs registered */
00097    const char *key;
00098 };
00099 
00100 /*! \brief Register a URI handler */
00101 int ast_http_uri_link(struct ast_http_uri *urihandler);
00102 
00103 /*! \brief Unregister a URI handler */
00104 void ast_http_uri_unlink(struct ast_http_uri *urihandler);
00105 
00106 /*! \brief Unregister all handlers with matching key */
00107 void ast_http_uri_unlink_all_with_key(const char *key);
00108 
00109 /*! \brief Return an ast_str malloc()'d string containing an HTTP error message */
00110 struct ast_str *ast_http_error(int status, const char *title, const char *extra_header, const char *text);
00111 
00112 /*!
00113  * \brief Return the current prefix
00114  * \param buf[out] destination buffer for previous
00115  * \param len[in] length of prefix to copy
00116  * \since 1.6.1
00117  */
00118 void ast_http_prefix(char *buf, int len);
00119 
00120 #endif /* _ASTERISK_SRV_H */

Generated on Wed Aug 18 22:33:52 2010 for Asterisk - the Open Source PBX by  doxygen 1.4.7