Fri Jul 24 00:41:46 2009

Asterisk developer's documentation


http.h File Reference

Support for Private Asterisk HTTP Servers. More...

#include "asterisk/config.h"
#include "asterisk/tcptls.h"
#include "asterisk/linkedlists.h"

Go to the source code of this file.

Data Structures

struct  ast_http_uri
 Definition of a URI handler. More...

Typedefs

typedef 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)

Enumerations

enum  ast_http_method { AST_HTTP_GET = 0, AST_HTTP_POST }
 HTTP Callbacks take the socket. More...

Functions

ast_strast_http_error (int status, const char *title, const char *extra_header, const char *text)
 Return an ast_str malloc()'d string containing an HTTP error message.
void ast_http_prefix (char *buf, int len)
 Return the current prefix.
int ast_http_uri_link (struct ast_http_uri *urihandler)
 Register a URI handler.
void ast_http_uri_unlink (struct ast_http_uri *urihandler)
 Unregister a URI handler.
void ast_http_uri_unlink_all_with_key (const char *key)
 Unregister all handlers with matching key.


Detailed Description

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.

: 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.

Definition in file http.h.


Typedef Documentation

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)

Definition at line 75 of file http.h.


Enumeration Type Documentation

enum ast_http_method

HTTP Callbacks take the socket.

Note:
The method and the path as arguments and should return the content, allocated with malloc(). Status should be changed to reflect the status of the request if it isn't 200 and title may be set to a malloc()'d string to an appropriate title for non-200 responses. Content length may also be specified.
   The return value may include additional headers at the front and MUST include a blank
   line with \r\n to provide separation between user headers and content (even if no
   content is specified)
Enumerator:
AST_HTTP_GET 
AST_HTTP_POST 

Definition at line 69 of file http.h.

00069                      {
00070    AST_HTTP_GET = 0,
00071    AST_HTTP_POST,
00072 };


Function Documentation

struct ast_str* ast_http_error ( int  status,
const char *  title,
const char *  extra_header,
const char *  text 
)

Return an ast_str malloc()'d string containing an HTTP error message.

Definition at line 309 of file http.c.

References ast_str_create(), and ast_str_set().

Referenced by handle_uri(), http_post_callback(), httpd_helper_thread(), phoneprov_callback(), and static_callback().

00310 {
00311    struct ast_str *out = ast_str_create(512);
00312 
00313    if (out == NULL) {
00314       return out;
00315    }
00316 
00317    ast_str_set(&out, 0,
00318           "Content-type: text/html\r\n"
00319           "%s"
00320           "\r\n"
00321           "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\r\n"
00322           "<html><head>\r\n"
00323           "<title>%d %s</title>\r\n"
00324           "</head><body>\r\n"
00325           "<h1>%s</h1>\r\n"
00326           "<p>%s</p>\r\n"
00327           "<hr />\r\n"
00328           "<address>Asterisk Server</address>\r\n"
00329           "</body></html>\r\n",
00330           (extra_header ? extra_header : ""), status, title, title, text);
00331 
00332    return out;
00333 }

void ast_http_prefix ( char *  buf,
int  len 
)

Return the current prefix.

Parameters:
buf[out] destination buffer for previous
len[in] length of prefix to copy
Since:
1.6.1

Definition at line 147 of file http.c.

References ast_copy_string().

00148 {
00149    if (buf) {
00150       ast_copy_string(buf, prefix, len);
00151    }
00152 }

int ast_http_uri_link ( struct ast_http_uri urih  ) 

Register a URI handler.

They are sorted by length of the string, not alphabetically. Duplicate entries are not replaced, but the insertion order (using <= and not just <) makes sure that more recent insertions hide older ones. On a lookup, we just scan the list and stop at the first matching entry.

Definition at line 344 of file http.c.

References ast_log(), AST_RWLIST_EMPTY, AST_RWLIST_FIRST, AST_RWLIST_INSERT_AFTER, AST_RWLIST_INSERT_HEAD, AST_RWLIST_INSERT_TAIL, AST_RWLIST_NEXT, AST_RWLIST_TRAVERSE, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_http_uri::description, ast_http_uri::entry, len(), LOG_WARNING, ast_http_uri::supports_get, ast_http_uri::supports_post, and ast_http_uri::uri.

Referenced by __ast_http_post_load(), ast_http_init(), and load_module().

00345 {
00346    struct ast_http_uri *uri;
00347    int len = strlen(urih->uri);
00348 
00349    if (!(urih->supports_get || urih->supports_post)) {
00350       ast_log(LOG_WARNING, "URI handler does not provide either GET or POST method: %s (%s)\n", urih->uri, urih->description);
00351       return -1;
00352    }
00353 
00354    AST_RWLIST_WRLOCK(&uris);
00355 
00356    if (AST_RWLIST_EMPTY(&uris) || strlen(AST_RWLIST_FIRST(&uris)->uri) <= len) {
00357       AST_RWLIST_INSERT_HEAD(&uris, urih, entry);
00358       AST_RWLIST_UNLOCK(&uris);
00359 
00360       return 0;
00361    }
00362 
00363    AST_RWLIST_TRAVERSE(&uris, uri, entry) {
00364       if (AST_RWLIST_NEXT(uri, entry) &&
00365           strlen(AST_RWLIST_NEXT(uri, entry)->uri) <= len) {
00366          AST_RWLIST_INSERT_AFTER(&uris, uri, urih, entry);
00367          AST_RWLIST_UNLOCK(&uris); 
00368 
00369          return 0;
00370       }
00371    }
00372 
00373    AST_RWLIST_INSERT_TAIL(&uris, urih, entry);
00374 
00375    AST_RWLIST_UNLOCK(&uris);
00376    
00377    return 0;
00378 }  

void ast_http_uri_unlink ( struct ast_http_uri urihandler  ) 

Unregister a URI handler.

Definition at line 380 of file http.c.

References AST_RWLIST_REMOVE, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, and ast_http_uri::entry.

Referenced by unload_module().

00381 {
00382    AST_RWLIST_WRLOCK(&uris);
00383    AST_RWLIST_REMOVE(&uris, urih, entry);
00384    AST_RWLIST_UNLOCK(&uris);
00385 }

void ast_http_uri_unlink_all_with_key ( const char *  key  ) 

Unregister all handlers with matching key.

Definition at line 387 of file http.c.

References ast_free, AST_RWLIST_REMOVE_CURRENT, AST_RWLIST_TRAVERSE_SAFE_BEGIN, AST_RWLIST_TRAVERSE_SAFE_END, AST_RWLIST_UNLOCK, AST_RWLIST_WRLOCK, ast_http_uri::data, ast_http_uri::dmallocd, ast_http_uri::entry, ast_http_uri::key, and ast_http_uri::mallocd.

Referenced by __ast_http_post_load(), and unload_module().

00388 {
00389    struct ast_http_uri *urih;
00390    AST_RWLIST_WRLOCK(&uris);
00391    AST_RWLIST_TRAVERSE_SAFE_BEGIN(&uris, urih, entry) {
00392       if (!strcmp(urih->key, key)) {
00393          AST_RWLIST_REMOVE_CURRENT(entry);
00394       }
00395       if (urih->dmallocd) {
00396          ast_free(urih->data);
00397       }
00398       if (urih->mallocd) {
00399          ast_free(urih);
00400       }
00401    }
00402    AST_RWLIST_TRAVERSE_SAFE_END;
00403    AST_RWLIST_UNLOCK(&uris);
00404 }


Generated on Fri Jul 24 00:41:46 2009 for Asterisk - the Open Source PBX by  doxygen 1.4.7