src/pthr_http.h

   1 /* HTTP library.
   2  * - by Richard W.M. Jones <rich@annexia.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the Free
  16  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *
  18  * $Id: pthr_http.h,v 1.15 2002/12/08 13:41:07 rich Exp $
  19  */
  20
  21 #ifndef PTHR_HTTP_H
  22 #define PTHR_HTTP_H
  23
  24 #include <stdio.h>
  25 #include <stdarg.h>
  26
  27 #include <setjmp.h>
  28 #include <time.h>
  29
  30 #include <pool.h>
  31 #include <vector.h>
  32 #include <hash.h>
  33
  34 #include "pthr_pseudothread.h"
  35 #include "pthr_iolib.h"
  36
  37 struct http_request;
  38 typedef struct http_request *http_request;
  39
  40 struct http_response;
  41 typedef struct http_response *http_response;
  42
  43 /* A vector of struct http_header is returned from the
  44  * HTTP_REQUEST_GET_HEADERS call.
  45  */
  46 struct http_header { const char *key, *value; };
  47
  48 /* Supported methods. */
  49 #define HTTP_METHOD_GET  1
  50 #define HTTP_METHOD_HEAD 2
  51 #define HTTP_METHOD_POST 3
  52
  53 /* Function: http_get_servername - get and set the server name string
  54  * Function: http_set_servername
  55  *
  56  * Get and set the server name (which is sent in the @code{Server})
  57  * header by the server when it responds to requests.
  58  *
  59  * The default string is @code{pthrlib-httpd/version}.
  60  *
  61  * See also: @ref{new_http_request(3)}, @ref{new_http_response(3)},
  62  * @ref{new_cgi(3)}.
  63  */
  64 const char *http_get_servername (void);
  65 const char *http_set_servername (const char *new_server_name);
  66
  67 /* Function: new_http_request - functions for parsing HTTP requests
  68  * Function: http_request_time
  69  * Function: http_request_get_url
  70  * Function: http_request_set_url
  71  * Function: http_request_path
  72  * Function: http_request_query_string
  73  * Function: http_request_method
  74  * Function: http_request_method_string
  75  * Function: http_request_is_HEAD
  76  * Function: http_request_version
  77  * Function: http_request_nr_headers
  78  * Function: http_request_get_headers
  79  * Function: http_request_get_header
  80  * Function: http_request_get_cookie
  81  *
  82  * These functions allow you to efficiently parse incoming
  83  * HTTP requests from conforming HTTP/0.9, HTTP/1.0 and HTTP/1.1
  84  * clients. The request parser understands GET, HEAD and POST
  85  * requests and conforms as far as possible to RFC 2616.
  86  *
  87  * @code{new_http_request} creates a new request object, parsing
  88  * the incoming request on the given @code{io_handle}. If the
  89  * stream closes at the beginning of the request the function
  90  * returns @code{NULL}. If the request is faulty, then the
  91  * library prints a message to syslog and throws an exception
  92  * by calling @ref{pth_die(3)}. Otherwise it initializes a complete
  93  * @code{http_request} object and returns it.
  94  *
  95  * @code{http_request_time} returns the timestamp of the incoming
  96  * request.
  97  *
  98  * @code{http_request_get_url} returns the complete URL of the request.
  99  *
 100  * @code{http_request_path} returns just the path component of
 101  * the URL (ie. without the query string if there was one).
 102  * @code{http_request_query_string} returns just the query string
 103  * (for GET requests only). Do not do your own parsing of query
 104  * strings: there is a CGI library built into pthrlib (see:
 105  * @ref{new_cgi(3)}).
 106  *
 107  * @code{http_request_set_url} updates the URL (and hence path
 108  * and query string). It is used by servers which support internal
 109  * redirects, such as @code{rws}.
 110  *
 111  * @code{http_request_method} returns the method, one of
 112  * @code{HTTP_METHOD_GET}, @code{HTTP_METHOD_HEAD} or
 113  * @code{HTTP_METHOD_POST}. @code{http_request_is_HEAD} is
 114  * just a quick way of testing if the method is a HEAD
 115  * request. @code{http_request_method_string} returns the
 116  * method as a string rather than a coded number.
 117  *
 118  * @code{http_request_version} returns the major and minor
 119  * numbers of the HTTP request (eg. major = 1, minor = 0 for
 120  * a HTTP/1.0 request).
 121  *
 122  * @code{http_request_nr_headers}, @code{http_request_get_headers}
 123  * and @code{http_request_get_header} return the number of
 124  * HTTP headers, the list of HTTP headers and a particular
 125  * HTTP header (if it exists). @code{http_request_get_headers}
 126  * returns a @code{vector} or @code{struct http_header}. This
 127  * structure contains at least two fields called @code{key} and
 128  * @code{value}. HTTP header keys are case insensitive when
 129  * searching, and you will find that the list of keys returned
 130  * by @code{http_request_get_headers} has been converted to
 131  * lowercase.
 132  *
 133  * @code{http_request_get_cookie} gets a named browser cookie
 134  * sent in the request. It returns the value of the cookie
 135  * or @code{NULL} if no such named cookie was sent by the browser.
 136  *
 137  * To send a cookie to the browser, you should generate and send
 138  * a @code{Set-Cookie} header with the appropriate content. Note
 139  * that not all browsers support cookies.
 140  *
 141  * See also: @ref{new_http_response(3)}, @ref{new_cgi(3)},
 142  * @ref{new_pseudothread(3)}, @ref{io_fdopen(3)}, RFC 2616.
 143  */
 144 extern http_request new_http_request (pool, io_handle);
 145 extern time_t http_request_time (http_request);
 146 extern const char *http_request_get_url (http_request);
 147 extern void http_request_set_url (http_request, const char *new_url);
 148 extern const char *http_request_path (http_request);
 149 extern const char *http_request_query_string (http_request);
 150 extern int http_request_method (http_request);
 151 extern const char *http_request_method_string (http_request);
 152 extern int http_request_is_HEAD (http_request);
 153 extern void http_request_version (http_request, int *major, int *minor);
 154 extern int http_request_nr_headers (http_request);
 155 extern vector http_request_get_headers (http_request);
 156 extern const char *http_request_get_header (http_request h, const char *key);
 157 extern const char *http_request_get_cookie (http_request h, const char *key);
 158
 159 /* Function: new_http_response - functions for sending HTTP responses
 160  * Function: http_response_send_header
 161  * Function: http_response_send_headers
 162  * Function: http_response_end_headers
 163  * Function: http_response_write_chunk
 164  * Function: http_response_write_chunk_string
 165  * Function: http_response_write_chunk_end
 166  *
 167  * These functions allow you to efficiently generate outgoing HTTP
 168  * responses.
 169  *
 170  * @code{new_http_response} generates a new HTTP response object and
 171  * returns it. @code{code} is the HTTP response code (see RFC 2616
 172  * for a list of codes), and @code{msg} is the HTTP response message.
 173  *
 174  * @code{http_response_send_header} sends a single HTTP header back
 175  * to the client. The header is constructed by concatenating
 176  * @code{key}, @code{": "}, @code{value} and @code{CR LF}.
 177  *
 178  * @code{http_response_send_headers} sends back several headers in
 179  * a single call. The arguments to this function are a list of
 180  * @code{key}, @code{value} pairs followed by a single @code{NULL}
 181  * argument which terminates the list.
 182  *
 183  * @code{http_response_end_headers} ends the header list. It causes
 184  * the code to emit any missing-but-required headers and then send
 185  * the final @code{CR LF} characters.
 186  *
 187  * @code{http_response_write_chunk}, @code{http_response_write_chunk_string}
 188  * and @code{http_response_write_chunk_end}
 189  * allow the caller to use chunked encoding, which is an
 190  * alternative to sending the @code{Content-Length} header. To enable
 191  * chunked encoding, the application should first call
 192  * @code{http_response_send_header (h, "Transfer-Encoding", "chunked");}.
 193  * Then, instead of writing directly to @code{io} to send data,
 194  * the application should call @code{http_response_write_chunk}
 195  * or @code{http_response_write_chunk_string} to write each block
 196  * (or string) of data. At the end of the data, the application
 197  * should call @code{http_response_write_chunk_end}.
 198  * (Steve Atkins implemented chunked encoding).
 199  *
 200  * See also: @ref{new_http_request(3)}, @ref{new_cgi(3)},
 201  * @ref{new_pseudothread(3)}, @ref{io_fdopen(3)}, RFC 2616.
 202  */
 203 extern http_response new_http_response (pool, http_request, io_handle, int code, const char *msg);
 204 extern void http_response_send_header (http_response, const char *key, const char *value);
 205 extern void http_response_send_headers (http_response, ...);
 206 extern int http_response_end_headers (http_response h);
 207 extern void http_response_write_chunk (http_response, const char *data, int length);
 208 extern void http_response_write_chunk_string (http_response, const char *string);
 209 extern void http_response_write_chunk_end (http_response);
 210
 211 /* Function: http_set_log_file - enable HTTP logs on file pointer
 212  * Function: http_get_log_file
 213  *
 214  * The @code{FILE *fp} argument to @code{http_set_log_file} sets
 215  * the file pointer on which HTTP logs are generated. To disable
 216  * logging, set @code{fp} to @code{NULL}. The function returns
 217  * @code{fp}.
 218  *
 219  * @code{http_get_log_file} returns the current file pointer
 220  * or @code{NULL} if logging is disabled.
 221  *
 222  * The default is that logging is disabled.
 223  *
 224  * Currently log messages are generated at the end of the
 225  * HTTP response headers and have the following fixed format:
 226  *
 227  * YYYY/MM/DD HH:MM ip:port - "METHOD URL HTTP/x.y" CODE length "Referer" "User Agent"
 228  *
 229  * The first "-" is intended to store the HTTP auth username, when
 230  * HTTP authorization is supported by the library. The "length"
 231  * field is only known if the caller sends back a "Content-Length"
 232  * header. Otherwise 0 is printed in that position.
 233  *
 234  * Bugs: Log format should be customizable. It should be possible
 235  * (optionally, of course) to look up the IP address and print
 236  * a hostname.
 237  *
 238  * See also: @ref{new_http_request(3)}, @ref{new_cgi(3)},
 239  * @ref{new_pseudothread(3)}, @ref{io_fdopen(3)}, RFC 2616.
 240  */
 241 extern FILE *http_set_log_file (FILE *fp);
 242 extern FILE *http_get_log_file (void);
 243
 244 #endif /* PTHR_HTTP_H */