--- /dev/null
+(* $Id$
+ * ----------------------------------------------------------------------
+ *
+ *)
+
+(* FOR SIMPLE CGI PROGRAMS:
+ *
+ * If you do not need all the features of the API below, the following may
+ * be enough:
+ *
+ * - At the beginning of the main program, call 'parse_argument' with
+ * either 'default_config' as argument or with a customized configuration.
+ * - Use 'argument_value(name)' to get the string value of the CGI parameter
+ * 'name'. If you like, you can also open the Cgi.Operators module and
+ * write '!$ name' instead. Here, !$ is a prefix operator equivalent to
+ * argument_value.
+ *
+ * If you do not change the default configuration, you do not need to
+ * worry about temporary files - there are not any.
+ *
+ * Most of the other functions defined below deal with file uploads, and
+ * are only useful for that.
+ *)
+
+
+(**********************************************************************)
+(* CGI functions *)
+(**********************************************************************)
+
+(* First, the general interface to the CGI argument parser. *)
+
+exception Resources_exceeded
+
+type argument
+
+type argument_processing =
+ Memory (* Keep the value of the argument in memory *)
+ | File (* Store the value of the argument into a temporary file *)
+ | Automatic (* Store only large arguments into files. An argument
+ * value is large if it is longer than about one block (4K).
+ * This is not an exact definition.
+ *)
+
+type workaround =
+ Work_around_MSIE_Content_type_bug
+ (* There is a bug in MSIE I observed together with SSL connections.
+ * The CONTENT_TYPE passed to the server has sometimes the wrong
+ * format. This option enables a workaround if the user agent string
+ * contains the word "MSIE".
+ *)
+ | Work_around_backslash_bug
+ (* There is a bug in many browsers: The backslash character is not
+ * handled as an escaping character in MIME headers. Because DOS-
+ * based systems use the backslash regularly in filenames, this bug
+ * matters.
+ * This option changes the interpretation of backslashes such that
+ * these are handled as normal characters. I do not know any browser
+ * that is not affected by this bug, so there is no check on
+ * the user agent string.
+ *)
+
+
+type config =
+ { maximum_content_length : int;
+ (* The maximum CONTENT_LENGTH. Bigger requests trigger an
+ * Resources_exceeded exception. This feature can be used
+ * to detect primitive denial-of-service attacks.
+ *)
+ how_to_process_arguments : argument -> argument_processing;
+ (* After the beginning of an argument has been decoded, the
+ * type of processing is decided by invoking this function on
+ * the argument. Note that the passed argument is incomplete -
+ * it does not have a value. You can assume that name, filename,
+ * MIME type and the whole header are already known.
+ * - THIS CONFIGURATION PARAMETER ONLY AFFECTS ARGUMENTS
+ * "POST"ED FROM THE CLIENT IN FORM-ENCODED REPRESENTATION.
+ * All other transport methods can only handle the Memory
+ * processing type.
+ *)
+ tmp_directory : string;
+ (* The temporary directory to use for the temporary files. *)
+ tmp_prefix : string;
+ (* A prefix for temporary files. It is recommended that the prefix
+ * contains a part that is random or that depends on rapidly changing
+ * environment properties. For example, the process ID is a good
+ * candidate, or the current system time. It is not required that
+ * the prefix is unique; there is a fail-safe algorithm that
+ * computes a unique file name from the prefix, even if several
+ * CGI programs run concurrently.
+ *)
+ workarounds : workaround list;
+ (* Specifies which workarounds should be enabled. *)
+ }
+
+val parse_arguments : config -> unit
+val arguments : unit -> (string * argument) list
+ (* - let () = parse_arguments config:
+ * Decodes the CGI arguments. 'config' specifies limits and processing
+ * hints; you can simply pass default_config (see below).
+ *
+ * - let arglist = get_arguments():
+ * The function returns a list with (name, arg) pairs. The name is
+ * passed back as string while the value is returned as opaque type
+ * 'argument'. Below accessor functions are defined. These functions
+ * require that parse_arguments was invoked before.
+ *
+ * Note 1: You can invoke 'parse_arguments' several times, but only
+ * the first time the arguments are read in. If you call the function
+ * again, it does nothing (even if the config changes). This is also
+ * true if 'parse_arguments' has been invoked after 'set_arguments'.
+ *
+ * Note 2: It is not guaranteed that stdin has been read until EOF.
+ * Only CONTENT_LENGTH bytes are read from stdin (following the CGI spec).
+ *
+ * Note 3: If arguments are processed in File or Automatic mode, the
+ * caller of 'parse_arguments' is responsible for deleting the files
+ * after use. You may consider to apply the at_exit function of the
+ * core library for this purpose. See also 'cleanup' below.
+ *)
+
+val set_arguments : argument list -> unit
+ (* Alternatively, you can set the arguments to use. This overrides any
+ * previously parsed set of arguments, and also any following parsing.
+ * - Intended for debugging, and to make it possible to replace the
+ * CGI parser by a different one while retaining this API.
+ *)
+
+val default_config : config
+ (* maximum_content_length = maxint
+ * how_to_process_arguments = "use always Memory"
+ * tmp_directory = "/var/tmp"
+ * tmp_prefix = "cgi"
+ * workarounds = [ Work_around_MSIE_content_type_bug;
+ * Work_around_backslash_bug;
+ * ]
+ *
+ * Note 1: On some Unixes, a special file system is used for /tmp that
+ * stores the files into the virtual memory (main memory or swap area).
+ * Because of this, /var/tmp is preferred as default.
+ *
+ * Note 2: Filename.temp_file is not used because it depends on
+ * environment variables which are usually not set in a CGI environment.
+ *)
+
+val arg_name : argument -> string
+val arg_value : argument -> string
+val arg_file : argument -> string option
+val arg_mimetype : argument -> string
+val arg_filename : argument -> string option
+val arg_header : argument -> (string * string) list
+ (* The accessor functions that return several aspects of arguments.
+ * arg_name: returns the name of the argument
+ * arg_value: returns the value of the argument. If the value is stored
+ * in a temporary file, the contents of this file are returned, i.e.
+ * the file is loaded. This may have some consequences:
+ * (1) The function may fail because of I/O errors.
+ * (2) The function may be very slow, especially if the file is
+ * non-local.
+ * (3) If the value is bigger than Sys.max_string_length, the function
+ * raises the exception Resources_exceeded. On 32 bit architectures,
+ * strings are limited to 16 MB.
+ * Note that loaded values are put into weak arrays. This makes it
+ * possible that subsequent calls of 'arg_value' on the same argument
+ * can avoid loading the value again, and that unused values will
+ * nevertheless be collected by the GC.
+ * arg_file: returns 'Some filename' if the value resides in a temporary
+ * file, and 'filename' is the absolute path of this file. If the
+ * value is only available in memory, None is returned.
+ * arg_mimetype: returns the MIME type of the argument. Note that the
+ * default MIME type is "text/plain", and that the default is returned
+ * if the MIME type is not available.
+ * arg_filename: returns 'Some filename' if the argument is associated
+ * with a certain filename (e.g. from a file upload); otherwise None
+ * arg_header: returns pairs (name,value) containing the complete header
+ * of the argument. If the transmission protocol does not specify
+ * a header, the empty list is passed back.
+ *)
+
+val mk_simple_arg : name:string -> string -> argument
+ (* mk_simple_arg name value:
+ * Creates a simple argument with only name, and a value passed by string.
+ * The MIME type is "text/plain".
+ *)
+
+val mk_memory_arg
+ : name:string -> ?mime:string -> ?filename:string ->
+ ?header:((string * string) list) -> string -> argument
+ (* mk_memory_arg name mimetype filename header value:
+ * Creates an argument whose value is kept in memory.
+ *
+ * Note: The signature of this function changed in release 0.8.
+ *)
+
+val mk_file_arg
+ : name:string -> ?mime:string -> ?filename:string ->
+ ?header:((string * string) list) -> string -> argument
+ (* mk_file_arg name mimetype filename header value_filename:
+ * Creates an argument whose value is stored in the file
+ * 'value_filename'. If this file name is not absolute, it is interpreted
+ * relative to the directory returned by Sys.getcwd() - this might not
+ * be what you want with respect to mount points and symlinks (and it
+ * depends on the operating system as getcwd is only POSIX.1). The
+ * file name is turned into an absolute name immediately, and the
+ * function arg_file returns the rewritten name.
+ *
+ * Note: The signature of this function changed in release 0.8.
+ *)
+
+
+val cleanup : unit -> unit
+ (* Removes all temporary files that occur in the current set of arguments
+ * (as returned by 'arguments()').
+ *)
+
+
+(* Convenience functions: *)
+
+val argument : string -> argument
+ (* let argument name = List.assoc name (arguments()) -- i.e. returns
+ * the argument with the passed name. Of course, this function expects
+ * that 'parse_arguments' was called before.
+ *)
+
+val argument_value : string -> string
+ (* let argument_value name = arg_value(argument name) -- i.e. returns
+ * the value of the argument.
+ * See also Operators.( !$ ) below.
+ *)
+
+(* For toploop printers: *)
+
+val print_argument : argument -> unit
+
+
+(* Now, the compatibility functions. *)
+
+val parse_args : unit -> (string * string) list
+ (* Decodes the arguments of the CGI and returns them as an association list
+ * Works whatever the method is (GET or POST)
+ *)
+
+val parse_args_with_mimetypes : unit -> (string * string * string) list
+ (* Like parse_args, but returns also the MIME type.
+ * The triples contain (name, mime_type, value).
+ * If an encoding was chosen that does not transfer the MIME type,
+ * "text/plain" is returned.
+ *
+ * THIS FUNCTION SHOULD BE CONSIDERED AS DEPRECATED.
+ * It was included in netstring-0.4, but most people want not only
+ * the MIME type. parse_arguments should be used instead.
+ *)
+
+val header : string -> unit
+ (* Prints the content-type header.
+ * the argument is the MIME type (default value is "text/html" if the
+ * argument is the empty string)
+ *)
+
+val this_url : unit -> string
+ (* Returns the address of the CGI *)
+
+(**********************************************************************)
+(* The Operators module *)
+(**********************************************************************)
+
+(* If you open the Operators module, you can write
+ * !% "name" instead of argument "name", and
+ * !$ "name" instead of argument_value "name"
+ *)
+
+module Operators : sig
+ val ( !% ) : string -> argument
+ (* same as 'argument' above *)
+ val ( !$ ) : string -> string
+ (* same as 'argument_value' above *)
+end
+
+(**********************************************************************)
+(* Low-level functions *)
+(**********************************************************************)
+
+(* Encoding/Decoding within URLs:
+ *
+ * The following two functions perform the '%'-substitution for
+ * characters that may otherwise be interpreted as metacharacters.
+ *
+ * See also the Netencoding module. This interface contains these functions
+ * to keep the compatibility with the old Cgi module.
+ *)
+
+val decode : string -> string
+val encode : string -> string
+
+(* URL-encoded parameters:
+ *
+ * The following two functions create and analyze URL-encoded parameters.
+ * Format: name1=val1&name2=val2&...
+ *)
+
+val mk_url_encoded_parameters : (string * string) list -> string
+ (* The argument is a list of (name,value) pairs. The result is the
+ * single URL-encoded parameter string.
+ *)
+
+val dest_url_encoded_parameters : string -> (string * string) list
+ (* The argument is the URL-encoded parameter string. The result is
+ * the corresponding list of (name,value) pairs.
+ * Note: Whitespace within the parameter string is ignored.
+ * If there is a format error, the function fails.
+ *)
+
+(* Form-encoded parameters:
+ *
+ * According to: RFCs 2388, 2183, 2045, 2046
+ *
+ * General note: This is a simple API to encode/decode form-encoded parameters.
+ * Especially, it is not possible to pass the header of the parts through
+ * this API.
+ *)
+
+val mk_form_encoded_parameters : (string * string * string) list ->
+ (string * string)
+ (* The argument is a list of (name,mimetype,value) triples.
+ * The result is (parstr, boundary), where 'parstr' is the
+ * single form-encoded parameter string, and 'boundary' is the
+ * boundary to separate the message parts.
+ *
+ * THIS FUNCTION IS CURRENTLY NOT IMPLEMENTED!
+ *)
+
+val dest_form_encoded_parameters : string -> boundary:string -> config ->
+ argument list
+ (* The first argument is the form-encoded parameter string.
+ * The second argument is the boundary (extracted from the mime type).
+ * Third argument: Only the workarounds component is used.
+ * The result is
+ * the corresponding list of arguments (all in memory).
+ * If there is a format error, the function fails.
+ * Note: embedded multipart/mixed types are returned as they are,
+ * and are not recursively decoded.
+ * Note: The content-transfer-encodings "7bit", "8bit", "binary",
+ * "base64", and "quoted-printable" are supported.
+ * Note: Parameter names which include spaces or non-alphanumeric
+ * characters may be problematic (the rules of RFC 2047 are NOT applied).
+ * Note: The returned MIME type is not normalized.
+ *)
+
+val dest_form_encoded_parameters_from_netstream
+ : Netstream.t -> boundary:string -> config -> argument list
+ (* let arglist = dest_form_encoded_parameters_from_netstream s b c:
+ * Reads the form-encoded parameters from netstream s. The boundary
+ * is passed in b, and the configuration in c.
+ * A list of arguments is returned.
+ *
+ * See also dest_form_encoded_parameters.
+ *
+ * Restriction: In contrast to dest_form_encoded_parameters, this
+ * function is not able to handle the content-transfer-encodings
+ * "base64" and "quoted-printable". (This is not really a restriction
+ * because no browser uses these encodings in conjunction with HTTP.
+ * This is different if mail transport is chosen. - The reason for
+ * this restriction is that there are currently no stream functions
+ * for decoding.)
+ *)
+
+(* Private functions: *)
+
+val init_mt : (unit -> unit) -> (unit -> unit) -> unit
+
+
+(**********************************************************************)
+(* Compatibility with CGI library by J.-C. Filliatre *)
+(**********************************************************************)
+
+(* The following functions are compatible with J.-C. Filliatre's CGI
+ * library:
+ *
+ * parse_args, header, this_url, decode, encode.
+ *
+ * Note that the new implementation of parse_args can be safely invoked
+ * several times.
+ *
+ * Since release 0.8, Netstring's CGI implementation is again thread-safe.
+ *)
+
+
+(* ======================================================================
+ * History:
+ *
+ * $Log$
+ * Revision 1.1 2000/11/17 09:57:27 lpadovan
+ * Initial revision
+ *
+ * Revision 1.8 2000/06/25 22:34:43 gerd
+ * Added labels to arguments.
+ *
+ * Revision 1.7 2000/06/25 21:40:36 gerd
+ * Added printer.
+ *
+ * Revision 1.6 2000/06/25 21:15:48 gerd
+ * Checked thread-safety.
+ *
+ * Revision 1.5 2000/05/16 22:28:13 gerd
+ * New "workarounds" config component.
+ *
+ * Revision 1.4 2000/04/15 16:47:27 gerd
+ * Last minor changes before releasing 0.6.
+ *
+ * Revision 1.3 2000/04/15 13:09:01 gerd
+ * Implemented uploads to temporary files.
+ *
+ * Revision 1.2 2000/03/02 01:15:30 gerd
+ * Updated.
+ *
+ * Revision 1.1 2000/02/25 15:21:12 gerd
+ * Initial revision.
+ *
+ *
+ *)
projects / helm.git / blobdiff