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