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.
  28  *
  29  ***/
  30
  31 #ifndef SILCHTTPSERVER_H
  32 #define SILCHTTPSERVER_H
  33
  34 typedef struct SilcHttpServerStruct *SilcHttpServer;
  35 typedef struct SilcHttpConnectionStruct *SilcHttpConnection;
  36
  37 /****f* silchttp/SilcHTTPServer/SilcHttpServerCallback
  38  *
  39  * SYNOPSIS
  40  *
  41  *    typedef void (*SilcHttpServerCallback)(SilcHttpServer httpd,
  42  *                                           SilcHttpConnection conn,
  43  *                                           const char *uri,
  44  *                                           const char *method,
  45  *                                           SilcBuffer data,
  46  *                                           void *context);
  47  *
  48  * DESCRIPTION
  49  *
  50  *    The HTTP request callback, that is called everytime a new HTTP request
  51  *    comes from a HTTP client.  The `uri' is the requested URI (web page),
  52  *    and the `method' is the HTTP request method (GET, POST, etc.).  The
  53  *    `data' is non-NULL only if the `method' is POST, and it includes the
  54  *    the POST data.
  55  *
  56  *    The requested web page must be returned to the HTTP client from this
  57  *    callback by calling silc_http_server_send or error is returned by
  58  *    calling silc_http_server_send_error.
  59  *
  60  *    The silc_http_server_get_header may be called to find a specific
  61  *    HTTP header from this request.  New headers may be added to the
  62  *    reply by calling silc_http_server_add_header.
  63  *
  64  ***/
  65 typedef void (*SilcHttpServerCallback)(SilcHttpServer httpd,
  66                                        SilcHttpConnection conn,
  67                                        const char *uri,
  68                                        const char *method,
  69                                        SilcBuffer data,
  70                                        void *context);
  71
  72 /****f* silchttp/SilcHTTPServer/silc_http_server_alloc
  73  *
  74  * SYNOPSIS
  75  *
  76  *    SilcHttpServer
  77  *    silc_http_server_alloc(const char *ip, SilcUInt16 port,
  78  *                           SilcUInt32 max_connections,
  79  *                           SilcSchedule schedule,
  80  *                           SilcHttpServerCallback callback, void *context);
  81  *
  82  * DESCRIPTION
  83  *
  84  *    Allocates HTTP server and binds it to the IP address `ip' on the
  85  *    `port'.  If `max_connections' is non-zero, that many connections
  86  *    are allowed to the HTTP server.  The `callback' with `context' will
  87  *    be called everytime a new HTTP request comes to the server from
  88  *    a HTTP client.  In that callback the caller must then reply with
  89  *    the requested Web page or with an error.
  90  *
  91  ***/
  92 SilcHttpServer silc_http_server_alloc(const char *ip, SilcUInt16 port,
  93                                       SilcUInt32 max_connections,
  94                                       SilcSchedule schedule,
  95                                       SilcHttpServerCallback callback,
  96                                       void *context);
  97
  98 /****f* silchttp/SilcHTTPServer/silc_http_server_free
  99  *
 100  * SYNOPSIS
 101  *
 102  *    void silc_http_server_free(SilcHttpServer httpd);
 103  *
 104  * DESCRIPTION
 105  *
 106  *    Close HTTP server and free all resources.
 107  *
 108  ***/
 109 void silc_http_server_free(SilcHttpServer httpd);
 110
 111 /****f* silchttp/SilcHTTPServer/silc_http_server_free
 112  *
 113  * SYNOPSIS
 114  *
 115  *    SilcBool silc_http_server_send(SilcHttpServer httpd,
 116  *                                   SilcHttpConnection conn,
 117  *                                   SilcBuffer data);
 118  *
 119  * DESCRIPTION
 120  *
 121  *    Send the HTTP data indicated by `data' buffer into the connection
 122  *    indicated by `conn'.  Returns TRUE after the data is sent, and FALSE
 123  *    if error occurred.  Usually the `data' would be the requested web page.
 124  *
 125  ***/
 126 SilcBool silc_http_server_send(SilcHttpServer httpd,
 127                                SilcHttpConnection conn,
 128                                SilcBuffer data);
 129
 130 /****f* silchttp/SilcHTTPServer/silc_http_server_free
 131  *
 132  * SYNOPSIS
 133  *
 134  *    SilcBool silc_http_server_send_error(SilcHttpServer httpd,
 135  *                                         SilcHttpConnection conn,
 136  *                                         const char *error,
 137  *                                         const char *error_message);
 138  *
 139  * DESCRIPTION
 140  *
 141  *    Send HTTP error back to the connection indicated by `conn'.  The
 142  *    `error' is one of the 4xx or 5xx errors defined by the HTTP protocol.
 143  *    The `error_message' is the optional error message sent to the
 144  *    connection.  Returns FALSE if the error could not be sent.
 145  *
 146  *    Typical errors are: 400 Bad Request
 147  *                        403 Forbidden
 148  *                        404 Not Found
 149  *
 150  * EXAMPLE
 151  *
 152  *    silc_http_server_send_error(httpd, conn, "400 Bad Request",
 153  *                                "<body><h1>400 Bad Request!!</h1></body>");
 154  *
 155  ***/
 156 SilcBool silc_http_server_send_error(SilcHttpServer httpd,
 157                                      SilcHttpConnection conn,
 158                                      const char *error,
 159                                      const char *error_message);
 160
 161 /****f* silchttp/SilcHTTPServer/silc_http_server_get_header
 162  *
 163  * SYNOPSIS
 164  *
 165  *    const char *silc_http_server_get_header(SilcHttpServer httpd,
 166  *                                            SilcHttpConnection conn,
 167  *                                            const char *field);
 168  *
 169  * DESCRIPTION
 170  *
 171  *    Finds a header field indicated by `field' from the current HTTP
 172  *    request sent by the HTTP client.  Returns the field value or NULL
 173  *    if suchs header field does not exist.
 174  *
 175  ***/
 176 const char *silc_http_server_get_header(SilcHttpServer httpd,
 177                                         SilcHttpConnection conn,
 178                                         const char *field);
 179
 180 /****f* silchttp/SilcHTTPServer/silc_http_server_add_header
 181  *
 182  * SYNOPSIS
 183  *
 184  *    SilcBool silc_http_server_add_header(SilcHttpServer httpd,
 185  *                                         SilcHttpConnection conn,
 186  *                                         const char *field,
 187  *                                         const char *value);
 188  *
 189  * DESCRIPTION
 190  *
 191  *    Adds a new header to the HTTP headers to be sent back to the
 192  *    HTTP client.  This may be called to add needed headers to the
 193  *    HTTP reply.
 194  *
 195  * EXAMPLE
 196  *
 197  *    silc_http_server_add_header(httpd, conn, "Content-Type", "image/jpeg");
 198  *
 199  ***/
 200 SilcBool silc_http_server_add_header(SilcHttpServer httpd,
 201                                      SilcHttpConnection conn,
 202                                      const char *field,
 203                                      const char *value);
 204
 205 #endif /* SILCHTTPSERVER_H */