- added main that starts a new http_daemon given a daemon_spec (see

[helm.git] / helm / DEVEL / ocaml-http / http_daemon.mli

diff --git a/helm/DEVEL/ocaml-http/http_daemon.mli b/helm/DEVEL/ocaml-http/http_daemon.mli
index ba20a0b424fbfa8c005ac05f7910bdf2ba5a8406..54b8c19d0d4a998c2275570c8d65635671bc2436 100644 (file)
--- a/helm/DEVEL/ocaml-http/http_daemon.mli
+++ b/helm/DEVEL/ocaml-http/http_daemon.mli
@@ -108,27 +108,53 @@ val respond_file:
   (** respond using a prebuilt Http_types.response object *)
 val respond_with: Http_types.response -> out_channel -> unit
 
-  (** starts an HTTP daemon listening
-  * @param addr adress on which daemon will be listening, can be both a numeric
-  *   address (e.g. "127.0.0.1") and an hostname (e.g. "localhost"). Default is
+  (** start an HTTP daemon
+  * @param spec specification of daemon behaviour
+  *)
+val main: Http_types.daemon_spec -> unit
+
+  (** default daemon specification:
+  * - listen on 0.0.0.0, port 80
+  * - "always ok" callback  (return an empty response, response code 200)
+  * - fork a child for each request
+  * - do not change to a root directory (i.e. keep cwd)
+  * - 300 seconds timeout
+  * - ignores exceptions
+  * - no authentication required *)
+val default_spec: Http_types.daemon_spec
+
+  (** currified daemon_spec constructor. Each parameter of this function
+    * corresponds to one field of Http_types.daemon_spec and defaults to the
+    * corresponding field of Http_daemon.default_spec *)
+val daemon_spec:
+  ?address:string ->
+  ?auth:(string * Http_types.auth_info) option ->
+  ?callback:(Http_types.request -> out_channel -> unit) ->
+  ?mode:(Http_types.daemon_mode) ->
+  ?port:int ->
+  ?root_dir:string option ->
+  ?exn_handler:(exn -> out_channel -> unit) option ->
+  ?timeout:int option ->
+  unit ->
+    Http_types.daemon_spec
+
+  (** starts an HTTP daemon (deprecated function)
+  *
+  * DEPRECATED, will be removed in future versions, please switch to
+  * Http_daemon.main below.
+  *
+  * see Http_types.daemon_spec for a detailed description of parameters
+  * @param addr like the "address" field of Http_types.daemon_spec, defaults to
   *   the wildcard address "0.0.0.0"
-  * @param port TCP port on which the daemon will be listening. Default is the
-  *   HTTP port 80
-  * @param timeout timeout in seconds after which an incoming HTTP request will
-  *   be terminated closing the corresponding TCP connection. Passing None will
-  *   disable the timeout. Default is 5 minutes (300 seconds)
-  * @param mode requests handling mode, it can have three different values.
-  *   `Single -> all requests will be handled by the same process,
-  *   `Fork   -> each request will be handled by a separate process
-  *   `Thread -> each request will be handled by a separate thread
-  *   Default is `Fork
-  * @param root document root (i.e. directory to which ocaml http will chdir
-  *   before starting handling requests). Default is current working directory
-  * @param callback function which will be called each time a correct HTTP
-  *   request will be received. 1st callback argument is the path requested by
-  *   the HTTP client; 2nd argument is a list of pairs <parameter, value>
-  *   representing decoded query string; 3rd argument is an output channel
-  *   connected with the client
+  * @param like the "port" field of Http_types.daemon_spec, defaults to 80
+  * @param like the "timeout" field of Http_types.daemon_spec, defaults to Some
+  *   300
+  * @param like the "mode" field of Http_types.daemon_spec, defaults to `Fork
+  * @param like the "root_dir" field of Http_types.daemon_spec, defaults to None
+  * @param callback functional version of the "callback" field of
+  *   Http_types.daemon_spec.  1st argument is the request path, 2nd argument
+  *   the decoded query string, 3rd argument an output channel connect to the
+  *   client
   *)
 val start:
   ?addr: string -> ?port: int ->
@@ -136,9 +162,14 @@ val start:
   (string -> (string * string) list -> out_channel -> unit) ->
     unit
 
-  (** identical to 'start' above but callback receive two arguments, the second
-  one is an out_channel as per 'start', but the secondo one is a Request.request
-  object *)
+  (** starts an HTTP daemon (deprecated function)
+  *
+  * DEPRECATED, will be removed in future versions, please switch to
+  * Http_daemon.main below.
+  *
+  * parameters as above except for the callback, in this case it behaves as the
+  * "callback" field of Http_types.daemon_spec
+  *)
 val start':
   ?addr: string -> ?port: int ->
   ?timeout: int option -> ?mode: Http_types.daemon_mode -> ?root: string -> 
@@ -161,9 +192,11 @@ module Trivial :
   sig
       (** callback function, exposed if you like to use it as a basis to define
       a more powerful daemon *)
-    val callback : string -> 'a -> out_channel -> unit
+    val callback : Http_types.request -> out_channel -> unit
 
-      (** start the "trivial" HTTP daemon *)
-    val start : ?addr:string -> ?port:int -> unit -> unit
+      (** start the "trivial" HTTP daemon
+      * @param spec trivial HTTP daemon specification, "callback" field is
+      * ignored and set to the callback above *)
+    val main : Http_types.daemon_spec -> unit
   end