lib/silchttp/silchttpserver.h

   1 /*
   2
   3   silchttpserver.h
   4
   5   Author: Pekka Riikonen <priikone@silcnet.org>
   6
   7   Copyright (C) 2006 - 2007 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  *    If the `schedule' is NULL this will call silc_schedule_get_global to
 116  *    try to get global scheduler.
 117  *
 118  ***/
 119 SilcHttpServer silc_http_server_alloc(const char *ip, SilcUInt16 port,
 120                                       SilcSchedule schedule,
 121                                       SilcHttpServerCallback callback,
 122                                       void *context);
 123
 124 /****f* silchttp/SilcHTTPServer/silc_http_server_free
 125  *
 126  * SYNOPSIS
 127  *
 128  *    void silc_http_server_free(SilcHttpServer httpd);
 129  *
 130  * DESCRIPTION
 131  *
 132  *    Close HTTP server and free all resources.
 133  *
 134  ***/
 135 void silc_http_server_free(SilcHttpServer httpd);
 136
 137 /****f* silchttp/SilcHTTPServer/silc_http_server_send
 138  *
 139  * SYNOPSIS
 140  *
 141  *    SilcBool silc_http_server_send(SilcHttpServer httpd,
 142  *                                   SilcHttpConnection conn,
 143  *                                   SilcBuffer data);
 144  *
 145  * DESCRIPTION
 146  *
 147  *    Send the HTTP data indicated by `data' buffer into the connection
 148  *    indicated by `conn'.  Returns TRUE after the data is sent, and FALSE
 149  *    if error occurred.  Usually the `data' would be the requested web page.
 150  *
 151  ***/
 152 SilcBool silc_http_server_send(SilcHttpServer httpd,
 153                                SilcHttpConnection conn,
 154                                SilcBuffer data);
 155
 156 /****f* silchttp/SilcHTTPServer/silc_http_server_send_error
 157  *
 158  * SYNOPSIS
 159  *
 160  *    SilcBool silc_http_server_send_error(SilcHttpServer httpd,
 161  *                                         SilcHttpConnection conn,
 162  *                                         const char *error,
 163  *                                         const char *error_message);
 164  *
 165  * DESCRIPTION
 166  *
 167  *    Send HTTP error back to the connection indicated by `conn'.  The
 168  *    `error' is one of the 4xx or 5xx errors defined by the HTTP protocol.
 169  *    The `error_message' is the optional error message sent to the
 170  *    connection.  Returns FALSE if the error could not be sent.
 171  *
 172  *    Typical errors are: 400 Bad Request
 173  *                        403 Forbidden
 174  *                        404 Not Found
 175  *
 176  * EXAMPLE
 177  *
 178  *    silc_http_server_send_error(httpd, conn, "400 Bad Request",
 179  *                                "<body><h1>400 Bad Request!!</h1></body>");
 180  *
 181  ***/
 182 SilcBool silc_http_server_send_error(SilcHttpServer httpd,
 183                                      SilcHttpConnection conn,
 184                                      const char *error,
 185                                      const char *error_message);
 186
 187 /****f* silchttp/SilcHTTPServer/silc_http_server_get_header
 188  *
 189  * SYNOPSIS
 190  *
 191  *    const char *silc_http_server_get_header(SilcHttpServer httpd,
 192  *                                            SilcHttpConnection conn,
 193  *                                            const char *field);
 194  *
 195  * DESCRIPTION
 196  *
 197  *    Finds a header field indicated by `field' from the current HTTP
 198  *    request sent by the HTTP client.  Returns the field value or NULL
 199  *    if such header field does not exist.
 200  *
 201  ***/
 202 const char *silc_http_server_get_header(SilcHttpServer httpd,
 203                                         SilcHttpConnection conn,
 204                                         const char *field);
 205
 206 /****f* silchttp/SilcHTTPServer/silc_http_server_add_header
 207  *
 208  * SYNOPSIS
 209  *
 210  *    SilcBool silc_http_server_add_header(SilcHttpServer httpd,
 211  *                                         SilcHttpConnection conn,
 212  *                                         const char *field,
 213  *                                         const char *value);
 214  *
 215  * DESCRIPTION
 216  *
 217  *    Adds a new header to the HTTP headers to be sent back to the
 218  *    HTTP client.  This may be called to add needed headers to the
 219  *    HTTP reply.
 220  *
 221  * EXAMPLE
 222  *
 223  *    silc_http_server_add_header(httpd, conn, "Content-Type", "image/jpeg");
 224  *    silc_http_server_send(httpd, conn, image_data);
 225  *
 226  ***/
 227 SilcBool silc_http_server_add_header(SilcHttpServer httpd,
 228                                      SilcHttpConnection conn,
 229                                      const char *field,
 230                                      const char *value);
 231
 232 #endif /* SILCHTTPSERVER_H */