]> matita.cs.unibo.it Git - helm.git/blob - DEVEL/ocaml-http/http_daemon.mli
added some missing includes
[helm.git] / DEVEL / ocaml-http / http_daemon.mli
1
2 (*
3   OCaml HTTP - do it yourself (fully OCaml) HTTP daemon
4
5   Copyright (C) <2002-2005> Stefano Zacchiroli <zack@cs.unibo.it>
6
7   This program is free software; you can redistribute it and/or modify
8   it under the terms of the GNU Library General Public License as
9   published by the Free Software Foundation, version 2.
10
11   This program is distributed in the hope that it will be useful,
12   but WITHOUT ANY WARRANTY; without even the implied warranty of
13   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14   GNU Library General Public License for more details.
15
16   You should have received a copy of the GNU Library General Public
17   License along with this program; if not, write to the Free Software
18   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
19   USA
20 *)
21
22 (** Main OCaml HTTP module.
23     Here you can find two set of functions:
24     - functions which let you start an HTTP Daemon (start* functions)
25     - facility functions which let you sent responses back to clients *)
26
27   (** send a CRLF sequence on the given output channel, this is mandatory after
28   the last header was sent and before start sending the response body *)
29 val send_CRLF: out_channel -> unit
30
31   (** send response status line, version is the http version used in response,
32   either code or status must be given (not both, not none) which represent the
33   HTTP response code, outchan is the output channel to which send status line *)
34 val send_status_line:
35   ?version:Http_types.version -> code:Http_types.status_code ->
36   out_channel ->
37     unit
38
39   (** like send_status_line but additionally will also send "Date" and "Server"
40   standard headers *)
41 val send_basic_headers:
42   ?version: Http_types.version -> code:Http_types.status_code ->
43   out_channel ->
44     unit
45
46   (** send an HTTP header on outchan *)
47 val send_header: header: string -> value: string -> out_channel -> unit
48
49   (** as send_header, but for a list of pairs <header, value> *)
50 val send_headers: headers:(string * string) list -> out_channel -> unit
51
52 (*
53   (** send a file through an out_channel, file can be passed as an in_channel
54   (if 'file' is given) or as a file name (if 'name' is given) *)
55 val send_file: ?name:string -> ?file:in_channel -> out_channel -> unit
56 *)
57   (** send a file through an out_channel *)
58 val send_file: src:Http_types.file_source -> out_channel -> unit
59
60   (** high level response function, respond on outchan sending: basic headers
61   (including Content-Length computed using 'body' argument), headers probided
62   via 'headers' argument, body given via 'body' argument.  Default response
63   status is 200, default response HTTP version is Http_common.http_version *)
64 val respond:
65   ?body:string -> ?headers:(string * string) list ->
66   ?version:Http_types.version -> ?code:Http_types.status_code ->
67   out_channel ->
68     unit
69
70   (** send a 404 (not found) HTTP response *)
71 val respond_not_found:
72   url:string -> ?version: Http_types.version -> out_channel -> unit
73
74   (** send a 403 (forbidden) HTTP response *)
75 val respond_forbidden:
76   url:string -> ?version: Http_types.version -> out_channel -> unit
77
78   (** send a "redirection" class response, optional body argument contains data
79   that will be displayed in the body of the response, default response status is
80   301 (moved permanently), only redirection status are accepted by this
81   function, other values will raise Failure *)
82 val respond_redirect:
83   location:string -> ?body:string ->
84   ?version: Http_types.version -> ?code:Http_types.status_code ->
85   out_channel ->
86     unit
87
88   (** respond with a 401 (Unauthorized) response asking for authentication
89   * against given realm (default is the server name) *)
90 val respond_unauthorized:
91   ?version: Http_types.version -> ?realm:string -> out_channel -> unit
92
93   (** send an "error" response (i.e. 400 <= status < 600), optional body
94   argument as per send_redirect, default response status is 400 (bad request),
95   only error status are accepted by this function, other values will
96   raise Failure *)
97 val respond_error:
98   ?body:string ->
99   ?version: Http_types.version -> ?code:Http_types.status_code ->
100   out_channel ->
101     unit
102
103   (** tipical static pages http daemon behaviour, if requested url is a file,
104   return it, it it is a directory return a directory listing of it *)
105 val respond_file:
106   fname:string -> ?version: Http_types.version -> out_channel -> unit
107
108   (** respond using a prebuilt Http_types.response object *)
109 val respond_with: Http_types.response -> out_channel -> unit
110
111   (** start an HTTP daemon
112   * @param spec specification of daemon behaviour
113   *)
114 val main: Http_types.daemon_spec -> unit
115
116   (** default daemon specification:
117   * - listen on 0.0.0.0, port 80
118   * - "always ok" callback  (return an empty response, response code 200)
119   * - fork a child for each request
120   * - do not change to a root directory (i.e. keep cwd)
121   * - 300 seconds timeout
122   * - ignores exceptions
123   * - no authentication required
124   * - do not automatically close client connections after callback *)
125 val default_spec: Http_types.daemon_spec
126
127   (** currified daemon_spec constructor. Each parameter of this function
128     * corresponds to one field of Http_types.daemon_spec and defaults to the
129     * corresponding field of Http_daemon.default_spec *)
130 val daemon_spec:
131   ?address:string ->
132   ?auth:(string * Http_types.auth_info) option ->
133   ?auto_close:bool ->
134   ?callback:(Http_types.request -> out_channel -> unit) ->
135   ?mode:(Http_types.daemon_mode) ->
136   ?port:int ->
137   ?root_dir:string option ->
138   ?exn_handler:(exn -> out_channel -> unit) option ->
139   ?timeout:int option ->
140   unit ->
141     Http_types.daemon_spec
142
143 (*
144 (** XXX
145  * This function has been deprecated for a while. Now it has been removed! *)
146 val start:
147   ?addr: string -> ?port: int ->
148   ?timeout: int option -> ?mode: Http_types.daemon_mode -> ?root: string ->
149   (string -> (string * string) list -> out_channel -> unit) ->
150     unit
151 *)
152
153 (*
154 (** XXX
155  * This function has been deprecated for a while. Now it has been removed! *)
156 val start':
157   ?addr: string -> ?port: int ->
158   ?timeout: int option -> ?mode: Http_types.daemon_mode -> ?root: string -> 
159   (Http_types.request -> out_channel -> unit) ->
160     unit
161 *)
162
163   (** Object oriented interface to HTTP daemons.
164   * @param addr address on which daemon will listen for connections
165   * @param port port which daemon will bind
166   * see {!Http_types.daemon} *)
167 class daemon:
168   ?addr: string -> ?port: int ->
169     unit ->
170       Http_types.daemon
171
172   (** Trivial static pages HTTP daemon.
173   * Daemons created using this module will serve directory indexes and files
174   * found starting from the working directory *)
175 module Trivial :
176   sig
177       (** callback function, exposed if you like to use it as a basis to define
178       a more powerful daemon *)
179     val callback : Http_types.request -> out_channel -> unit
180
181       (** start the "trivial" HTTP daemon
182       * @param spec trivial HTTP daemon specification, "callback" field is
183       * ignored and set to the callback above *)
184     val main : Http_types.daemon_spec -> unit
185   end
186