• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
3  * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  *    notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  *    notice, this list of conditions and the following disclaimer in the
12  *    documentation and/or other materials provided with the distribution.
13  * 3. The name of the author may not be used to endorse or promote products
14  *    derived from this software without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  */
27 #ifndef EVENT2_HTTP_H_INCLUDED_
28 #define EVENT2_HTTP_H_INCLUDED_
29 
30 /* For int types. */
31 #include <event2/util.h>
32 #include <event2/visibility.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /* In case we haven't included the right headers yet. */
39 struct evbuffer;
40 struct event_base;
41 struct bufferevent;
42 struct evhttp_connection;
43 
44 /** @file event2/http.h
45  *
46  * Basic support for HTTP serving.
47  *
48  * As Libevent is a library for dealing with event notification and most
49  * interesting applications are networked today, I have often found the
50  * need to write HTTP code.  The following prototypes and definitions provide
51  * an application with a minimal interface for making HTTP requests and for
52  * creating a very simple HTTP server.
53  */
54 
55 /* Response codes */
56 #define HTTP_OK			200	/**< request completed ok */
57 #define HTTP_NOCONTENT		204	/**< request does not have content */
58 #define HTTP_MOVEPERM		301	/**< the uri moved permanently */
59 #define HTTP_MOVETEMP		302	/**< the uri moved temporarily */
60 #define HTTP_NOTMODIFIED	304	/**< page was not modified from last */
61 #define HTTP_BADREQUEST		400	/**< invalid http request was made */
62 #define HTTP_NOTFOUND		404	/**< could not find content for uri */
63 #define HTTP_BADMETHOD		405 	/**< method not allowed for this uri */
64 #define HTTP_ENTITYTOOLARGE	413	/**<  */
65 #define HTTP_EXPECTATIONFAILED	417	/**< we can't handle this expectation */
66 #define HTTP_INTERNAL           500     /**< internal error */
67 #define HTTP_NOTIMPLEMENTED     501     /**< not implemented */
68 #define HTTP_SERVUNAVAIL	503	/**< the server is not available */
69 
70 struct evhttp;
71 struct evhttp_request;
72 struct evkeyvalq;
73 struct evhttp_bound_socket;
74 struct evconnlistener;
75 struct evdns_base;
76 
77 /**
78  * Create a new HTTP server.
79  *
80  * @param base (optional) the event base to receive the HTTP events
81  * @return a pointer to a newly initialized evhttp server structure
82  * @see evhttp_free()
83  */
84 EVENT2_EXPORT_SYMBOL
85 struct evhttp *evhttp_new(struct event_base *base);
86 
87 /**
88  * Binds an HTTP server on the specified address and port.
89  *
90  * Can be called multiple times to bind the same http server
91  * to multiple different ports.
92  *
93  * @param http a pointer to an evhttp object
94  * @param address a string containing the IP address to listen(2) on
95  * @param port the port number to listen on
96  * @return 0 on success, -1 on failure.
97  * @see evhttp_accept_socket()
98  */
99 EVENT2_EXPORT_SYMBOL
100 int evhttp_bind_socket(struct evhttp *http, const char *address, ev_uint16_t port);
101 
102 /**
103  * Like evhttp_bind_socket(), but returns a handle for referencing the socket.
104  *
105  * The returned pointer is not valid after \a http is freed.
106  *
107  * @param http a pointer to an evhttp object
108  * @param address a string containing the IP address to listen(2) on
109  * @param port the port number to listen on
110  * @return Handle for the socket on success, NULL on failure.
111  * @see evhttp_bind_socket(), evhttp_del_accept_socket()
112  */
113 EVENT2_EXPORT_SYMBOL
114 struct evhttp_bound_socket *evhttp_bind_socket_with_handle(struct evhttp *http, const char *address, ev_uint16_t port);
115 
116 /**
117  * Makes an HTTP server accept connections on the specified socket.
118  *
119  * This may be useful to create a socket and then fork multiple instances
120  * of an http server, or when a socket has been communicated via file
121  * descriptor passing in situations where an http servers does not have
122  * permissions to bind to a low-numbered port.
123  *
124  * Can be called multiple times to have the http server listen to
125  * multiple different sockets.
126  *
127  * @param http a pointer to an evhttp object
128  * @param fd a socket fd that is ready for accepting connections
129  * @return 0 on success, -1 on failure.
130  * @see evhttp_bind_socket()
131  */
132 EVENT2_EXPORT_SYMBOL
133 int evhttp_accept_socket(struct evhttp *http, evutil_socket_t fd);
134 
135 /**
136  * Like evhttp_accept_socket(), but returns a handle for referencing the socket.
137  *
138  * The returned pointer is not valid after \a http is freed.
139  *
140  * @param http a pointer to an evhttp object
141  * @param fd a socket fd that is ready for accepting connections
142  * @return Handle for the socket on success, NULL on failure.
143  * @see evhttp_accept_socket(), evhttp_del_accept_socket()
144  */
145 EVENT2_EXPORT_SYMBOL
146 struct evhttp_bound_socket *evhttp_accept_socket_with_handle(struct evhttp *http, evutil_socket_t fd);
147 
148 /**
149  * The most low-level evhttp_bind/accept method: takes an evconnlistener, and
150  * returns an evhttp_bound_socket.  The listener will be freed when the bound
151  * socket is freed.
152  */
153 EVENT2_EXPORT_SYMBOL
154 struct evhttp_bound_socket *evhttp_bind_listener(struct evhttp *http, struct evconnlistener *listener);
155 
156 /**
157  * Return the listener used to implement a bound socket.
158  */
159 EVENT2_EXPORT_SYMBOL
160 struct evconnlistener *evhttp_bound_socket_get_listener(struct evhttp_bound_socket *bound);
161 
162 typedef void evhttp_bound_socket_foreach_fn(struct evhttp_bound_socket *, void *);
163 /**
164  * Applies the function specified in the first argument to all
165  * evhttp_bound_sockets associated with "http". The user must not
166  * attempt to free or remove any connections, sockets or listeners
167  * in the callback "function".
168  *
169  * @param http pointer to an evhttp object
170  * @param function function to apply to every bound socket
171  * @param argument pointer value passed to function for every socket iterated
172  */
173 EVENT2_EXPORT_SYMBOL
174 void evhttp_foreach_bound_socket(struct evhttp *http, evhttp_bound_socket_foreach_fn *function, void *argument);
175 
176 /**
177  * Makes an HTTP server stop accepting connections on the specified socket
178  *
179  * This may be useful when a socket has been sent via file descriptor passing
180  * and is no longer needed by the current process.
181  *
182  * If you created this bound socket with evhttp_bind_socket_with_handle or
183  * evhttp_accept_socket_with_handle, this function closes the fd you provided.
184  * If you created this bound socket with evhttp_bind_listener, this function
185  * frees the listener you provided.
186  *
187  * \a bound_socket is an invalid pointer after this call returns.
188  *
189  * @param http a pointer to an evhttp object
190  * @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle
191  * @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle()
192  */
193 EVENT2_EXPORT_SYMBOL
194 void evhttp_del_accept_socket(struct evhttp *http, struct evhttp_bound_socket *bound_socket);
195 
196 /**
197  * Get the raw file descriptor referenced by an evhttp_bound_socket.
198  *
199  * @param bound_socket a handle returned by evhttp_{bind,accept}_socket_with_handle
200  * @return the file descriptor used by the bound socket
201  * @see evhttp_bind_socket_with_handle(), evhttp_accept_socket_with_handle()
202  */
203 EVENT2_EXPORT_SYMBOL
204 evutil_socket_t evhttp_bound_socket_get_fd(struct evhttp_bound_socket *bound_socket);
205 
206 /**
207  * Free the previously created HTTP server.
208  *
209  * Works only if no requests are currently being served.
210  *
211  * @param http the evhttp server object to be freed
212  * @see evhttp_start()
213  */
214 EVENT2_EXPORT_SYMBOL
215 void evhttp_free(struct evhttp* http);
216 
217 /** XXX Document. */
218 EVENT2_EXPORT_SYMBOL
219 void evhttp_set_max_headers_size(struct evhttp* http, ev_ssize_t max_headers_size);
220 /** XXX Document. */
221 EVENT2_EXPORT_SYMBOL
222 void evhttp_set_max_body_size(struct evhttp* http, ev_ssize_t max_body_size);
223 
224 /**
225   Set the value to use for the Content-Type header when none was provided. If
226   the content type string is NULL, the Content-Type header will not be
227   automatically added.
228 
229   @param http the http server on which to set the default content type
230   @param content_type the value for the Content-Type header
231 */
232 EVENT2_EXPORT_SYMBOL
233 void evhttp_set_default_content_type(struct evhttp *http,
234 	const char *content_type);
235 
236 /**
237   Sets the what HTTP methods are supported in requests accepted by this
238   server, and passed to user callbacks.
239 
240   If not supported they will generate a "405 Method not allowed" response.
241 
242   By default this includes the following methods: GET, POST, HEAD, PUT, DELETE
243 
244   @param http the http server on which to set the methods
245   @param methods bit mask constructed from evhttp_cmd_type values
246 */
247 EVENT2_EXPORT_SYMBOL
248 void evhttp_set_allowed_methods(struct evhttp* http, ev_uint16_t methods);
249 
250 /**
251    Set a callback for a specified URI
252 
253    @param http the http sever on which to set the callback
254    @param path the path for which to invoke the callback
255    @param cb the callback function that gets invoked on requesting path
256    @param cb_arg an additional context argument for the callback
257    @return 0 on success, -1 if the callback existed already, -2 on failure
258 */
259 EVENT2_EXPORT_SYMBOL
260 int evhttp_set_cb(struct evhttp *http, const char *path,
261     void (*cb)(struct evhttp_request *, void *), void *cb_arg);
262 
263 /** Removes the callback for a specified URI */
264 EVENT2_EXPORT_SYMBOL
265 int evhttp_del_cb(struct evhttp *, const char *);
266 
267 /**
268     Set a callback for all requests that are not caught by specific callbacks
269 
270     Invokes the specified callback for all requests that do not match any of
271     the previously specified request paths.  This is catchall for requests not
272     specifically configured with evhttp_set_cb().
273 
274     @param http the evhttp server object for which to set the callback
275     @param cb the callback to invoke for any unmatched requests
276     @param arg an context argument for the callback
277 */
278 EVENT2_EXPORT_SYMBOL
279 void evhttp_set_gencb(struct evhttp *http,
280     void (*cb)(struct evhttp_request *, void *), void *arg);
281 
282 /**
283    Set a callback used to create new bufferevents for connections
284    to a given evhttp object.
285 
286    You can use this to override the default bufferevent type -- for example,
287    to make this evhttp object use SSL bufferevents rather than unencrypted
288    ones.
289 
290    New bufferevents must be allocated with no fd set on them.
291 
292    @param http the evhttp server object for which to set the callback
293    @param cb the callback to invoke for incoming connections
294    @param arg an context argument for the callback
295  */
296 EVENT2_EXPORT_SYMBOL
297 void evhttp_set_bevcb(struct evhttp *http,
298     struct bufferevent *(*cb)(struct event_base *, void *), void *arg);
299 
300 /**
301    Adds a virtual host to the http server.
302 
303    A virtual host is a newly initialized evhttp object that has request
304    callbacks set on it via evhttp_set_cb() or evhttp_set_gencb().  It
305    most not have any listing sockets associated with it.
306 
307    If the virtual host has not been removed by the time that evhttp_free()
308    is called on the main http server, it will be automatically freed, too.
309 
310    It is possible to have hierarchical vhosts.  For example: A vhost
311    with the pattern *.example.com may have other vhosts with patterns
312    foo.example.com and bar.example.com associated with it.
313 
314    @param http the evhttp object to which to add a virtual host
315    @param pattern the glob pattern against which the hostname is matched.
316      The match is case insensitive and follows otherwise regular shell
317      matching.
318    @param vhost the virtual host to add the regular http server.
319    @return 0 on success, -1 on failure
320    @see evhttp_remove_virtual_host()
321 */
322 EVENT2_EXPORT_SYMBOL
323 int evhttp_add_virtual_host(struct evhttp* http, const char *pattern,
324     struct evhttp* vhost);
325 
326 /**
327    Removes a virtual host from the http server.
328 
329    @param http the evhttp object from which to remove the virtual host
330    @param vhost the virtual host to remove from the regular http server.
331    @return 0 on success, -1 on failure
332    @see evhttp_add_virtual_host()
333 */
334 EVENT2_EXPORT_SYMBOL
335 int evhttp_remove_virtual_host(struct evhttp* http, struct evhttp* vhost);
336 
337 /**
338    Add a server alias to an http object. The http object can be a virtual
339    host or the main server.
340 
341    @param http the evhttp object
342    @param alias the alias to add
343    @see evhttp_add_remove_alias()
344 */
345 EVENT2_EXPORT_SYMBOL
346 int evhttp_add_server_alias(struct evhttp *http, const char *alias);
347 
348 /**
349    Remove a server alias from an http object.
350 
351    @param http the evhttp object
352    @param alias the alias to remove
353    @see evhttp_add_server_alias()
354 */
355 EVENT2_EXPORT_SYMBOL
356 int evhttp_remove_server_alias(struct evhttp *http, const char *alias);
357 
358 /**
359  * Set the timeout for an HTTP request.
360  *
361  * @param http an evhttp object
362  * @param timeout_in_secs the timeout, in seconds
363  */
364 EVENT2_EXPORT_SYMBOL
365 void evhttp_set_timeout(struct evhttp *http, int timeout_in_secs);
366 
367 /**
368  * Set the timeout for an HTTP request.
369  *
370  * @param http an evhttp object
371  * @param tv the timeout, or NULL
372  */
373 EVENT2_EXPORT_SYMBOL
374 void evhttp_set_timeout_tv(struct evhttp *http, const struct timeval* tv);
375 
376 /* Read all the clients body, and only after this respond with an error if the
377  * clients body exceed max_body_size */
378 #define EVHTTP_SERVER_LINGERING_CLOSE	0x0001
379 /**
380  * Set connection flags for HTTP server.
381  *
382  * @see EVHTTP_SERVER_*
383  * @return 0 on success, otherwise non zero (for example if flag doesn't
384  * supported).
385  */
386 EVENT2_EXPORT_SYMBOL
387 int evhttp_set_flags(struct evhttp *http, int flags);
388 
389 /* Request/Response functionality */
390 
391 /**
392  * Send an HTML error message to the client.
393  *
394  * @param req a request object
395  * @param error the HTTP error code
396  * @param reason a brief explanation of the error.  If this is NULL, we'll
397  *    just use the standard meaning of the error code.
398  */
399 EVENT2_EXPORT_SYMBOL
400 void evhttp_send_error(struct evhttp_request *req, int error,
401     const char *reason);
402 
403 /**
404  * Send an HTML reply to the client.
405  *
406  * The body of the reply consists of the data in databuf.  After calling
407  * evhttp_send_reply() databuf will be empty, but the buffer is still
408  * owned by the caller and needs to be deallocated by the caller if
409  * necessary.
410  *
411  * @param req a request object
412  * @param code the HTTP response code to send
413  * @param reason a brief message to send with the response code
414  * @param databuf the body of the response
415  */
416 EVENT2_EXPORT_SYMBOL
417 void evhttp_send_reply(struct evhttp_request *req, int code,
418     const char *reason, struct evbuffer *databuf);
419 
420 /* Low-level response interface, for streaming/chunked replies */
421 
422 /**
423    Initiate a reply that uses Transfer-Encoding chunked.
424 
425    This allows the caller to stream the reply back to the client and is
426    useful when either not all of the reply data is immediately available
427    or when sending very large replies.
428 
429    The caller needs to supply data chunks with evhttp_send_reply_chunk()
430    and complete the reply by calling evhttp_send_reply_end().
431 
432    @param req a request object
433    @param code the HTTP response code to send
434    @param reason a brief message to send with the response code
435 */
436 EVENT2_EXPORT_SYMBOL
437 void evhttp_send_reply_start(struct evhttp_request *req, int code,
438     const char *reason);
439 
440 /**
441    Send another data chunk as part of an ongoing chunked reply.
442 
443    The reply chunk consists of the data in databuf.  After calling
444    evhttp_send_reply_chunk() databuf will be empty, but the buffer is
445    still owned by the caller and needs to be deallocated by the caller
446    if necessary.
447 
448    @param req a request object
449    @param databuf the data chunk to send as part of the reply.
450 */
451 EVENT2_EXPORT_SYMBOL
452 void evhttp_send_reply_chunk(struct evhttp_request *req,
453     struct evbuffer *databuf);
454 
455 /**
456    Send another data chunk as part of an ongoing chunked reply.
457 
458    The reply chunk consists of the data in databuf.  After calling
459    evhttp_send_reply_chunk() databuf will be empty, but the buffer is
460    still owned by the caller and needs to be deallocated by the caller
461    if necessary.
462 
463    @param req a request object
464    @param databuf the data chunk to send as part of the reply.
465    @param cb callback funcion
466    @param call back's argument.
467 */
468 EVENT2_EXPORT_SYMBOL
469 void evhttp_send_reply_chunk_with_cb(struct evhttp_request *, struct evbuffer *,
470     void (*cb)(struct evhttp_connection *, void *), void *arg);
471 
472 /**
473    Complete a chunked reply, freeing the request as appropriate.
474 
475    @param req a request object
476 */
477 EVENT2_EXPORT_SYMBOL
478 void evhttp_send_reply_end(struct evhttp_request *req);
479 
480 /*
481  * Interfaces for making requests
482  */
483 
484 /** The different request types supported by evhttp.  These are as specified
485  * in RFC2616, except for PATCH which is specified by RFC5789.
486  *
487  * By default, only some of these methods are accepted and passed to user
488  * callbacks; use evhttp_set_allowed_methods() to change which methods
489  * are allowed.
490  */
491 enum evhttp_cmd_type {
492 	EVHTTP_REQ_GET     = 1 << 0,
493 	EVHTTP_REQ_POST    = 1 << 1,
494 	EVHTTP_REQ_HEAD    = 1 << 2,
495 	EVHTTP_REQ_PUT     = 1 << 3,
496 	EVHTTP_REQ_DELETE  = 1 << 4,
497 	EVHTTP_REQ_OPTIONS = 1 << 5,
498 	EVHTTP_REQ_TRACE   = 1 << 6,
499 	EVHTTP_REQ_CONNECT = 1 << 7,
500 	EVHTTP_REQ_PATCH   = 1 << 8
501 };
502 
503 /** a request object can represent either a request or a reply */
504 enum evhttp_request_kind { EVHTTP_REQUEST, EVHTTP_RESPONSE };
505 
506 /**
507  * Create and return a connection object that can be used to for making HTTP
508  * requests.  The connection object tries to resolve address and establish the
509  * connection when it is given an http request object.
510  *
511  * @param base the event_base to use for handling the connection
512  * @param dnsbase the dns_base to use for resolving host names; if not
513  *     specified host name resolution will block.
514  * @param bev a bufferevent to use for connecting to the server; if NULL, a
515  *     socket-based bufferevent will be created.  This buffrevent will be freed
516  *     when the connection closes.  It must have no fd set on it.
517  * @param address the address to which to connect
518  * @param port the port to connect to
519  * @return an evhttp_connection object that can be used for making requests
520  */
521 EVENT2_EXPORT_SYMBOL
522 struct evhttp_connection *evhttp_connection_base_bufferevent_new(
523 	struct event_base *base, struct evdns_base *dnsbase, struct bufferevent* bev, const char *address, ev_uint16_t port);
524 
525 /**
526  * Return the bufferevent that an evhttp_connection is using.
527  */
528 EVENT2_EXPORT_SYMBOL
529 struct bufferevent* evhttp_connection_get_bufferevent(struct evhttp_connection *evcon);
530 
531 /**
532  * Return the HTTP server associated with this connection, or NULL.
533  */
534 EVENT2_EXPORT_SYMBOL
535 struct evhttp *evhttp_connection_get_server(struct evhttp_connection *evcon);
536 
537 /**
538  * Creates a new request object that needs to be filled in with the request
539  * parameters.  The callback is executed when the request completed or an
540  * error occurred.
541  */
542 EVENT2_EXPORT_SYMBOL
543 struct evhttp_request *evhttp_request_new(
544 	void (*cb)(struct evhttp_request *, void *), void *arg);
545 
546 /**
547  * Enable delivery of chunks to requestor.
548  * @param cb will be called after every read of data with the same argument
549  *           as the completion callback. Will never be called on an empty
550  *           response. May drain the input buffer; it will be drained
551  *           automatically on return.
552  */
553 EVENT2_EXPORT_SYMBOL
554 void evhttp_request_set_chunked_cb(struct evhttp_request *,
555     void (*cb)(struct evhttp_request *, void *));
556 
557 /**
558  * Register callback for additional parsing of request headers.
559  * @param cb will be called after receiving and parsing the full header.
560  * It allows analyzing the header and possibly closing the connection
561  * by returning a value < 0.
562  */
563 EVENT2_EXPORT_SYMBOL
564 void evhttp_request_set_header_cb(struct evhttp_request *,
565     int (*cb)(struct evhttp_request *, void *));
566 
567 /**
568  * The different error types supported by evhttp
569  *
570  * @see evhttp_request_set_error_cb()
571  */
572 enum evhttp_request_error {
573   /**
574    * Timeout reached, also @see evhttp_connection_set_timeout()
575    */
576   EVREQ_HTTP_TIMEOUT,
577   /**
578    * EOF reached
579    */
580   EVREQ_HTTP_EOF,
581   /**
582    * Error while reading header, or invalid header
583    */
584   EVREQ_HTTP_INVALID_HEADER,
585   /**
586    * Error encountered while reading or writing
587    */
588   EVREQ_HTTP_BUFFER_ERROR,
589   /**
590    * The evhttp_cancel_request() called on this request.
591    */
592   EVREQ_HTTP_REQUEST_CANCEL,
593   /**
594    * Body is greater then evhttp_connection_set_max_body_size()
595    */
596   EVREQ_HTTP_DATA_TOO_LONG
597 };
598 /**
599  * Set a callback for errors
600  * @see evhttp_request_error for error types.
601  *
602  * On error, both the error callback and the regular callback will be called,
603  * error callback is called before the regular callback.
604  **/
605 EVENT2_EXPORT_SYMBOL
606 void evhttp_request_set_error_cb(struct evhttp_request *,
607     void (*)(enum evhttp_request_error, void *));
608 
609 /**
610  * Set a callback to be called on request completion of evhttp_send_* function.
611  *
612  * The callback function will be called on the completion of the request after
613  * the output data has been written and before the evhttp_request object
614  * is destroyed. This can be useful for tracking resources associated with a
615  * request (ex: timing metrics).
616  *
617  * @param req a request object
618  * @param cb callback function that will be called on request completion
619  * @param cb_arg an additional context argument for the callback
620  */
621 EVENT2_EXPORT_SYMBOL
622 void evhttp_request_set_on_complete_cb(struct evhttp_request *req,
623     void (*cb)(struct evhttp_request *, void *), void *cb_arg);
624 
625 /** Frees the request object and removes associated events. */
626 EVENT2_EXPORT_SYMBOL
627 void evhttp_request_free(struct evhttp_request *req);
628 
629 /**
630  * Create and return a connection object that can be used to for making HTTP
631  * requests.  The connection object tries to resolve address and establish the
632  * connection when it is given an http request object.
633  *
634  * @param base the event_base to use for handling the connection
635  * @param dnsbase the dns_base to use for resolving host names; if not
636  *     specified host name resolution will block.
637  * @param address the address to which to connect
638  * @param port the port to connect to
639  * @return an evhttp_connection object that can be used for making requests
640  */
641 EVENT2_EXPORT_SYMBOL
642 struct evhttp_connection *evhttp_connection_base_new(
643 	struct event_base *base, struct evdns_base *dnsbase,
644 	const char *address, ev_uint16_t port);
645 
646 /**
647  * Set family hint for DNS requests.
648  */
649 EVENT2_EXPORT_SYMBOL
650 void evhttp_connection_set_family(struct evhttp_connection *evcon,
651 	int family);
652 
653 /* reuse connection address on retry */
654 #define EVHTTP_CON_REUSE_CONNECTED_ADDR	0x0008
655 /* Try to read error, since server may already send and close
656  * connection, but if at that time we have some data to send then we
657  * can send get EPIPE and fail, while we can read that HTTP error. */
658 #define EVHTTP_CON_READ_ON_WRITE_ERROR	0x0010
659 /* @see EVHTTP_SERVER_LINGERING_CLOSE */
660 #define EVHTTP_CON_LINGERING_CLOSE	0x0020
661 /* Padding for public flags, @see EVHTTP_CON_* in http-internal.h */
662 #define EVHTTP_CON_PUBLIC_FLAGS_END	0x100000
663 /**
664  * Set connection flags.
665  *
666  * @see EVHTTP_CON_*
667  * @return 0 on success, otherwise non zero (for example if flag doesn't
668  * supported).
669  */
670 EVENT2_EXPORT_SYMBOL
671 int evhttp_connection_set_flags(struct evhttp_connection *evcon,
672 	int flags);
673 
674 /** Takes ownership of the request object
675  *
676  * Can be used in a request callback to keep onto the request until
677  * evhttp_request_free() is explicitly called by the user.
678  */
679 EVENT2_EXPORT_SYMBOL
680 void evhttp_request_own(struct evhttp_request *req);
681 
682 /** Returns 1 if the request is owned by the user */
683 EVENT2_EXPORT_SYMBOL
684 int evhttp_request_is_owned(struct evhttp_request *req);
685 
686 /**
687  * Returns the connection object associated with the request or NULL
688  *
689  * The user needs to either free the request explicitly or call
690  * evhttp_send_reply_end().
691  */
692 EVENT2_EXPORT_SYMBOL
693 struct evhttp_connection *evhttp_request_get_connection(struct evhttp_request *req);
694 
695 /**
696  * Returns the underlying event_base for this connection
697  */
698 EVENT2_EXPORT_SYMBOL
699 struct event_base *evhttp_connection_get_base(struct evhttp_connection *req);
700 
701 EVENT2_EXPORT_SYMBOL
702 void evhttp_connection_set_max_headers_size(struct evhttp_connection *evcon,
703     ev_ssize_t new_max_headers_size);
704 
705 EVENT2_EXPORT_SYMBOL
706 void evhttp_connection_set_max_body_size(struct evhttp_connection* evcon,
707     ev_ssize_t new_max_body_size);
708 
709 /** Frees an http connection */
710 EVENT2_EXPORT_SYMBOL
711 void evhttp_connection_free(struct evhttp_connection *evcon);
712 
713 /** Disowns a given connection object
714  *
715  * Can be used to tell libevent to free the connection object after
716  * the last request has completed or failed.
717  */
718 EVENT2_EXPORT_SYMBOL
719 void evhttp_connection_free_on_completion(struct evhttp_connection *evcon);
720 
721 /** sets the ip address from which http connections are made */
722 EVENT2_EXPORT_SYMBOL
723 void evhttp_connection_set_local_address(struct evhttp_connection *evcon,
724     const char *address);
725 
726 /** sets the local port from which http connections are made */
727 EVENT2_EXPORT_SYMBOL
728 void evhttp_connection_set_local_port(struct evhttp_connection *evcon,
729     ev_uint16_t port);
730 
731 /** Sets the timeout in seconds for events related to this connection */
732 EVENT2_EXPORT_SYMBOL
733 void evhttp_connection_set_timeout(struct evhttp_connection *evcon,
734     int timeout_in_secs);
735 
736 /** Sets the timeout for events related to this connection.  Takes a struct
737  * timeval. */
738 EVENT2_EXPORT_SYMBOL
739 void evhttp_connection_set_timeout_tv(struct evhttp_connection *evcon,
740     const struct timeval *tv);
741 
742 /** Sets the delay before retrying requests on this connection. This is only
743  * used if evhttp_connection_set_retries is used to make the number of retries
744  * at least one. Each retry after the first is twice as long as the one before
745  * it. */
746 EVENT2_EXPORT_SYMBOL
747 void evhttp_connection_set_initial_retry_tv(struct evhttp_connection *evcon,
748     const struct timeval *tv);
749 
750 /** Sets the retry limit for this connection - -1 repeats indefinitely */
751 EVENT2_EXPORT_SYMBOL
752 void evhttp_connection_set_retries(struct evhttp_connection *evcon,
753     int retry_max);
754 
755 /** Set a callback for connection close. */
756 EVENT2_EXPORT_SYMBOL
757 void evhttp_connection_set_closecb(struct evhttp_connection *evcon,
758     void (*)(struct evhttp_connection *, void *), void *);
759 
760 /** Get the remote address and port associated with this connection. */
761 EVENT2_EXPORT_SYMBOL
762 void evhttp_connection_get_peer(struct evhttp_connection *evcon,
763     char **address, ev_uint16_t *port);
764 
765 /** Get the remote address associated with this connection.
766  * extracted from getpeername() OR from nameserver.
767  *
768  * @return NULL if getpeername() return non success,
769  * or connection is not connected,
770  * otherwise it return pointer to struct sockaddr_storage */
771 EVENT2_EXPORT_SYMBOL
772 const struct sockaddr*
773 evhttp_connection_get_addr(struct evhttp_connection *evcon);
774 
775 /**
776     Make an HTTP request over the specified connection.
777 
778     The connection gets ownership of the request.  On failure, the
779     request object is no longer valid as it has been freed.
780 
781     @param evcon the evhttp_connection object over which to send the request
782     @param req the previously created and configured request object
783     @param type the request type EVHTTP_REQ_GET, EVHTTP_REQ_POST, etc.
784     @param uri the URI associated with the request
785     @return 0 on success, -1 on failure
786     @see evhttp_cancel_request()
787 */
788 EVENT2_EXPORT_SYMBOL
789 int evhttp_make_request(struct evhttp_connection *evcon,
790     struct evhttp_request *req,
791     enum evhttp_cmd_type type, const char *uri);
792 
793 /**
794    Cancels a pending HTTP request.
795 
796    Cancels an ongoing HTTP request.  The callback associated with this request
797    is not executed and the request object is freed.  If the request is
798    currently being processed, e.g. it is ongoing, the corresponding
799    evhttp_connection object is going to get reset.
800 
801    A request cannot be canceled if its callback has executed already. A request
802    may be canceled reentrantly from its chunked callback.
803 
804    @param req the evhttp_request to cancel; req becomes invalid after this call.
805 */
806 EVENT2_EXPORT_SYMBOL
807 void evhttp_cancel_request(struct evhttp_request *req);
808 
809 /**
810  * A structure to hold a parsed URI or Relative-Ref conforming to RFC3986.
811  */
812 struct evhttp_uri;
813 
814 /** Returns the request URI */
815 EVENT2_EXPORT_SYMBOL
816 const char *evhttp_request_get_uri(const struct evhttp_request *req);
817 /** Returns the request URI (parsed) */
818 EVENT2_EXPORT_SYMBOL
819 const struct evhttp_uri *evhttp_request_get_evhttp_uri(const struct evhttp_request *req);
820 /** Returns the request command */
821 EVENT2_EXPORT_SYMBOL
822 enum evhttp_cmd_type evhttp_request_get_command(const struct evhttp_request *req);
823 
824 EVENT2_EXPORT_SYMBOL
825 int evhttp_request_get_response_code(const struct evhttp_request *req);
826 EVENT2_EXPORT_SYMBOL
827 const char * evhttp_request_get_response_code_line(const struct evhttp_request *req);
828 
829 /** Returns the input headers */
830 EVENT2_EXPORT_SYMBOL
831 struct evkeyvalq *evhttp_request_get_input_headers(struct evhttp_request *req);
832 /** Returns the output headers */
833 EVENT2_EXPORT_SYMBOL
834 struct evkeyvalq *evhttp_request_get_output_headers(struct evhttp_request *req);
835 /** Returns the input buffer */
836 EVENT2_EXPORT_SYMBOL
837 struct evbuffer *evhttp_request_get_input_buffer(struct evhttp_request *req);
838 /** Returns the output buffer */
839 EVENT2_EXPORT_SYMBOL
840 struct evbuffer *evhttp_request_get_output_buffer(struct evhttp_request *req);
841 /** Returns the host associated with the request. If a client sends an absolute
842     URI, the host part of that is preferred. Otherwise, the input headers are
843     searched for a Host: header. NULL is returned if no absolute URI or Host:
844     header is provided. */
845 EVENT2_EXPORT_SYMBOL
846 const char *evhttp_request_get_host(struct evhttp_request *req);
847 
848 /* Interfaces for dealing with HTTP headers */
849 
850 /**
851    Finds the value belonging to a header.
852 
853    @param headers the evkeyvalq object in which to find the header
854    @param key the name of the header to find
855    @returns a pointer to the value for the header or NULL if the header
856      could not be found.
857    @see evhttp_add_header(), evhttp_remove_header()
858 */
859 EVENT2_EXPORT_SYMBOL
860 const char *evhttp_find_header(const struct evkeyvalq *headers,
861     const char *key);
862 
863 /**
864    Removes a header from a list of existing headers.
865 
866    @param headers the evkeyvalq object from which to remove a header
867    @param key the name of the header to remove
868    @returns 0 if the header was removed, -1  otherwise.
869    @see evhttp_find_header(), evhttp_add_header()
870 */
871 EVENT2_EXPORT_SYMBOL
872 int evhttp_remove_header(struct evkeyvalq *headers, const char *key);
873 
874 /**
875    Adds a header to a list of existing headers.
876 
877    @param headers the evkeyvalq object to which to add a header
878    @param key the name of the header
879    @param value the value belonging to the header
880    @returns 0 on success, -1  otherwise.
881    @see evhttp_find_header(), evhttp_clear_headers()
882 */
883 EVENT2_EXPORT_SYMBOL
884 int evhttp_add_header(struct evkeyvalq *headers, const char *key, const char *value);
885 
886 /**
887    Removes all headers from the header list.
888 
889    @param headers the evkeyvalq object from which to remove all headers
890 */
891 EVENT2_EXPORT_SYMBOL
892 void evhttp_clear_headers(struct evkeyvalq *headers);
893 
894 /* Miscellaneous utility functions */
895 
896 
897 /**
898    Helper function to encode a string for inclusion in a URI.  All
899    characters are replaced by their hex-escaped (%22) equivalents,
900    except for characters explicitly unreserved by RFC3986 -- that is,
901    ASCII alphanumeric characters, hyphen, dot, underscore, and tilde.
902 
903    The returned string must be freed by the caller.
904 
905    @param str an unencoded string
906    @return a newly allocated URI-encoded string or NULL on failure
907  */
908 EVENT2_EXPORT_SYMBOL
909 char *evhttp_encode_uri(const char *str);
910 
911 /**
912    As evhttp_encode_uri, but if 'size' is nonnegative, treat the string
913    as being 'size' bytes long.  This allows you to encode strings that
914    may contain 0-valued bytes.
915 
916    The returned string must be freed by the caller.
917 
918    @param str an unencoded string
919    @param size the length of the string to encode, or -1 if the string
920       is NUL-terminated
921    @param space_to_plus if true, space characters in 'str' are encoded
922       as +, not %20.
923    @return a newly allocate URI-encoded string, or NULL on failure.
924  */
925 EVENT2_EXPORT_SYMBOL
926 char *evhttp_uriencode(const char *str, ev_ssize_t size, int space_to_plus);
927 
928 /**
929   Helper function to sort of decode a URI-encoded string.  Unlike
930   evhttp_get_decoded_uri, it decodes all plus characters that appear
931   _after_ the first question mark character, but no plusses that occur
932   before.  This is not a good way to decode URIs in whole or in part.
933 
934   The returned string must be freed by the caller
935 
936   @deprecated  This function is deprecated; you probably want to use
937      evhttp_get_decoded_uri instead.
938 
939   @param uri an encoded URI
940   @return a newly allocated unencoded URI or NULL on failure
941  */
942 EVENT2_EXPORT_SYMBOL
943 char *evhttp_decode_uri(const char *uri);
944 
945 /**
946   Helper function to decode a URI-escaped string or HTTP parameter.
947 
948   If 'decode_plus' is 1, then we decode the string as an HTTP parameter
949   value, and convert all plus ('+') characters to spaces.  If
950   'decode_plus' is 0, we leave all plus characters unchanged.
951 
952   The returned string must be freed by the caller.
953 
954   @param uri a URI-encode encoded URI
955   @param decode_plus determines whether we convert '+' to space.
956   @param size_out if size_out is not NULL, *size_out is set to the size of the
957      returned string
958   @return a newly allocated unencoded URI or NULL on failure
959  */
960 EVENT2_EXPORT_SYMBOL
961 char *evhttp_uridecode(const char *uri, int decode_plus,
962     size_t *size_out);
963 
964 /**
965    Helper function to parse out arguments in a query.
966 
967    Parsing a URI like
968 
969       http://foo.com/?q=test&s=some+thing
970 
971    will result in two entries in the key value queue.
972 
973    The first entry is: key="q", value="test"
974    The second entry is: key="s", value="some thing"
975 
976    @deprecated This function is deprecated as of Libevent 2.0.9.  Use
977      evhttp_uri_parse and evhttp_parse_query_str instead.
978 
979    @param uri the request URI
980    @param headers the head of the evkeyval queue
981    @return 0 on success, -1 on failure
982  */
983 EVENT2_EXPORT_SYMBOL
984 int evhttp_parse_query(const char *uri, struct evkeyvalq *headers);
985 
986 /**
987    Helper function to parse out arguments from the query portion of an
988    HTTP URI.
989 
990    Parsing a query string like
991 
992      q=test&s=some+thing
993 
994    will result in two entries in the key value queue.
995 
996    The first entry is: key="q", value="test"
997    The second entry is: key="s", value="some thing"
998 
999    @param query_parse the query portion of the URI
1000    @param headers the head of the evkeyval queue
1001    @return 0 on success, -1 on failure
1002  */
1003 EVENT2_EXPORT_SYMBOL
1004 int evhttp_parse_query_str(const char *uri, struct evkeyvalq *headers);
1005 
1006 /**
1007  * Escape HTML character entities in a string.
1008  *
1009  * Replaces <, >, ", ' and & with &lt;, &gt;, &quot;,
1010  * &#039; and &amp; correspondingly.
1011  *
1012  * The returned string needs to be freed by the caller.
1013  *
1014  * @param html an unescaped HTML string
1015  * @return an escaped HTML string or NULL on error
1016  */
1017 EVENT2_EXPORT_SYMBOL
1018 char *evhttp_htmlescape(const char *html);
1019 
1020 /**
1021  * Return a new empty evhttp_uri with no fields set.
1022  */
1023 EVENT2_EXPORT_SYMBOL
1024 struct evhttp_uri *evhttp_uri_new(void);
1025 
1026 /**
1027  * Changes the flags set on a given URI.  See EVHTTP_URI_* for
1028  * a list of flags.
1029  **/
1030 EVENT2_EXPORT_SYMBOL
1031 void evhttp_uri_set_flags(struct evhttp_uri *uri, unsigned flags);
1032 
1033 /** Return the scheme of an evhttp_uri, or NULL if there is no scheme has
1034  * been set and the evhttp_uri contains a Relative-Ref. */
1035 EVENT2_EXPORT_SYMBOL
1036 const char *evhttp_uri_get_scheme(const struct evhttp_uri *uri);
1037 /**
1038  * Return the userinfo part of an evhttp_uri, or NULL if it has no userinfo
1039  * set.
1040  */
1041 EVENT2_EXPORT_SYMBOL
1042 const char *evhttp_uri_get_userinfo(const struct evhttp_uri *uri);
1043 /**
1044  * Return the host part of an evhttp_uri, or NULL if it has no host set.
1045  * The host may either be a regular hostname (conforming to the RFC 3986
1046  * "regname" production), or an IPv4 address, or the empty string, or a
1047  * bracketed IPv6 address, or a bracketed 'IP-Future' address.
1048  *
1049  * Note that having a NULL host means that the URI has no authority
1050  * section, but having an empty-string host means that the URI has an
1051  * authority section with no host part.  For example,
1052  * "mailto:user@example.com" has a host of NULL, but "file:///etc/motd"
1053  * has a host of "".
1054  */
1055 EVENT2_EXPORT_SYMBOL
1056 const char *evhttp_uri_get_host(const struct evhttp_uri *uri);
1057 /** Return the port part of an evhttp_uri, or -1 if there is no port set. */
1058 EVENT2_EXPORT_SYMBOL
1059 int evhttp_uri_get_port(const struct evhttp_uri *uri);
1060 /** Return the path part of an evhttp_uri, or NULL if it has no path set */
1061 EVENT2_EXPORT_SYMBOL
1062 const char *evhttp_uri_get_path(const struct evhttp_uri *uri);
1063 /** Return the query part of an evhttp_uri (excluding the leading "?"), or
1064  * NULL if it has no query set */
1065 EVENT2_EXPORT_SYMBOL
1066 const char *evhttp_uri_get_query(const struct evhttp_uri *uri);
1067 /** Return the fragment part of an evhttp_uri (excluding the leading "#"),
1068  * or NULL if it has no fragment set */
1069 EVENT2_EXPORT_SYMBOL
1070 const char *evhttp_uri_get_fragment(const struct evhttp_uri *uri);
1071 
1072 /** Set the scheme of an evhttp_uri, or clear the scheme if scheme==NULL.
1073  * Returns 0 on success, -1 if scheme is not well-formed. */
1074 EVENT2_EXPORT_SYMBOL
1075 int evhttp_uri_set_scheme(struct evhttp_uri *uri, const char *scheme);
1076 /** Set the userinfo of an evhttp_uri, or clear the userinfo if userinfo==NULL.
1077  * Returns 0 on success, -1 if userinfo is not well-formed. */
1078 EVENT2_EXPORT_SYMBOL
1079 int evhttp_uri_set_userinfo(struct evhttp_uri *uri, const char *userinfo);
1080 /** Set the host of an evhttp_uri, or clear the host if host==NULL.
1081  * Returns 0 on success, -1 if host is not well-formed. */
1082 EVENT2_EXPORT_SYMBOL
1083 int evhttp_uri_set_host(struct evhttp_uri *uri, const char *host);
1084 /** Set the port of an evhttp_uri, or clear the port if port==-1.
1085  * Returns 0 on success, -1 if port is not well-formed. */
1086 EVENT2_EXPORT_SYMBOL
1087 int evhttp_uri_set_port(struct evhttp_uri *uri, int port);
1088 /** Set the path of an evhttp_uri, or clear the path if path==NULL.
1089  * Returns 0 on success, -1 if path is not well-formed. */
1090 EVENT2_EXPORT_SYMBOL
1091 int evhttp_uri_set_path(struct evhttp_uri *uri, const char *path);
1092 /** Set the query of an evhttp_uri, or clear the query if query==NULL.
1093  * The query should not include a leading "?".
1094  * Returns 0 on success, -1 if query is not well-formed. */
1095 EVENT2_EXPORT_SYMBOL
1096 int evhttp_uri_set_query(struct evhttp_uri *uri, const char *query);
1097 /** Set the fragment of an evhttp_uri, or clear the fragment if fragment==NULL.
1098  * The fragment should not include a leading "#".
1099  * Returns 0 on success, -1 if fragment is not well-formed. */
1100 EVENT2_EXPORT_SYMBOL
1101 int evhttp_uri_set_fragment(struct evhttp_uri *uri, const char *fragment);
1102 
1103 /**
1104  * Helper function to parse a URI-Reference as specified by RFC3986.
1105  *
1106  * This function matches the URI-Reference production from RFC3986,
1107  * which includes both URIs like
1108  *
1109  *    scheme://[[userinfo]@]foo.com[:port]]/[path][?query][#fragment]
1110  *
1111  *  and relative-refs like
1112  *
1113  *    [path][?query][#fragment]
1114  *
1115  * Any optional elements portions not present in the original URI are
1116  * left set to NULL in the resulting evhttp_uri.  If no port is
1117  * specified, the port is set to -1.
1118  *
1119  * Note that no decoding is performed on percent-escaped characters in
1120  * the string; if you want to parse them, use evhttp_uridecode or
1121  * evhttp_parse_query_str as appropriate.
1122  *
1123  * Note also that most URI schemes will have additional constraints that
1124  * this function does not know about, and cannot check.  For example,
1125  * mailto://www.example.com/cgi-bin/fortune.pl is not a reasonable
1126  * mailto url, http://www.example.com:99999/ is not a reasonable HTTP
1127  * URL, and ftp:username@example.com is not a reasonable FTP URL.
1128  * Nevertheless, all of these URLs conform to RFC3986, and this function
1129  * accepts all of them as valid.
1130  *
1131  * @param source_uri the request URI
1132  * @param flags Zero or more EVHTTP_URI_* flags to affect the behavior
1133  *              of the parser.
1134  * @return uri container to hold parsed data, or NULL if there is error
1135  * @see evhttp_uri_free()
1136  */
1137 EVENT2_EXPORT_SYMBOL
1138 struct evhttp_uri *evhttp_uri_parse_with_flags(const char *source_uri,
1139     unsigned flags);
1140 
1141 /** Tolerate URIs that do not conform to RFC3986.
1142  *
1143  * Unfortunately, some HTTP clients generate URIs that, according to RFC3986,
1144  * are not conformant URIs.  If you need to support these URIs, you can
1145  * do so by passing this flag to evhttp_uri_parse_with_flags.
1146  *
1147  * Currently, these changes are:
1148  * <ul>
1149  *   <li> Nonconformant URIs are allowed to contain otherwise unreasonable
1150  *        characters in their path, query, and fragment components.
1151  * </ul>
1152  */
1153 #define EVHTTP_URI_NONCONFORMANT 0x01
1154 
1155 /** Alias for evhttp_uri_parse_with_flags(source_uri, 0) */
1156 EVENT2_EXPORT_SYMBOL
1157 struct evhttp_uri *evhttp_uri_parse(const char *source_uri);
1158 
1159 /**
1160  * Free all memory allocated for a parsed uri.  Only use this for URIs
1161  * generated by evhttp_uri_parse.
1162  *
1163  * @param uri container with parsed data
1164  * @see evhttp_uri_parse()
1165  */
1166 EVENT2_EXPORT_SYMBOL
1167 void evhttp_uri_free(struct evhttp_uri *uri);
1168 
1169 /**
1170  * Join together the uri parts from parsed data to form a URI-Reference.
1171  *
1172  * Note that no escaping of reserved characters is done on the members
1173  * of the evhttp_uri, so the generated string might not be a valid URI
1174  * unless the members of evhttp_uri are themselves valid.
1175  *
1176  * @param uri container with parsed data
1177  * @param buf destination buffer
1178  * @param limit destination buffer size
1179  * @return an joined uri as string or NULL on error
1180  * @see evhttp_uri_parse()
1181  */
1182 EVENT2_EXPORT_SYMBOL
1183 char *evhttp_uri_join(struct evhttp_uri *uri, char *buf, size_t limit);
1184 
1185 #ifdef __cplusplus
1186 }
1187 #endif
1188 
1189 #endif /* EVENT2_HTTP_H_INCLUDED_ */
1190