libocamlnet-ocaml-dev 4.1.2-3 / usr / lib / ocaml / netcgi2 / netcgi1_compat.mli

(* netcgi_compat.mli

   Copyright (C) 2005-2006

     Christophe Troestler
     email: Christophe.Troestler@umh.ac.be
     WWW: http://math.umh.ac.be/an/

   This library is free software; see the file LICENSE for more information.

   This library 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 file
   LICENSE for more details.
*)

(** Compatibility module with the previous version of Netcgi.
 *
 * Opening this module allows a project using the old Netcgi_env and
 * Netcgi_types to compile with minor changes.  For documentation,
 * please see the original modules (in the netcgi1 directory).  If you are
 * a first time user or start a new project, {b do not use this
 * module}.
 *
 * Functions that are useful to migrate a project are emphasized with
 * "{b Portage:}".  Some comments accompany the functions that changed
 * to give some motivation for the new API.  (It is useful to refer to
 * the old documentation to understand everything.)
 *
 * @deprecated {i Use the new API instead.}
 *
 * @version $Id: netcgi_compat.mli,v 1.7 2005/11/04 00:53:05 chris_77 Exp $
 *)

exception Not_implemented of string
  (** Raised by some functions/exceptions when a feature of the old model
    * cannot be implemented in the new model or vice versa
   *)

module Netcgi_env :
sig
  type input_mode = [ `Standard (* | `Direct *) ]
      (** This is not used anywhere.  Moreover this is protocol
	  dependent. *)

  type input_state =
      [ `Start
      | `Receiving_header | `Received_header
      | `Receiving_body | `Received_body      ]
	(** This is not the business of the user.  Rather than to
	    document [#set_input_state] as such, we prefer not to
	    allow the user to have access to it at the first
	    place... *)

  type output_mode = [ `Standard (* | `Direct *) ]
      (** This is not used anywhere.  Moreover "non-parsed header" is
	  not supported by all connectors. *)

  type output_state =
      [ `Start
      | `Sending_header      | `Sent_header
      | `Sending_body        | `Sent_body
      | `Sending_part_header | `Sent_part_header
      | `Sending_part_body   | `Sent_part_body
      | `End
      ]
	(** This is not the business of the user.  In the new API, it
	    is handled transparently. *)

  type protocol_version = Nethttp.protocol_version
  type protocol_attribute = Nethttp.protocol_attribute
  type protocol = Nethttp.protocol
  type workaround =
      [ `Work_around_MSIE_Content_type_bug | `Work_around_backslash_bug  ]
	(** The [Work_around_] part has been dropped as it is clear at
	    the spot of use. *)

  (** Now simply called {!Netcgi.config}. *)
  type cgi_config = {
    tmp_directory : string;
    tmp_prefix : string;
    permitted_http_methods : string list;
    (** Now has type [[`GET | `HEAD | `POST | `DELETE | `PUT] list]
	for coherence with {!Netcgi.cgi}[#request_method]. *)
    permitted_input_content_types : string list;
    input_content_length_limit : int;
    workarounds : workaround list;
  }

  val default_config : cgi_config

  val of_compat_config : cgi_config -> Netcgi.config
    (** {b Portage:} [of_compat_config c] transform the old configuration [c]
	into one suitable for the new interface. *)

  val to_compat_config : Netcgi.config -> cgi_config
    (** {b Portage:} [to_compat_config c] transform the new configuration [c]
	into one suitable for the old interface. *)


  class type cgi_environment =
  object
    method config : cgi_config

    method cgi_gateway_interface  : string
    method cgi_server_software    : string
    method cgi_server_name        : string
    method cgi_server_protocol    : string
    method cgi_server_port        : int option
    method cgi_request_method     : string
    method cgi_path_info          : string
    method cgi_path_translated    : string
    method cgi_script_name        : string
    method cgi_query_string       : string
    method cgi_remote_host        : string
    method cgi_remote_addr        : string
    method cgi_auth_type          : string
    method cgi_remote_user        : string
    method cgi_remote_ident       : string
    method cgi_property          : ?default:string -> string -> string
    method cgi_properties : (string * string) list
    method cgi_https              : bool

    method cgi_request_uri : string
      (** I rest to be convinced we need this.  Is it provided by web
	  servers different from Apache?  Why is the [#url] method not
	  enough? *)
    method protocol : protocol

    method input_header : Netmime.mime_header

    method input_header_field : ?default:string -> string -> string
    method multiple_input_header_field : string -> string list
    method input_header_fields : (string * string) list
    method user_agent : string
    method cookies : (string * string) list
      (** Cookies are returned in decoded form.  An additional
	  [#cookie] method has been added for convenience and
	  coherence with e.g. {!Netcgi.cgi.arguments}
	  v.s. {!Netcgi.cgi.argument}. *)
    method input_content_length : int
    method input_content_type_string : string
    method input_content_type : (string * (string * Netmime_string.s_param) list)
      (** Type now is [unit -> string * (string * Netmime_string.s_param)
	  list] to be coherent with {!Netmime.mime_header_ro}. *)

    method input_ch : Netchannels.in_obj_channel
      (** Not the user business. *)
    method input_state : input_state
      (** Not the user business. *)
    method set_input_state : input_state -> unit
      (** Not the user business. *)

    method output_header : Netmime.mime_header
    method output_header_field : ?default:string -> string -> string
    method multiple_output_header_field : string -> string list
    method output_header_fields : (string * string) list
    method set_output_header_field : string -> string -> unit
    method set_multiple_output_header_field : string -> string list -> unit
    method set_output_header_fields : (string * string) list -> unit
    method set_status : Nethttp.http_status -> unit
    method send_output_header : unit -> unit

    method output_ch : Netchannels.out_obj_channel
      (** @deprecated in favor of [out_channel] by analogy with the
	  standard library -- even though it is a "channel object".  *)
    method output_state : output_state
      (** Not the user business. *)
    method set_output_state : output_state -> unit
      (** Not the user business. *)
    method log_error : string -> unit
  end

  val to_compat_environment : Netcgi.cgi_environment -> cgi_environment
    (** {b Portage:} [to_compat_environment e] converts the new environment
	[e] to the old interface. *)

  val of_compat_environment : cgi_environment -> Netcgi.cgi_environment
    (** {b Portage:} [of_compat_environment e] converts the old environment
	[e] to the new interface. *)
end


module Netcgi_types :
sig
  class type simple_message = Netmime.mime_body

  type store = [ `Memory | `File of string ]
      (** Embedded in the single place of use. *)
  type representation =
      [ `Simple of simple_message | `MIME of Netmime.mime_message ]
	(** Embedded in the single place of use. *)

  (** {b Portage:} In addition to defining a type, the following
      [cgi_argument] also defines a conversion function that allows to
      connect old scripts to the new infrastructure.  Finalizing
      [cgi_argument a] will also finalize [a].  *)
  class type cgi_argument =
  object
    method name : string
    method value : string
    method open_value_rd : unit -> Netchannels.in_obj_channel
    method ro : bool
      (** Irrelevant: there are no methods to mutate an argument. *)
    method store : store
    method content_type : string
    method content_type_params : (string * Netmime_string.s_param) list
      (** Method [content_type : unit -> string * (string *
	  Netmime_string.s_param) list] defined instead of [content_type]
	  and [content_type_params] to be coherent with
	  {!Netmime.mime_header_ro} -- yet as easy to use. *)
    method charset : string
    method filename : string option
    method representation : representation
    method finalize : unit -> unit
    method set_value : string -> unit
      (** Dealing with the arguments is the task of an higher order
	  library.  In fact, it is generally misleading to think
	  arguments as mutable because one must accomodate the back
	  button -- so cache, history,... will use the "initial args".
	  Moreover, the only place where mutability is interesting is
	  the [#url] method which -- as already remarked -- can be
	  dealt with in a purely functional way.

	  The new interface contains commodity functions to update
	  lists of arguments (see {!Netcgi.Argument}).  *)
    method open_value_wr : unit -> Netchannels.out_obj_channel
      (** See [#set_value]. *)
  end

  val to_compat_argument : Netcgi.cgi_argument ->  cgi_argument
    (** {b Portage:} [to_compat_argument a] converts a new style argument
	[a] to an old style one.  Finalizing [to_compat_argument a] will also
	finalize [a].  *)

  val of_compat_argument : cgi_argument -> Netcgi.cgi_argument
    (** {b Portage:} [of_compat_argument a] converts an old style argument
	[a] to a new style one.  Finalizing [of_compat_argument a] will also
	finalize [a].  *)


  type cgi_cookie = Nethttp.netscape_cookie = {
    cookie_name : string;
    cookie_value : string;
    cookie_expires : float option;
    cookie_domain : string option;
    cookie_path : string option;
    cookie_secure : bool;
  }

  type status = Nethttp.http_status

  type request_method =
      [ `GET | `HEAD | `POST | `DELETE | `PUT of cgi_argument ]

  type cache_control = [ `No_cache | `Max_age of int | `Unspecified ]

  type query_string_spec =
      [ `Initial | `Current | `Args of cgi_argument list | `None ]

  type other_url_spec = [ `Env | `This of string | `None ]

  (** {b Portage:} In addition to defining a type, the following
      [cgi_activation] also defines a conversion function that allows
      to connect old scripts to the new infrastructure.  Renamed
      simply [cgi] as this is the main cgi-like abstraction.  *)
  class type cgi_activation =
  object
    method environment : Netcgi_env.cgi_environment
    method request_method : request_method

    method initial_arguments : (string * cgi_argument) list
    method initial_argument : string -> cgi_argument
    method initial_argument_value : ?default:string -> string -> string
    method initial_multiple_argument : string -> cgi_argument list

    (** Mutability of arguments has been dropped.  We indeed believe
	that how to deal with arguments is the role of a higher level
	library, so it is unconvenient that they are mutable (force
	copying even if unecessary).  {!Netcgi.Argument} has a few
	helper functions to help manipulating lists of immutable
	arguments.  Moreover, mutable arguments send the wrong message
	to the user (imagine one wants to keep a cache of args ->
	response) and unnecessarily complicate the interface. *)
    method arguments : (string * cgi_argument) list
      (** It has type [argument list] as the name is redundant and
	  this is better suited for the {!Netcgi.query_string_spec}
	  optional arguments. *)
    method argument : string -> cgi_argument
    method argument_value : ?default:string -> string -> string
    method multiple_argument : string -> cgi_argument list

    method set_arguments : ?fin:bool -> cgi_argument list -> unit
    method update_argument : ?fin:bool -> cgi_argument -> unit
    method update_multiple_argument : ?fin:bool -> cgi_argument list -> unit
    method delete_argument : ?fin:bool -> string -> unit

    method url :
      ?protocol:Netcgi_env.protocol ->
      ?with_authority:other_url_spec ->        (* default: `Env *)
      ?with_script_name:other_url_spec ->      (* default: `Env *)
      ?with_path_info:other_url_spec ->        (* default: `Env *)
      ?with_query_string:query_string_spec ->  (* default: `None *)
      unit -> string

    method output : Netchannels.trans_out_obj_channel
      (** @deprecated in favor of [out_channel] for coherence with the
	  standard library --- this is also to avoid
	  [cgi#output#output ...]  which looks odd. *)

    method set_header :
      ?status:status ->
      ?content_type:string ->
      ?cache:cache_control ->
      ?filename:string ->
      ?language:string ->
      ?script_type:string ->
      ?style_type:string ->
      ?set_cookie:cgi_cookie list ->
      ?fields:(string * string list) list ->
      unit -> unit
      (** Added [?content_length] for user convenience and deprecated
	  [?set_cookie] in favor of [?set_cookies] for coherence
	  e.g. with [?fields]. *)

    method set_redirection_header : string -> unit

    method finalize : unit -> unit
  end

  val to_compat_activation : Netcgi.cgi -> cgi_activation
    (** {b Portage:} [to_compat_activation] converts a new style 
        cgi object to an old cgi_activation object. *)

  val of_compat_activation : cgi_activation -> Netcgi.cgi
    (** {b Portage:} [of_compat_activation] converts an old style 
        cgi_activation to a new CGI-like object. *)
end

module Netcgi :
sig
  type argument_processing =
      [ `Memory
      | `File
      | `Automatic ]
	
  type operating_type =
      [ `Direct of string (* separator *)
      | `Transactional of
          (Netcgi_env.cgi_config -> Netchannels.out_obj_channel ->
             Netchannels.trans_out_obj_channel)
      ]

  class simple_argument :
    ?ro:bool -> string -> string -> Netcgi_types.cgi_argument

  class mime_argument :
    ?work_around_backslash_bug:bool ->
  string -> Netmime.mime_message -> Netcgi_types.cgi_argument

  class std_activation :
    ?env:Netcgi_env.cgi_environment ->
    ?processing:(string -> Netmime.mime_header -> argument_processing) ->
    ?operating_type:operating_type ->
    unit ->
      Netcgi_types.cgi_activation

  val buffered_transactional_optype : operating_type

  val tempfile_transactional_optype : operating_type

end



(*
  Local Variables:
  mode: outline-minor
  outline-regexp: " *\\(val\\|module\\|method\\) "
  End:
*)