external/bsd/libevent/dist/evhttp.h

   1 /*      $NetBSD$        */
   2 /*
   3  * Copyright (c) 2000-2004 Niels Provos <provos@citi.umich.edu>
   4  * All rights reserved.
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  * 3. The name of the author may not be used to endorse or promote products
  15  *    derived from this software without specific prior written permission.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  */
  28 #ifndef _EVHTTP_H_
  29 #define _EVHTTP_H_
  30
  31 #include <event.h>
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 #ifdef WIN32
  38 #define WIN32_LEAN_AND_MEAN
  39 #include <winsock2.h>
  40 #include <windows.h>
  41 #undef WIN32_LEAN_AND_MEAN
  42 #endif
  43
  44 /** @file evhttp.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
  57 #define HTTP_NOCONTENT          204
  58 #define HTTP_MOVEPERM           301
  59 #define HTTP_MOVETEMP           302
  60 #define HTTP_NOTMODIFIED        304
  61 #define HTTP_BADREQUEST         400
  62 #define HTTP_NOTFOUND           404
  63 #define HTTP_SERVUNAVAIL        503
  64
  65 struct evhttp;
  66 struct evhttp_request;
  67 struct evkeyvalq;
  68
  69 /** Create a new HTTP server
  70  *
  71  * @param base (optional) the event base to receive the HTTP events
  72  * @return a pointer to a newly initialized evhttp server structure
  73  */
  74 struct evhttp *evhttp_new(struct event_base *base);
  75
  76 /**
  77  * Binds an HTTP server on the specified address and port.
  78  *
  79  * Can be called multiple times to bind the same http server
  80  * to multiple different ports.
  81  *
  82  * @param http a pointer to an evhttp object
  83  * @param address a string containing the IP address to listen(2) on
  84  * @param port the port number to listen on
  85  * @return a newly allocated evhttp struct
  86  * @see evhttp_free()
  87  */
  88 int evhttp_bind_socket(struct evhttp *http, const char *address, u_short port);
  89
  90 /**
  91  * Makes an HTTP server accept connections on the specified socket
  92  *
  93  * This may be useful to create a socket and then fork multiple instances
  94  * of an http server, or when a socket has been communicated via file
  95  * descriptor passing in situations where an http servers does not have
  96  * permissions to bind to a low-numbered port.
  97  *
  98  * Can be called multiple times to have the http server listen to
  99  * multiple different sockets.
 100  *
 101  * @param http a pointer to an evhttp object
 102  * @param fd a socket fd that is ready for accepting connections
 103  * @return 0 on success, -1 on failure.
 104  * @see evhttp_free(), evhttp_bind_socket()
 105  */
 106 int evhttp_accept_socket(struct evhttp *http, int fd);
 107
 108 /**
 109  * Free the previously created HTTP server.
 110  *
 111  * Works only if no requests are currently being served.
 112  *
 113  * @param http the evhttp server object to be freed
 114  * @see evhttp_start()
 115  */
 116 void evhttp_free(struct evhttp* http);
 117
 118 /** Set a callback for a specified URI */
 119 void evhttp_set_cb(struct evhttp *, const char *,
 120     void (*)(struct evhttp_request *, void *), void *);
 121
 122 /** Removes the callback for a specified URI */
 123 int evhttp_del_cb(struct evhttp *, const char *);
 124
 125 /** Set a callback for all requests that are not caught by specific callbacks
 126  */
 127 void evhttp_set_gencb(struct evhttp *,
 128     void (*)(struct evhttp_request *, void *), void *);
 129
 130 /**
 131  * Set the timeout for an HTTP request.
 132  *
 133  * @param http an evhttp object
 134  * @param timeout_in_secs the timeout, in seconds
 135  */
 136 void evhttp_set_timeout(struct evhttp *, int timeout_in_secs);
 137
 138 /* Request/Response functionality */
 139
 140 /**
 141  * Send an HTML error message to the client.
 142  *
 143  * @param req a request object
 144  * @param error the HTTP error code
 145  * @param reason a brief explanation of the error
 146  */
 147 void evhttp_send_error(struct evhttp_request *req, int error,
 148     const char *reason);
 149
 150 /**
 151  * Send an HTML reply to the client.
 152  *
 153  * @param req a request object
 154  * @param code the HTTP response code to send
 155  * @param reason a brief message to send with the response code
 156  * @param databuf the body of the response
 157  */
 158 void evhttp_send_reply(struct evhttp_request *req, int code,
 159     const char *reason, struct evbuffer *databuf);
 160
 161 /* Low-level response interface, for streaming/chunked replies */
 162 void evhttp_send_reply_start(struct evhttp_request *, int, const char *);
 163 void evhttp_send_reply_chunk(struct evhttp_request *, struct evbuffer *);
 164 void evhttp_send_reply_end(struct evhttp_request *);
 165
 166 /**
 167  * Start an HTTP server on the specified address and port
 168  *
 169  * DEPRECATED: it does not allow an event base to be specified
 170  *
 171  * @param address the address to which the HTTP server should be bound
 172  * @param port the port number on which the HTTP server should listen
 173  * @return an struct evhttp object
 174  */
 175 struct evhttp *evhttp_start(const char *address, u_short port);
 176
 177 /*
 178  * Interfaces for making requests
 179  */
 180 enum evhttp_cmd_type { EVHTTP_REQ_GET, EVHTTP_REQ_POST, EVHTTP_REQ_HEAD };
 181
 182 enum evhttp_request_kind { EVHTTP_REQUEST, EVHTTP_RESPONSE };
 183
 184 /**
 185  * the request structure that a server receives.
 186  * WARNING: expect this structure to change.  I will try to provide
 187  * reasonable accessors.
 188  */
 189 struct evhttp_request {
 190 #if defined(TAILQ_ENTRY)
 191         TAILQ_ENTRY(evhttp_request) next;
 192 #else
 193 struct {
 194         struct evhttp_request *tqe_next;
 195         struct evhttp_request **tqe_prev;
 196 }       next;
 197 #endif
 198
 199         /* the connection object that this request belongs to */
 200         struct evhttp_connection *evcon;
 201         int flags;
 202 #define EVHTTP_REQ_OWN_CONNECTION       0x0001
 203 #define EVHTTP_PROXY_REQUEST            0x0002
 204
 205         struct evkeyvalq *input_headers;
 206         struct evkeyvalq *output_headers;
 207
 208         /* address of the remote host and the port connection came from */
 209         char *remote_host;
 210         u_short remote_port;
 211
 212         enum evhttp_request_kind kind;
 213         enum evhttp_cmd_type type;
 214
 215         char *uri;                      /* uri after HTTP request was parsed */
 216
 217         char major;                     /* HTTP Major number */
 218         char minor;                     /* HTTP Minor number */
 219
 220         int response_code;              /* HTTP Response code */
 221         char *response_code_line;       /* Readable response */
 222
 223         struct evbuffer *input_buffer;  /* read data */
 224         ev_int64_t ntoread;
 225         int chunked;
 226
 227         struct evbuffer *output_buffer; /* outgoing post or data */
 228
 229         /* Callback */
 230         void (*cb)(struct evhttp_request *, void *);
 231         void *cb_arg;
 232
 233         /*
 234          * Chunked data callback - call for each completed chunk if
 235          * specified.  If not specified, all the data is delivered via
 236          * the regular callback.
 237          */
 238         void (*chunk_cb)(struct evhttp_request *, void *);
 239 };
 240
 241 /**
 242  * Creates a new request object that needs to be filled in with the request
 243  * parameters.  The callback is executed when the request completed or an
 244  * error occurred.
 245  */
 246 struct evhttp_request *evhttp_request_new(
 247         void (*cb)(struct evhttp_request *, void *), void *arg);
 248
 249 /** enable delivery of chunks to requestor */
 250 void evhttp_request_set_chunked_cb(struct evhttp_request *,
 251     void (*cb)(struct evhttp_request *, void *));
 252
 253 /** Frees the request object and removes associated events. */
 254 void evhttp_request_free(struct evhttp_request *req);
 255
 256 /**
 257  * A connection object that can be used to for making HTTP requests.  The
 258  * connection object tries to establish the connection when it is given an
 259  * http request object.
 260  */
 261 struct evhttp_connection *evhttp_connection_new(
 262         const char *address, unsigned short port);
 263
 264 /** Frees an http connection */
 265 void evhttp_connection_free(struct evhttp_connection *evcon);
 266
 267 /** sets the ip address from which http connections are made */
 268 void evhttp_connection_set_local_address(struct evhttp_connection *evcon,
 269     const char *address);
 270
 271 /** sets the local port from which http connections are made */
 272 void evhttp_connection_set_local_port(struct evhttp_connection *evcon,
 273     unsigned short port);
 274
 275 /** Sets the timeout for events related to this connection */
 276 void evhttp_connection_set_timeout(struct evhttp_connection *evcon,
 277     int timeout_in_secs);
 278
 279 /** Sets the retry limit for this connection - -1 repeats indefnitely */
 280 void evhttp_connection_set_retries(struct evhttp_connection *evcon,
 281     int retry_max);
 282
 283 /** Set a callback for connection close. */
 284 void evhttp_connection_set_closecb(struct evhttp_connection *evcon,
 285     void (*)(struct evhttp_connection *, void *), void *);
 286
 287 /**
 288  * Associates an event base with the connection - can only be called
 289  * on a freshly created connection object that has not been used yet.
 290  */
 291 void evhttp_connection_set_base(struct evhttp_connection *evcon,
 292     struct event_base *base);
 293
 294 /** Get the remote address and port associated with this connection. */
 295 void evhttp_connection_get_peer(struct evhttp_connection *evcon,
 296     char **address, u_short *port);
 297
 298 /** The connection gets ownership of the request */
 299 int evhttp_make_request(struct evhttp_connection *evcon,
 300     struct evhttp_request *req,
 301     enum evhttp_cmd_type type, const char *uri);
 302
 303 const char *evhttp_request_uri(struct evhttp_request *req);
 304
 305 /* Interfaces for dealing with HTTP headers */
 306
 307 const char *evhttp_find_header(const struct evkeyvalq *, const char *);
 308 int evhttp_remove_header(struct evkeyvalq *, const char *);
 309 int evhttp_add_header(struct evkeyvalq *, const char *, const char *);
 310 void evhttp_clear_headers(struct evkeyvalq *);
 311
 312 /* Miscellaneous utility functions */
 313
 314
 315 /**
 316   Helper function to encode a URI.
 317
 318   The returned string must be freed by the caller.
 319
 320   @param uri an unencoded URI
 321   @return a newly allocated URI-encoded string
 322  */
 323 char *evhttp_encode_uri(const char *uri);
 324
 325
 326 /**
 327   Helper function to decode a URI.
 328
 329   The returned string must be freed by the caller.
 330
 331   @param uri an encoded URI
 332   @return a newly allocated unencoded URI
 333  */
 334 char *evhttp_decode_uri(const char *uri);
 335
 336
 337 /**
 338  * Helper function to parse out arguments in a query.
 339  *
 340  * Parsing a uri like
 341  *
 342  *    http://foo.com/?q=test&s=some+thing
 343  *
 344  * will result in two entries in the key value queue.
 345
 346  * The first entry is: key="q", value="test"
 347  * The second entry is: key="s", value="some thing"
 348  *
 349  * @param uri the request URI
 350  * @param headers the head of the evkeyval queue
 351  */
 352 void evhttp_parse_query(const char *uri, struct evkeyvalq *headers);
 353
 354
 355 /**
 356  * Escape HTML character entities in a string.
 357  *
 358  * Replaces <, >, ", ' and & with &lt;, &gt;, &quot;,
 359  * &#039; and &amp; correspondingly.
 360  *
 361  * The returned string needs to be freed by the caller.
 362  *
 363  * @param html an unescaped HTML string
 364  * @return an escaped HTML string
 365  */
 366 char *evhttp_htmlescape(const char *html);
 367
 368 #ifdef __cplusplus
 369 }
 370 #endif
 371
 372 #endif /* _EVHTTP_H_ */