helm/DEVEL/ocaml-http/http_daemon.mli

   1
   2 (*
   3   OCaml HTTP - do it yourself (fully OCaml) HTTP daemon
   4
   5   Copyright (C) <2002> 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: int -> ?status: Http_types.status ->
  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: int -> ?status: Http_types.status ->
  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:int -> ?status:Http_types.status ->
  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   302 (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 ->
  85   ?code: int -> ?status: Http_types.redirection_status ->
  86   out_channel ->
  87     unit
  88
  89   (** respond with a 401 (Unauthorized) response asking for authentication
  90   * against given realm (default is the server name) *)
  91 val respond_unauthorized:
  92   ?version: Http_types.version -> ?realm:string -> out_channel -> unit
  93
  94   (** send an "error" response (i.e. 400 <= status < 600), optional body
  95   argument as per send_redirect, default response status is 400 (bad request),
  96   only error status are accepted by this function, other values will
  97   raise Failure *)
  98 val respond_error:
  99   ?body:string ->
 100   ?version: Http_types.version ->
 101   ?code: int -> ?status: Http_types.error_status ->
 102   out_channel ->
 103     unit
 104
 105   (** tipical static pages http daemon behaviour, if requested url is a file,
 106   return it, it it is a directory return a directory listing of it *)
 107 val respond_file:
 108   fname:string -> ?version: Http_types.version -> out_channel -> unit
 109
 110   (** respond using a prebuilt Http_types.response object *)
 111 val respond_with: Http_types.response -> out_channel -> unit
 112
 113   (** create an HTTP daemon listening on 'addr':'port' (defaults are
 114   addr:"0.0.0.0" and port:80), callback is the user supplied function which
 115   receive as a first parameter the path required by the the HTTP client as a
 116   string, and a list of pair <parameter, value> representing parameters passed
 117   via GET. The last argument of the callback is an output_channel connected to
 118   the HTTP client to which the user can write directly. 'timeout' parameter sets
 119   a timeout for each request processed by the daemon, if it's set to None,
 120   daemon waits forever for completed requests (use with care!), default is 5
 121   minute. 'mode' parameter has 3 possible values: `Single means that all request
 122   are handled by the same process, `Fork means that each request is handled by a
 123   separate process, `Thread means that each request is handled by a separate
 124   thread, default is `Fork; 'root' (mnemonic "document root") is the directory
 125   where the daemon chdir before starting up, default is current working
 126   directory *)
 127 val start:
 128   ?addr: string -> ?port: int ->
 129   ?timeout: int option -> ?mode: Http_types.daemon_mode -> ?root: string ->
 130   (string -> (string * string) list -> out_channel -> unit) ->
 131     unit
 132
 133   (** identical to 'start' above but callback receive two arguments, the second
 134   one is an out_channel as per 'start', but the secondo one is a Request.request
 135   object *)
 136 val start':
 137   ?addr: string -> ?port: int ->
 138   ?timeout: int option -> ?mode: Http_types.daemon_mode -> ?root: string ->
 139   (Http_types.request -> out_channel -> unit) ->
 140     unit
 141
 142   (** Object oriented interface to HTTP daemons.
 143   @param addr address on which daemon will listen for connections
 144   @param port port which daemon will bind
 145   see {! Http_types.daemon} *)
 146 class daemon:
 147   ?addr: string -> ?port: int ->
 148     unit ->
 149       Http_types.daemon
 150
 151   (** Trivial static pages HTTP daemon.
 152   Daemons created using this module will serve directory indexes and files found
 153   starting from the working directory *)
 154 module Trivial :
 155   sig
 156       (** callback function, exposed if you like to use it as a basis to define
 157       a more powerful daemon *)
 158     val callback : string -> 'a -> out_channel -> unit
 159
 160       (** start the "trivial" HTTP daemon *)
 161     val start : ?addr:string -> ?port:int -> unit -> unit
 162   end
 163