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  *                           SilcSchedule schedule,
  79  *                           SilcHttpServerCallback callback, void *context);
  80  *
  81  * DESCRIPTION
  82  *
  83  *    Allocates HTTP server and binds it to the IP address `ip' on the
  84  *    `port'.  The `callback' with `context' will be called everytime a new
  85  *    HTTP request comes to the server from a HTTP client.  In that callback
  86  *    the caller must then reply with the requested Web page or with error.
  87  *
  88  ***/
  89 SilcHttpServer silc_http_server_alloc(const char *ip, SilcUInt16 port,
  90                                       SilcSchedule schedule,
  91                                       SilcHttpServerCallback callback,
  92                                       void *context);
  93
  94 /****f* silchttp/SilcHTTPServer/silc_http_server_free
  95  *
  96  * SYNOPSIS
  97  *
  98  *    void silc_http_server_free(SilcHttpServer httpd);
  99  *
 100  * DESCRIPTION
 101  *
 102  *    Close HTTP server and free all resources.
 103  *
 104  ***/
 105 void silc_http_server_free(SilcHttpServer httpd);
 106
 107 /****f* silchttp/SilcHTTPServer/silc_http_server_free
 108  *
 109  * SYNOPSIS
 110  *
 111  *    SilcBool silc_http_server_send(SilcHttpServer httpd,
 112  *                                   SilcHttpConnection conn,
 113  *                                   SilcBuffer data);
 114  *
 115  * DESCRIPTION
 116  *
 117  *    Send the HTTP data indicated by `data' buffer into the connection
 118  *    indicated by `conn'.  Returns TRUE after the data is sent, and FALSE
 119  *    if error occurred.  Usually the `data' would be the requested web page.
 120  *
 121  ***/
 122 SilcBool silc_http_server_send(SilcHttpServer httpd,
 123                                SilcHttpConnection conn,
 124                                SilcBuffer data);
 125
 126 /****f* silchttp/SilcHTTPServer/silc_http_server_free
 127  *
 128  * SYNOPSIS
 129  *
 130  *    SilcBool silc_http_server_send_error(SilcHttpServer httpd,
 131  *                                         SilcHttpConnection conn,
 132  *                                         const char *error,
 133  *                                         const char *error_message);
 134  *
 135  * DESCRIPTION
 136  *
 137  *    Send HTTP error back to the connection indicated by `conn'.  The
 138  *    `error' is one of the 4xx or 5xx errors defined by the HTTP protocol.
 139  *    The `error_message' is the optional error message sent to the
 140  *    connection.  Returns FALSE if the error could not be sent.
 141  *
 142  *    Typical errors are: 400 Bad Request
 143  *                        403 Forbidden
 144  *                        404 Not Found
 145  *
 146  * EXAMPLE
 147  *
 148  *    silc_http_server_send_error(httpd, conn, "400 Bad Request",
 149  *                                "<body><h1>400 Bad Request!!</h1></body>");
 150  *
 151  ***/
 152 SilcBool silc_http_server_send_error(SilcHttpServer httpd,
 153                                      SilcHttpConnection conn,
 154                                      const char *error,
 155                                      const char *error_message);
 156
 157 /****f* silchttp/SilcHTTPServer/silc_http_server_get_header
 158  *
 159  * SYNOPSIS
 160  *
 161  *    const char *silc_http_server_get_header(SilcHttpServer httpd,
 162  *                                            SilcHttpConnection conn,
 163  *                                            const char *field);
 164  *
 165  * DESCRIPTION
 166  *
 167  *    Finds a header field indicated by `field' from the current HTTP
 168  *    request sent by the HTTP client.  Returns the field value or NULL
 169  *    if suchs header field does not exist.
 170  *
 171  ***/
 172 const char *silc_http_server_get_header(SilcHttpServer httpd,
 173                                         SilcHttpConnection conn,
 174                                         const char *field);
 175
 176 /****f* silchttp/SilcHTTPServer/silc_http_server_add_header
 177  *
 178  * SYNOPSIS
 179  *
 180  *    SilcBool silc_http_server_add_header(SilcHttpServer httpd,
 181  *                                         SilcHttpConnection conn,
 182  *                                         const char *field,
 183  *                                         const char *value);
 184  *
 185  * DESCRIPTION
 186  *
 187  *    Adds a new header to the HTTP headers to be sent back to the
 188  *    HTTP client.  This may be called to add needed headers to the
 189  *    HTTP reply.
 190  *
 191  * EXAMPLE
 192  *
 193  *    silc_http_server_add_header(httpd, conn, "Content-Type", "image/jpeg");
 194  *
 195  ***/
 196 SilcBool silc_http_server_add_header(SilcHttpServer httpd,
 197                                      SilcHttpConnection conn,
 198                                      const char *field,
 199                                      const char *value);
 200
 201 #endif /* SILCHTTPSERVER_H */