lib/silchttp/silchttpserver.h

   1 /*
   2
   3   silchttpserver.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2006 Pekka Riikonen
   8
   9   This program is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU General Public License as published by
  11   the Free Software Foundation; version 2 of the License.
  12
  13   This program is distributed in the hope that it will be useful,
  14   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16   GNU General Public License for more details.
  17
  18 */
  19
  20 /****h* silchttp/SILC HTTP Server Interface
  21  *
  22  * DESCRIPTION
  23  *
  24  * Very simple HTTP server interface.  This HTTP server supports basic HTTP
  25  * features.  All pages on the server are dynamically created by the caller
  26  * of this interface.  The server does not support plugins, modules, cgi-bin,
  27  * server-side includes or any other special features.  Naturally, the caller
  28  * of this interface may itself implement such features.
  29  *
  30  ***/
  31
  32 #ifndef SILCHTTPSERVER_H
  33 #define SILCHTTPSERVER_H
  34
  35 /****s* silchttp/SilcHTTPServer/SilcHttpServer
  36  *
  37  * NAME
  38  *
  39  *    typedef struct SilcHttpServerStruct *SilcHttpServer;
  40  *
  41  * DESCRIPTION
  42  *
  43  *    The actual HTTP server allocated with silc_http_server_alloc and
  44  *    freed with silc_http_server_free.
  45  *
  46  ***/
  47 typedef struct SilcHttpServerStruct *SilcHttpServer;
  48
  49 /****s* silchttp/SilcHTTPServer/SilcHttpConnection
  50  *
  51  * NAME
  52  *
  53  *    typedef struct SilcHttpConnectionStruct *SilcHttpConnection;
  54  *
  55  * DESCRIPTION
  56  *
  57  *    HTTP connection context.  This is allocated by the library and
  58  *    delivered to application in SilcHttpServerCallback callbcak function.
  59  *    It is given as argument to many silc_http_server_* functions.
  60  *    It is freed automatically by the library.
  61  *
  62  ***/
  63 typedef struct SilcHttpConnectionStruct *SilcHttpConnection;
  64
  65 /****f* silchttp/SilcHTTPServer/SilcHttpServerCallback
  66  *
  67  * SYNOPSIS
  68  *
  69  *    typedef void (*SilcHttpServerCallback)(SilcHttpServer httpd,
  70  *                                           SilcHttpConnection conn,
  71  *                                           const char *uri,
  72  *                                           const char *method,
  73  *                                           SilcBuffer data,
  74  *                                           void *context);
  75  *
  76  * DESCRIPTION
  77  *
  78  *    The HTTP request callback that is called everytime a new HTTP request
  79  *    comes from a HTTP client.  The `uri' is the requested URI (web page),
  80  *    and the `method' is the HTTP request method (GET, POST, etc.).  The
  81  *    `data' is non-NULL only if the `method' is POST, and it includes the
  82  *    the POST data.
  83  *
  84  *    The requested web page must be returned to the HTTP client from this
  85  *    callback by calling silc_http_server_send or error is returned by
  86  *    calling silc_http_server_send_error.
  87  *
  88  *    The silc_http_server_get_header may be called to find a specific
  89  *    HTTP header from this request.  New headers may be added to the
  90  *    reply by calling silc_http_server_add_header.
  91  *
  92  ***/
  93 typedef void (*SilcHttpServerCallback)(SilcHttpServer httpd,
  94                                        SilcHttpConnection conn,
  95                                        const char *uri,
  96                                        const char *method,
  97                                        SilcBuffer data,
  98                                        void *context);
  99
 100 /****f* silchttp/SilcHTTPServer/silc_http_server_alloc
 101  *
 102  * SYNOPSIS
 103  *
 104  *    SilcHttpServer
 105  *    silc_http_server_alloc(const char *ip, SilcUInt16 port,
 106  *                           SilcSchedule schedule,
 107  *                           SilcHttpServerCallback callback, void *context);
 108  *
 109  * DESCRIPTION
 110  *
 111  *    Allocates HTTP server and binds it to the IP address `ip' on the
 112  *    `port'.  The `callback' with `context' will be called everytime a new
 113  *    HTTP request comes to the server from a HTTP client.  In that callback
 114  *    the caller must then reply with the requested Web page or with error.
 115  *
 116  ***/
 117 SilcHttpServer silc_http_server_alloc(const char *ip, SilcUInt16 port,
 118                                       SilcSchedule schedule,
 119                                       SilcHttpServerCallback callback,
 120                                       void *context);
 121
 122 /****f* silchttp/SilcHTTPServer/silc_http_server_free
 123  *
 124  * SYNOPSIS
 125  *
 126  *    void silc_http_server_free(SilcHttpServer httpd);
 127  *
 128  * DESCRIPTION
 129  *
 130  *    Close HTTP server and free all resources.
 131  *
 132  ***/
 133 void silc_http_server_free(SilcHttpServer httpd);
 134
 135 /****f* silchttp/SilcHTTPServer/silc_http_server_send
 136  *
 137  * SYNOPSIS
 138  *
 139  *    SilcBool silc_http_server_send(SilcHttpServer httpd,
 140  *                                   SilcHttpConnection conn,
 141  *                                   SilcBuffer data);
 142  *
 143  * DESCRIPTION
 144  *
 145  *    Send the HTTP data indicated by `data' buffer into the connection
 146  *    indicated by `conn'.  Returns TRUE after the data is sent, and FALSE
 147  *    if error occurred.  Usually the `data' would be the requested web page.
 148  *
 149  ***/
 150 SilcBool silc_http_server_send(SilcHttpServer httpd,
 151                                SilcHttpConnection conn,
 152                                SilcBuffer data);
 153
 154 /****f* silchttp/SilcHTTPServer/silc_http_server_send_error
 155  *
 156  * SYNOPSIS
 157  *
 158  *    SilcBool silc_http_server_send_error(SilcHttpServer httpd,
 159  *                                         SilcHttpConnection conn,
 160  *                                         const char *error,
 161  *                                         const char *error_message);
 162  *
 163  * DESCRIPTION
 164  *
 165  *    Send HTTP error back to the connection indicated by `conn'.  The
 166  *    `error' is one of the 4xx or 5xx errors defined by the HTTP protocol.
 167  *    The `error_message' is the optional error message sent to the
 168  *    connection.  Returns FALSE if the error could not be sent.
 169  *
 170  *    Typical errors are: 400 Bad Request
 171  *                        403 Forbidden
 172  *                        404 Not Found
 173  *
 174  * EXAMPLE
 175  *
 176  *    silc_http_server_send_error(httpd, conn, "400 Bad Request",
 177  *                                "<body><h1>400 Bad Request!!</h1></body>");
 178  *
 179  ***/
 180 SilcBool silc_http_server_send_error(SilcHttpServer httpd,
 181                                      SilcHttpConnection conn,
 182                                      const char *error,
 183                                      const char *error_message);
 184
 185 /****f* silchttp/SilcHTTPServer/silc_http_server_get_header
 186  *
 187  * SYNOPSIS
 188  *
 189  *    const char *silc_http_server_get_header(SilcHttpServer httpd,
 190  *                                            SilcHttpConnection conn,
 191  *                                            const char *field);
 192  *
 193  * DESCRIPTION
 194  *
 195  *    Finds a header field indicated by `field' from the current HTTP
 196  *    request sent by the HTTP client.  Returns the field value or NULL
 197  *    if such header field does not exist.
 198  *
 199  ***/
 200 const char *silc_http_server_get_header(SilcHttpServer httpd,
 201                                         SilcHttpConnection conn,
 202                                         const char *field);
 203
 204 /****f* silchttp/SilcHTTPServer/silc_http_server_add_header
 205  *
 206  * SYNOPSIS
 207  *
 208  *    SilcBool silc_http_server_add_header(SilcHttpServer httpd,
 209  *                                         SilcHttpConnection conn,
 210  *                                         const char *field,
 211  *                                         const char *value);
 212  *
 213  * DESCRIPTION
 214  *
 215  *    Adds a new header to the HTTP headers to be sent back to the
 216  *    HTTP client.  This may be called to add needed headers to the
 217  *    HTTP reply.
 218  *
 219  * EXAMPLE
 220  *
 221  *    silc_http_server_add_header(httpd, conn, "Content-Type", "image/jpeg");
 222  *    silc_http_server_send(httpd, conn, image_data);
 223  *
 224  ***/
 225 SilcBool silc_http_server_add_header(SilcHttpServer httpd,
 226                                      SilcHttpConnection conn,
 227                                      const char *field,
 228                                      const char *value);
 229
 230 #endif /* SILCHTTPSERVER_H */