helm/DEVEL/ocaml-http/http_daemon.mli

   1
   2 (*
   3   OCaml HTTP - do it yourself (fully OCaml) HTTP daemon
   4
   5   Copyright (C) <2002-2004> 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 General Public License as published by
   9   the Free Software Foundation; either version 2 of the License, or
  10   (at your option) any later version.
  11
  12   This program is distributed in the hope that it will be useful,
  13   but WITHOUT ANY WARRANTY; without even the implied warranty of
  14   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15   GNU General Public License for more details.
  16
  17   You should have received a copy of the GNU General Public License
  18   along with this program; if not, write to the Free Software
  19   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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 val default_spec: Http_types.daemon_spec
 125
 126   (** currified daemon_spec constructor. Each parameter of this function
 127     * corresponds to one field of Http_types.daemon_spec and defaults to the
 128     * corresponding field of Http_daemon.default_spec *)
 129 val daemon_spec:
 130   ?address:string ->
 131   ?auth:(string * Http_types.auth_info) option ->
 132   ?callback:(Http_types.request -> out_channel -> unit) ->
 133   ?mode:(Http_types.daemon_mode) ->
 134   ?port:int ->
 135   ?root_dir:string option ->
 136   ?exn_handler:(exn -> out_channel -> unit) option ->
 137   ?timeout:int option ->
 138   unit ->
 139     Http_types.daemon_spec
 140
 141   (** starts an HTTP daemon (deprecated function)
 142   *
 143   * DEPRECATED, will be removed in future versions, please switch to
 144   * Http_daemon.main below.
 145   *
 146   * see Http_types.daemon_spec for a detailed description of parameters
 147   * @param addr like the "address" field of Http_types.daemon_spec, defaults to
 148   *   the wildcard address "0.0.0.0"
 149   * @param like the "port" field of Http_types.daemon_spec, defaults to 80
 150   * @param like the "timeout" field of Http_types.daemon_spec, defaults to Some
 151   *   300
 152   * @param like the "mode" field of Http_types.daemon_spec, defaults to `Fork
 153   * @param like the "root_dir" field of Http_types.daemon_spec, defaults to None
 154   * @param callback functional version of the "callback" field of
 155   *   Http_types.daemon_spec.  1st argument is the request path, 2nd argument
 156   *   the decoded query string, 3rd argument an output channel connect to the
 157   *   client
 158   *)
 159 val start:
 160   ?addr: string -> ?port: int ->
 161   ?timeout: int option -> ?mode: Http_types.daemon_mode -> ?root: string ->
 162   (string -> (string * string) list -> out_channel -> unit) ->
 163     unit
 164
 165   (** starts an HTTP daemon (deprecated function)
 166   *
 167   * DEPRECATED, will be removed in future versions, please switch to
 168   * Http_daemon.main below.
 169   *
 170   * parameters as above except for the callback, in this case it behaves as the
 171   * "callback" field of Http_types.daemon_spec
 172   *)
 173 val start':
 174   ?addr: string -> ?port: int ->
 175   ?timeout: int option -> ?mode: Http_types.daemon_mode -> ?root: string ->
 176   (Http_types.request -> out_channel -> unit) ->
 177     unit
 178
 179   (** Object oriented interface to HTTP daemons.
 180   @param addr address on which daemon will listen for connections
 181   @param port port which daemon will bind
 182   see {! Http_types.daemon} *)
 183 class daemon:
 184   ?addr: string -> ?port: int ->
 185     unit ->
 186       Http_types.daemon
 187
 188   (** Trivial static pages HTTP daemon.
 189   Daemons created using this module will serve directory indexes and files found
 190   starting from the working directory *)
 191 module Trivial :
 192   sig
 193       (** callback function, exposed if you like to use it as a basis to define
 194       a more powerful daemon *)
 195     val callback : Http_types.request -> out_channel -> unit
 196
 197       (** start the "trivial" HTTP daemon
 198       * @param spec trivial HTTP daemon specification, "callback" field is
 199       * ignored and set to the callback above *)
 200     val main : Http_types.daemon_spec -> unit
 201   end
 202