2 * - by Richard W.M. Jones <rich@annexia.org>
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.
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.
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.
18 * $Id: pthr_http.h,v 1.15 2002/12/08 13:41:07 rich Exp $
34 #include "pthr_pseudothread.h"
35 #include "pthr_iolib.h"
38 typedef struct http_request *http_request;
41 typedef struct http_response *http_response;
43 /* A vector of struct http_header is returned from the
44 * HTTP_REQUEST_GET_HEADERS call.
46 struct http_header { const char *key, *value; };
48 /* Supported methods. */
49 #define HTTP_METHOD_GET 1
50 #define HTTP_METHOD_HEAD 2
51 #define HTTP_METHOD_POST 3
53 /* Function: http_get_servername - get and set the server name string
54 * Function: http_set_servername
56 * Get and set the server name (which is sent in the @code{Server})
57 * header by the server when it responds to requests.
59 * The default string is @code{pthrlib-httpd/version}.
61 * See also: @ref{new_http_request(3)}, @ref{new_http_response(3)},
64 const char *http_get_servername (void);
65 const char *http_set_servername (const char *new_server_name);
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
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.
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.
95 * @code{http_request_time} returns the timestamp of the incoming
98 * @code{http_request_get_url} returns the complete URL of the request.
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:
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}.
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.
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).
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
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.
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.
141 * See also: @ref{new_http_response(3)}, @ref{new_cgi(3)},
142 * @ref{new_pseudothread(3)}, @ref{io_fdopen(3)}, RFC 2616.
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);
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
167 * These functions allow you to efficiently generate outgoing HTTP
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.
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}.
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.
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.
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).
200 * See also: @ref{new_http_request(3)}, @ref{new_cgi(3)},
201 * @ref{new_pseudothread(3)}, @ref{io_fdopen(3)}, RFC 2616.
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);
211 /* Function: http_set_log_file - enable HTTP logs on file pointer
212 * Function: http_get_log_file
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
219 * @code{http_get_log_file} returns the current file pointer
220 * or @code{NULL} if logging is disabled.
222 * The default is that logging is disabled.
224 * Currently log messages are generated at the end of the
225 * HTTP response headers and have the following fixed format:
227 * YYYY/MM/DD HH:MM ip:port - "METHOD URL HTTP/x.y" CODE length "Referer" "User Agent"
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.
234 * Bugs: Log format should be customizable. It should be possible
235 * (optionally, of course) to look up the IP address and print
238 * See also: @ref{new_http_request(3)}, @ref{new_cgi(3)},
239 * @ref{new_pseudothread(3)}, @ref{io_fdopen(3)}, RFC 2616.
241 extern FILE *http_set_log_file (FILE *fp);
242 extern FILE *http_get_log_file (void);
244 #endif /* PTHR_HTTP_H */