vendor/shttpd/shttpd.h

   1 /*
   2  * Copyright (c) 2004-2008 Sergey Lyubka <valenok@gmail.com>
   3  * All rights reserved
   4  *
   5  * "THE BEER-WARE LICENSE" (Revision 42):
   6  * Sergey Lyubka wrote this file.  As long as you retain this notice you
   7  * can do whatever you want with this stuff. If we meet some day, and you think
   8  * this stuff is worth it, you can buy me a beer in return.
   9  *
  10  * $Id: shttpd.h,v 1.18 2008/08/23 08:34:50 drozd Exp $
  11  */
  12
  13 #ifndef SHTTPD_HEADER_INCLUDED
  14 #define SHTTPD_HEADER_INCLUDED
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif /* __cplusplus */
  19
  20 struct ubuf {
  21         char            *buf;           /* Buffer pointer               */
  22         int             len;            /* Size of a buffer             */
  23         int             num_bytes;      /* Bytes processed by callback  */
  24 };
  25
  26 /*
  27  * This structure is passed to the user callback function
  28  */
  29 struct shttpd_arg {
  30         void            *priv;          /* Private! Do not touch!       */
  31         void            *state;         /* User state                   */
  32         void            *user_data;     /* Data from register_uri()     */
  33         struct ubuf     in;             /* Input is here, POST data     */
  34         struct ubuf     out;            /* Output goes here             */
  35
  36         unsigned int    flags;
  37 #define SHTTPD_END_OF_OUTPUT    1       /* No more data do send         */
  38 #define SHTTPD_CONNECTION_ERROR 2       /* Server closed the connection */
  39 #define SHTTPD_MORE_POST_DATA   4       /* arg->in has incomplete data  */
  40 #define SHTTPD_POST_BUFFER_FULL 8       /* arg->in has max data         */
  41 #define SHTTPD_SSI_EVAL_TRUE    16      /* SSI eval callback must set it*/
  42 #define SHTTPD_SUSPEND          32      /* User wants to suspend output */
  43 };
  44
  45 /*
  46  * User callback function. Called when certain registered URLs have been
  47  * requested. These are the requirements to the callback function:
  48  *
  49  * 1. It must copy data into 'out.buf' buffer, not more than 'out.len' bytes,
  50  *      and record how many bytes are copied, into 'out.num_bytes'
  51  * 2. It must not call any blocking functions
  52  * 3. It must set SHTTPD_END_OF_OUTPUT flag when there is no more data to send
  53  * 4. For POST requests, it must process the incoming data (in.buf) of length
  54  *      'in.len', and set 'in.num_bytes', which is how many bytes of POST
  55  *      data was processed and can be discarded by SHTTPD.
  56  * 5. If callback allocates arg->state, to keep state, it must deallocate it
  57  *    at the end of coonection SHTTPD_CONNECTION_ERROR or SHTTPD_END_OF_OUTPUT
  58  * 6. If callback function wants to suspend until some event, it must store
  59  *      arg->priv pointer elsewhere, set SHTTPD_SUSPEND flag and return. When
  60  *      the event happens, user code should call shttpd_wakeup(priv).
  61  *      It is safe to call shttpd_wakeup() from any thread. User code must
  62  *      not call shttpd_wakeup once the connection is closed.
  63  */
  64 typedef void (*shttpd_callback_t)(struct shttpd_arg *);
  65
  66 /*
  67  * shttpd_init          Initialize shttpd context
  68  * shttpd_fini          Dealocate the context, close all connections
  69  * shttpd_set_option    Set new value for option
  70  * shttpd_register_uri  Setup the callback function for specified URL
  71  * shttpd_poll          Do connections processing
  72  * shttpd_version       return string with SHTTPD version
  73  * shttpd_get_var       Fetch POST/GET variable value by name. Return value len
  74  * shttpd_get_header    return value of the specified HTTP header
  75  * shttpd_get_env       return values for the following pseudo-variables:
  76                         "REQUEST_METHOD", "REQUEST_URI",
  77  *                      "REMOTE_USER" and "REMOTE_ADDR"
  78  * shttpd_printf        helper function to output data
  79  * shttpd_handle_error  register custom HTTP error handler
  80  * shttpd_wakeup        clear SHTTPD_SUSPEND state for the connection
  81  */
  82
  83 struct shttpd_ctx;
  84
  85 struct shttpd_ctx *shttpd_init(int argc, char *argv[]);
  86 int shttpd_set_option(struct shttpd_ctx *, const char *opt, const char *val);
  87 void shttpd_fini(struct shttpd_ctx *);
  88 void shttpd_register_uri(struct shttpd_ctx *ctx, const char *uri,
  89                 shttpd_callback_t callback, void *const user_data);
  90 void shttpd_poll(struct shttpd_ctx *, int milliseconds);
  91 const char *shttpd_version(void);
  92 int shttpd_get_var(const char *var, const char *buf, int buf_len,
  93                 char *value, int value_len);
  94 const char *shttpd_get_header(struct shttpd_arg *, const char *header_name);
  95 const char *shttpd_get_env(struct shttpd_arg *, const char *name);
  96 void shttpd_get_http_version(struct shttpd_arg *,
  97                 unsigned long *major, unsigned long *minor);
  98 size_t shttpd_printf(struct shttpd_arg *, const char *fmt, ...);
  99 void shttpd_handle_error(struct shttpd_ctx *ctx, int status,
 100                 shttpd_callback_t func, void *const data);
 101 void shttpd_register_ssi_func(struct shttpd_ctx *ctx, const char *name,
 102                 shttpd_callback_t func, void *const user_data);
 103 void shttpd_wakeup(const void *priv);
 104 int shttpd_join(struct shttpd_ctx *, fd_set *, fd_set *, int *max_fd);
 105 int  shttpd_socketpair(int sp[2]);
 106
 107 #ifdef __cplusplus
 108 }
 109 #endif /* __cplusplus */
 110
 111 #endif /* SHTTPD_HEADER_INCLUDED */