libs/shttpd/include/shttpd.h

   1 /*
   2  * Copyright (c) 2004-2005 Sergey Lyubka <valenok@gmail.com>
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a
   5  * copy of this software and associated documentation files (the "Software"),
   6  * to deal in the Software without restriction, including without limitation
   7  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8  * and/or sell copies of the Software, and to permit persons to whom the
   9  * Software is furnished to do so, subject to the following conditions:
  10  *
  11  * The above copyright notice and this permission notice shall be included
  12  * in all copies or substantial portions of the Software.
  13  *
  14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  20  * DEALINGS IN THE SOFTWARE.
  21  *
  22  * $Id: shttpd.h,v 1.3 2007/04/11 13:01:53 drozd Exp $
  23  */
  24
  25 #ifndef SHTTPD_HEADER_INCLUDED
  26 #define SHTTPD_HEADER_INCLUDED
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif /* __cplusplus */
  31
  32 struct ubuf {
  33         char            *buf;           /* Buffer pointer               */
  34         int             len;            /* Size of a buffer             */
  35         int             num_bytes;      /* Bytes processed by callback  */
  36 };
  37
  38 /*
  39  * This structure is passed to the user callback function
  40  */
  41 struct shttpd_arg {
  42         void            *priv;          /* Private! Do not touch!       */
  43         void            *state;         /* User state                   */
  44         void            *user_data;     /* User-defined data            */
  45         struct ubuf     in;             /* Input is here, POST data     */
  46         struct ubuf     out;            /* Output goes here             */
  47         unsigned int    flags;
  48 #define SHTTPD_END_OF_OUTPUT    1
  49 #define SHTTPD_CONNECTION_ERROR 2
  50 #define SHTTPD_MORE_POST_DATA   4
  51 #define SHTTPD_POST_BUFFER_FULL 8
  52 #define SHTTPD_SSI_EVAL_TRUE    16
  53 };
  54
  55 /*
  56  * User callback function. Called when certain registered URLs have been
  57  * requested. These are the requirements to the callback function:
  58  *
  59  * 1. it must copy data into 'out.buf' buffer, not more than 'out.len' bytes,
  60  *      and record how many bytes are copied, into 'out.num_bytes'
  61  * 2. it must not block the execution
  62  * 3. it must set SHTTPD_END_OF_OUTPUT flag when finished
  63  * 4. for POST requests, it must process the incoming data (in.buf) of length
  64  *      'in.len', and set 'in.num_bytes', which is how many bytes of POST
  65  *      data is read and can be discarded by SHTTPD.
  66  */
  67 typedef void (*shttpd_callback_t)(struct shttpd_arg *);
  68
  69 /*
  70  * shttpd_init          Initialize shttpd context. Parameters: configuration
  71  *                      file name (may be NULL), then NULL-terminated
  72  *                      sequence of pairs "option_name", "option_value".
  73  * shttpd_init2         Same as shttpd_init, but the list of option/value
  74  *                      pairs is passed in arrays
  75  * shttpd_fini          Dealocate the context
  76  * shttpd_register_uri  Setup the callback function for specified URL.
  77  * shttpd_protect_uri   Associate authorization file with an URL.
  78  * shttpd_add_mime_type Add mime type
  79  * shtppd_listen        Setup a listening socket in the SHTTPD context
  80  * shttpd_poll          Do connections processing
  81  * shttpd_version       return string with SHTTPD version
  82  * shttpd_get_var       Return POST/GET variable value for given variable name.
  83  * shttpd_get_header    return value of the specified HTTP header
  84  * shttpd_get_env       return string values for the following
  85  *                      pseudo-variables: "REQUEST_METHOD", "REQUEST_URI",
  86  *                      "REMOTE_USER" and "REMOTE_ADDR".
  87  */
  88
  89 struct shttpd_ctx;
  90
  91 struct shttpd_ctx *shttpd_init(const char *config_file, ...);
  92 struct shttpd_ctx *shttpd_init2(const char *config_file,
  93                 char *names[], char *values[], size_t num_options);
  94 void shttpd_fini(struct shttpd_ctx *);
  95 void shttpd_add_mime_type(struct shttpd_ctx *,
  96                 const char *ext, const char *mime);
  97 int shttpd_listen(struct shttpd_ctx *ctx, int port, int is_ssl);
  98 void shttpd_register_uri(struct shttpd_ctx *ctx,
  99                 const char *uri, shttpd_callback_t callback, void *user_data);
 100 void shttpd_protect_uri(struct shttpd_ctx *ctx,
 101                 const char *uri, const char *file);
 102 void shttpd_poll(struct shttpd_ctx *, int milliseconds);
 103 const char *shttpd_version(void);
 104 int shttpd_get_var(const char *var, const char *buf, int buf_len,
 105                 char *value, int value_len);
 106 const char *shttpd_get_header(struct shttpd_arg *, const char *);
 107 const char *shttpd_get_env(struct shttpd_arg *, const char *);
 108 void shttpd_get_http_version(struct shttpd_arg *,
 109                 unsigned long *major, unsigned long *minor);
 110 size_t shttpd_printf(struct shttpd_arg *, const char *fmt, ...);
 111 void shttpd_handle_error(struct shttpd_ctx *ctx, int status,
 112                 shttpd_callback_t func, void *data);
 113 void shttpd_register_ssi_func(struct shttpd_ctx *ctx, const char *name,
 114                 shttpd_callback_t func, void *user_data);
 115
 116 /*
 117  * The following three functions are for applications that need to
 118  * load-balance the connections on their own. Many threads may be spawned
 119  * with one SHTTPD context per thread. Boss thread may only wait for
 120  * new connections by means of shttpd_accept(). Then it may scan thread
 121  * pool for the idle thread by means of shttpd_active(), and add new
 122  * connection to the context by means of shttpd_add().
 123  */
 124 void shttpd_add_socket(struct shttpd_ctx *, int sock);
 125 int shttpd_accept(int lsn_sock, int milliseconds);
 126 int shttpd_active(struct shttpd_ctx *);
 127
 128
 129 #ifdef __cplusplus
 130 }
 131 #endif /* __cplusplus */
 132
 133 #endif /* SHTTPD_HEADER_INCLUDED */