shttpd源码分析(2) 接口简要介绍

好了，现在看看shttpd提供的接口。

 

为了让我们能定制自己的处理方式，shttpd采取了注册回调函数的方式。回调函数类型是shttpd_callback_t，使用shttpd_arg结构来传递参数，shttpd_arg结构中包含输入（来自于请求的数据）、输出的缓冲数据、自定义数据。

 

比如使用shttpd_get_env从arg中获取REQUEST_URI和QUERY_STRING

request_uri = shttpd_get_env(arg, "REQUEST_URI");
query_string = shttpd_get_env(arg, "QUERY_STRING");

 

 

代码中的注释已经比较清楚，直接看代码吧

struct ubuf {
    char        *buf;        /* Buffer pointer        */
    int        len;        /* Size of a buffer        */
    int        num_bytes;    /* Bytes processed by callback    */
};

/*
 * This structure is passed to the user callback function
 */
struct shttpd_arg {
    void        *priv;        /* Private! Do not touch!    */
    void        *state;        /* User state            */
    void        *user_data;    /* User-defined data        */
    struct ubuf    in;        /* Input is here, POST data    */
    struct ubuf    out;        /* Output goes here        */
    unsigned int    flags;
#define    SHTTPD_END_OF_OUTPUT    1
#define    SHTTPD_CONNECTION_ERROR    2
#define    SHTTPD_MORE_POST_DATA    4
#define    SHTTPD_POST_BUFFER_FULL    8
#define    SHTTPD_SSI_EVAL_TRUE    16
};

/*
 * User callback function. Called when certain registered URLs have been
 * requested. These are the requirements to the callback function:
 *
 * 1. it must copy data into 'out.buf' buffer, not more than 'out.len' bytes,
 *    and record how many bytes are copied, into 'out.num_bytes'
 * 2. it must not block the execution
 * 3. it must set SHTTPD_END_OF_OUTPUT flag when finished
 * 4. for POST requests, it must process the incoming data (in.buf) of length
 *    'in.len', and set 'in.num_bytes', which is how many bytes of POST
 *    data is read and can be discarded by SHTTPD.
 */
typedef void (*shttpd_callback_t)(struct shttpd_arg *);

/*
 * shttpd_init        Initialize shttpd context. Parameters: configuration
 *            file name (may be NULL), then NULL-terminated
 *            sequence of pairs "option_name", "option_value".
 * shttpd_init2        Same as shttpd_init, but the list of option/value
 *            pairs is passed in arrays
 * shttpd_fini        Dealocate the context
 * shttpd_register_uri    Setup the callback function for specified URL.
 * shttpd_protect_uri    Associate authorization file with an URL.
 * shttpd_add_mime_type    Add mime type
 * shtppd_listen    Setup a listening socket in the SHTTPD context
 * shttpd_poll        Do connections processing
 * shttpd_version    return string with SHTTPD version
 * shttpd_get_var    Return POST/GET variable value for given variable name.
 * shttpd_get_header    return value of the specified HTTP header
 * shttpd_get_env    return string values for the following
 *            pseudo-variables: "REQUEST_METHOD", "REQUEST_URI",
 *            "REMOTE_USER" and "REMOTE_ADDR".
 */

struct shttpd_ctx;

struct shttpd_ctx *shttpd_init(const char *config_file, ...);
struct shttpd_ctx *shttpd_init2(const char *config_file,
        char *names[], char *values[], size_t num_options);
void shttpd_fini(struct shttpd_ctx *);
void shttpd_add_mime_type(struct shttpd_ctx *,
        const char *ext, const char *mime);
int shttpd_listen(struct shttpd_ctx *ctx, int port, int is_ssl);
void shttpd_register_uri(struct shttpd_ctx *ctx,
        const char *uri, shttpd_callback_t callback, void *user_data);
void shttpd_protect_uri(struct shttpd_ctx *ctx,
        const char *uri, const char *file);
void shttpd_poll(struct shttpd_ctx *, int milliseconds);
const char *shttpd_version(void);
int shttpd_get_var(const char *var, const char *buf, int buf_len,
        char *value, int value_len);
const char *shttpd_get_header(struct shttpd_arg *, const char *);
const char *shttpd_get_env(struct shttpd_arg *, const char *);
void shttpd_get_http_version(struct shttpd_arg *,
        unsigned long *major, unsigned long *minor);
size_t shttpd_printf(struct shttpd_arg *, const char *fmt, ...);
void shttpd_handle_error(struct shttpd_ctx *ctx, int status,
        shttpd_callback_t func, void *data);
void shttpd_register_ssi_func(struct shttpd_ctx *ctx, const char *name,
        shttpd_callback_t func, void *user_data);

/*
 * The following three functions are for applications that need to
 * load-balance the connections on their own. Many threads may be spawned
 * with one SHTTPD context per thread. Boss thread may only wait for
 * new connections by means of shttpd_accept(). Then it may scan thread
 * pool for the idle thread by means of shttpd_active(), and add new
 * connection to the context by means of shttpd_add().
 */
void shttpd_add_socket(struct shttpd_ctx *, int sock);
int shttpd_accept(int lsn_sock, int milliseconds);
int shttpd_active(struct shttpd_ctx *);