(*
 * <COPYRIGHT>
 * Copyright 2002 Joachim Schrod Network and Publication Consultance GmbH, Gerd Stolpmann
 *
 * <GPL>
 * This file is part of WDialog.
 *
 * WDialog is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * WDialog is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with WDialog; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * </>
 *)

(* $Id: wd_run_cgi.mli,v 3.6 2003/03/21 14:23:44 stolpmann Exp $
 * ----------------------------------------------------------------------
 *
 *)

(** This module contains a customizable main program for CGIs *)

open Wd_types
open Netchannels

val adjust_gc : unit -> unit
  (** Adjust the garbage collector for short-living processes.
   * This is recommended if used in a CGI environment.
   *)

val run :
      ?charset:Pxp_types.rep_encoding ->      (* default: `Enc_iso88591 *)
      ?script:string ->                       (* default: use SCRIPT_NAME environment variable *)
      ?self_url:string ->                     (* default: derive from ~script *)
      ?uifile:string ->                       (* default: derive from ~script *)
      ?session_manager:session_manager_type -> (* defalt: instant_session_manager *)
      ?no_cache:bool ->                       (* default: true *)
      ?error_page:(out_obj_channel -> exn -> unit) ->  (* default: a simple error page *)
      ?cgi:Netcgi_types.cgi_activation ->     (* default: a [std_activation] object *)
      ?response_header:response_header ->     (* default: see below *)
      ?reg:(universe_type -> unit) ->
      unit ->
	unit
  (** A customizable "main program" which processes CGI requests and generates
   * responses. It includes support for error handling.
   *
   * The simplest way to make a working CGI program is to
   * call [run ~reg ()]; the argument [~reg] registers the dialog classes.
   * The other arguments have reasonable defaults for a normal CGI
   * environment.
   *
   * The function passed to [~reg] gets the universe as argument. Its task
   * is to register the dialog classes by calling the method [register]
   * of the universe.
   *
   * [run] loads the UI file, initializes the CGI environment, processes
   * the request (see {!Wd_cycle}), and generates the response.
   * If an error happens, an error page is generated describing the
   * exception. The optional arguments modify the standard behaviour:
   *
   * @param charset determines the character set for the internal representation
   *   of strings and for the generated HTML pages. (Note that the parsed
   *   XML files can have character sets independent of this setting.)
   *   The default is [ISO-8859-1].
   *
   * @param script determines the file name of the invoked CGI script. 
   *   This parameter sets default for the other parameters [self_url]
   *   and [uifile] as follows: The
   *   file name of the ui file is derived from [~script] by changing the
   *   extension to ".ui" (or ".ui.bin" for compiled UI definitions).
   *   The default for [self_url] is derived from the basename of [script].
   *   -- If [script] is not passed, it is derived from the (CGI) environment
   *   variable [SCRIPT_NAME], and interpreted relative to the current
   *   working directory. 
   *   There is normally no reason to pass ~script.
   *   EXAMPLE: If your script is called "index.cgi", the UI definition
   *   file "index.ui" or "index.ui.bin" is used.
   *
   * @param self_url the URL which refers to the current script. By default,
   *   it is derived from [~script]. This value is put into the generated
   *   FORM elements as ACTION attribute.
   *
   * @param uifile is the path where the UI file can be found. By default,
   *   this argument is derived from [~script].
   *
   * @param no_cache If [true]: The CGI response contains header directives
   *   preventing the browser (and all caches between server and browser)
   *   from storing the response. This ensures that never a cache copy
   *   is taken, and for many browsers, the history is no longer usable
   *   (when hitting the "Back" button, the user only gets a message
   *   that the data is expired, but not the old page).
   *   The default is [true].
   *
   * @param error_page This function is called when an exception is caught.
   *   It can generate an error page by writing a nicely formatted
   *   message to the output channel. The default is a function that
   *   outputs a simple error page.
   *
   * @param cgi This argument is the CGI activation object to be used. This
   *   object represents the "outer world" for WDialog. The default is
   *   to use the class [std_activation] (of Ocamlnet) implementing the CGI/1.1
   *   standard.
   *
   * @param response_header If set, this parameter is taken as the initial
   *   HTTP response header while processing the request. If omitted, 
   *   the response header defaults to: The content type is text/html,
   *   the character set as determined by [charset], the caching header is
   *   set according to [no_cache].
   *)


(* ======================================================================
 * History:
 *
 * $Log: wd_run_cgi.mli,v $
 * Revision 3.6  2003/03/21 14:23:44  stolpmann
 * 	ocamldoc updated
 *
 * Revision 3.5  2003/01/15 23:04:47  stolpmann
 * 	New option ~uifile
 *
 * Revision 3.4  2003/01/04 21:55:25  stolpmann
 * 	new record response_header
 *
 * Revision 3.3  2002/02/16 17:29:45  stolpmann
 * 	mostly ocamldoc.
 *
 * Revision 3.2  2002/02/14 16:15:21  stolpmann
 * 	Added copyright notice.
 *
 * Revision 3.1  2002/02/12 20:29:23  stolpmann
 * 	Initial release at sourceforge.
 *
 * Revision 1.5  2002/02/05 18:43:55  gerd
 * 	It is now possible to pass the session_manager
 *
 * Revision 1.4  2002/01/30 15:14:03  gerd
 * 	New: ~charset.
 * 	Updated comments.
 *
 * Revision 1.3  2002/01/14 15:03:24  gerd
 * 	Major change: Typing has been completely revised, and almost
 * every tiny thing has now a new type. Also renamed a lot.
 *
 * Revision 1.2  2000/12/06 15:26:47  gerd
 * 	Support for the ~self_url argument.
 *
 * Revision 1.1  2000/11/30 18:29:07  gerd
 * 	Initial revision
 *
 *)
