Added socket stream and socket into SilcClientConnection context.

[silc.git] / lib / silchttp / silchttpserver.h

diff --git a/lib/silchttp/silchttpserver.h b/lib/silchttp/silchttpserver.h
index 4bc9a624a58f176dfa880d9e1445fe9a6d1b2503..36faf5a5dc70b0229e8ec98292b03bc469bbeafb 100644 (file)
--- a/lib/silchttp/silchttpserver.h
+++ b/lib/silchttp/silchttpserver.h
@@ -4,7 +4,7 @@
 
   Author: Pekka Riikonen <priikone@silcnet.org>
 
-  Copyright (C) 2006 Pekka Riikonen
+  Copyright (C) 2006 - 2007 Pekka Riikonen
 
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
@@ -24,14 +24,42 @@
  * Very simple HTTP server interface.  This HTTP server supports basic HTTP
  * features.  All pages on the server are dynamically created by the caller
  * of this interface.  The server does not support plugins, modules, cgi-bin,
- * server-side includes or any other special features.
+ * server-side includes or any other special features.  Naturally, the caller
+ * of this interface may itself implement such features.
  *
  ***/
 
 #ifndef SILCHTTPSERVER_H
 #define SILCHTTPSERVER_H
 
+/****s* silchttp/SilcHTTPServer/SilcHttpServer
+ *
+ * NAME
+ *
+ *    typedef struct SilcHttpServerStruct *SilcHttpServer;
+ *
+ * DESCRIPTION
+ *
+ *    The actual HTTP server allocated with silc_http_server_alloc and
+ *    freed with silc_http_server_free.
+ *
+ ***/
 typedef struct SilcHttpServerStruct *SilcHttpServer;
+
+/****s* silchttp/SilcHTTPServer/SilcHttpConnection
+ *
+ * NAME
+ *
+ *    typedef struct SilcHttpConnectionStruct *SilcHttpConnection;
+ *
+ * DESCRIPTION
+ *
+ *    HTTP connection context.  This is allocated by the library and
+ *    delivered to application in SilcHttpServerCallback callbcak function.
+ *    It is given as argument to many silc_http_server_* functions.
+ *    It is freed automatically by the library.
+ *
+ ***/
 typedef struct SilcHttpConnectionStruct *SilcHttpConnection;
 
 /****f* silchttp/SilcHTTPServer/SilcHttpServerCallback
@@ -47,7 +75,7 @@ typedef struct SilcHttpConnectionStruct *SilcHttpConnection;
  *
  * DESCRIPTION
  *
- *    The HTTP request callback, that is called everytime a new HTTP request
+ *    The HTTP request callback that is called everytime a new HTTP request
  *    comes from a HTTP client.  The `uri' is the requested URI (web page),
  *    and the `method' is the HTTP request method (GET, POST, etc.).  The
  *    `data' is non-NULL only if the `method' is POST, and it includes the
@@ -75,22 +103,20 @@ typedef void (*SilcHttpServerCallback)(SilcHttpServer httpd,
  *
  *    SilcHttpServer
  *    silc_http_server_alloc(const char *ip, SilcUInt16 port,
- *                           SilcUInt32 max_connections,
  *                           SilcSchedule schedule,
  *                           SilcHttpServerCallback callback, void *context);
  *
  * DESCRIPTION
  *
  *    Allocates HTTP server and binds it to the IP address `ip' on the
- *    `port'.  If `max_connections' is non-zero, that many connections
- *    are allowed to the HTTP server.  The `callback' with `context' will
- *    be called everytime a new HTTP request comes to the server from
- *    a HTTP client.  In that callback the caller must then reply with
- *    the requested Web page or with an error.
+ *    `port'.  The `callback' with `context' will be called everytime a new
+ *    HTTP request comes to the server from a HTTP client.  In that callback
+ *    the caller must then reply with the requested Web page or with error.
+ *    If the `schedule' is NULL this will call silc_schedule_get_global to
+ *    try to get global scheduler.
  *
  ***/
 SilcHttpServer silc_http_server_alloc(const char *ip, SilcUInt16 port,
-                                     SilcUInt32 max_connections,
                                      SilcSchedule schedule,
                                      SilcHttpServerCallback callback,
                                      void *context);
@@ -108,7 +134,7 @@ SilcHttpServer silc_http_server_alloc(const char *ip, SilcUInt16 port,
  ***/
 void silc_http_server_free(SilcHttpServer httpd);
 
-/****f* silchttp/SilcHTTPServer/silc_http_server_free
+/****f* silchttp/SilcHTTPServer/silc_http_server_send
  *
  * SYNOPSIS
  *
@@ -127,7 +153,7 @@ SilcBool silc_http_server_send(SilcHttpServer httpd,
                               SilcHttpConnection conn,
                               SilcBuffer data);
 
-/****f* silchttp/SilcHTTPServer/silc_http_server_free
+/****f* silchttp/SilcHTTPServer/silc_http_server_send_error
  *
  * SYNOPSIS
  *
@@ -170,7 +196,7 @@ SilcBool silc_http_server_send_error(SilcHttpServer httpd,
  *
  *    Finds a header field indicated by `field' from the current HTTP
  *    request sent by the HTTP client.  Returns the field value or NULL
- *    if suchs header field does not exist.
+ *    if such header field does not exist.
  *
  ***/
 const char *silc_http_server_get_header(SilcHttpServer httpd,
@@ -195,6 +221,7 @@ const char *silc_http_server_get_header(SilcHttpServer httpd,
  * EXAMPLE
  *
  *    silc_http_server_add_header(httpd, conn, "Content-Type", "image/jpeg");
+ *    silc_http_server_send(httpd, conn, image_data);
  *
  ***/
 SilcBool silc_http_server_add_header(SilcHttpServer httpd,