5 Author: Pekka Riikonen <priikone@silcnet.org>
7 Copyright (C) 2006 - 2007 Pekka Riikonen
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.
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.
20 /****h* silchttp/SILC HTTP Server Interface
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.
32 #ifndef SILCHTTPSERVER_H
33 #define SILCHTTPSERVER_H
35 /****s* silchttp/SilcHTTPServer/SilcHttpServer
39 * typedef struct SilcHttpServerStruct *SilcHttpServer;
43 * The actual HTTP server allocated with silc_http_server_alloc and
44 * freed with silc_http_server_free.
47 typedef struct SilcHttpServerStruct *SilcHttpServer;
49 /****s* silchttp/SilcHTTPServer/SilcHttpConnection
53 * typedef struct SilcHttpConnectionStruct *SilcHttpConnection;
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.
63 typedef struct SilcHttpConnectionStruct *SilcHttpConnection;
65 /****f* silchttp/SilcHTTPServer/SilcHttpServerCallback
69 * typedef void (*SilcHttpServerCallback)(SilcHttpServer httpd,
70 * SilcHttpConnection conn,
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
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.
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.
93 typedef void (*SilcHttpServerCallback)(SilcHttpServer httpd,
94 SilcHttpConnection conn,
100 /****f* silchttp/SilcHTTPServer/silc_http_server_alloc
105 * silc_http_server_alloc(const char *ip, SilcUInt16 port,
106 * SilcSchedule schedule,
107 * SilcHttpServerCallback callback, void *context);
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.
119 SilcHttpServer silc_http_server_alloc(const char *ip, SilcUInt16 port,
120 SilcSchedule schedule,
121 SilcHttpServerCallback callback,
124 /****f* silchttp/SilcHTTPServer/silc_http_server_free
128 * void silc_http_server_free(SilcHttpServer httpd);
132 * Close HTTP server and free all resources.
135 void silc_http_server_free(SilcHttpServer httpd);
137 /****f* silchttp/SilcHTTPServer/silc_http_server_send
141 * SilcBool silc_http_server_send(SilcHttpServer httpd,
142 * SilcHttpConnection conn,
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.
152 SilcBool silc_http_server_send(SilcHttpServer httpd,
153 SilcHttpConnection conn,
156 /****f* silchttp/SilcHTTPServer/silc_http_server_send_error
160 * SilcBool silc_http_server_send_error(SilcHttpServer httpd,
161 * SilcHttpConnection conn,
163 * const char *error_message);
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.
172 * Typical errors are: 400 Bad Request
178 * silc_http_server_send_error(httpd, conn, "400 Bad Request",
179 * "<body><h1>400 Bad Request!!</h1></body>");
182 SilcBool silc_http_server_send_error(SilcHttpServer httpd,
183 SilcHttpConnection conn,
185 const char *error_message);
187 /****f* silchttp/SilcHTTPServer/silc_http_server_get_header
191 * const char *silc_http_server_get_header(SilcHttpServer httpd,
192 * SilcHttpConnection conn,
193 * const char *field);
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.
202 const char *silc_http_server_get_header(SilcHttpServer httpd,
203 SilcHttpConnection conn,
206 /****f* silchttp/SilcHTTPServer/silc_http_server_add_header
210 * SilcBool silc_http_server_add_header(SilcHttpServer httpd,
211 * SilcHttpConnection conn,
213 * const char *value);
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
223 * silc_http_server_add_header(httpd, conn, "Content-Type", "image/jpeg");
224 * silc_http_server_send(httpd, conn, image_data);
227 SilcBool silc_http_server_add_header(SilcHttpServer httpd,
228 SilcHttpConnection conn,
232 #endif /* SILCHTTPSERVER_H */