(* $Id: netcgi_types.mli 1016 2006-10-02 13:58:45Z gerd $
* ----------------------------------------------------------------------
*
*)
(** Basic types for CGI and related protocols *)
exception Resources_exceeded
(** Raised when the CGI input is longer than the configured maximum *)
(* {b Representation of CGI arguments}
*
* There are two representations of CGI arguments, {!Netcgi_types.simple_message}
* and {!Netmime.mime_message}. The first consists only of a name and a value
* while the second representation has additionally a MIME header.
*
* The [simple_message] arguments are used when the transport mechanism
* does not allow the inclusion of a header. This is the case for all
* [GET] parameters, and for [POST] parameters in URL-encoded format.
* The [mime_message] representation is used if the posted message is
* form-encoded.
*
* Independently of the representation, the arguments are stored somewhere.
* Supported stores are currently [`Memory] and [`File].
* (Restriction: A [simple_message] can only be stored in [`Memory] for now.)
*)
class type simple_message = Netmime.mime_body
(** A [simple_message] stores the value of the CGI argument as an
* unstructured string value. It happens that {!Netmime.mime_body}
* is already a class type for such unstructured values, so we are
* reusing this type here.
*)
(* The types mime_header and mime_message are now defined in Netmime. *)
type store =
[ `Memory
| `File of string
]
(** Determines where the data of the CGI argument are actually stored.
* - [`Memory]: In an O'Caml string
* - [`File name]: In the file [name]. The file contains the value of
* the argument after all transfer-related encodings have been
* removed (i.e. URL-encoding, and MIME transfer encodings).
*)
type representation =
[ `Simple of simple_message
| `MIME of Netmime.mime_message
]
(** Representations of CGI arguments:
* - [`Simple msg]: The argument is unstructured
* - [`MIME msg]: The argument has a MIME header in addition to the value
*)
(* In general, the [store] is just a container, and the interpretation
* of the [store] depends on the [representation] of the argument. For the
* two defined representations, the container holds the decoded value of
* the argument. For future extensions of [representation], the [store] might
* be interpreted differently, though.
*)
(* The exception Value_is_immutable has been renamed to just "Immutable",
* and its definition has been moved to the module Netmime.
*)
(** The interface of CGI argument objects *)
class type cgi_argument =
object
method name : string
(** The name of the CGI argument *)
method value : string
(** The value of the CGI argument, after all transfer encodings have
* been removed. If the
* value is stored in a file, the file will be loaded.
*)
method open_value_rd : unit -> Netchannels.in_obj_channel
(** Opens the contents of the value as an input channel. This works
* for all kinds of arguments, independent of [store] and [representation].
*)
method ro : bool
(** Whether this argument is read-only or not *)
method store : store
(** Returns where the argument value is stored *)
method content_type : string
(** Returns the content type of the header, or ["text/plain"] when the
* header is missing. Parameters of the content type have been stripped
* off (e.g. [charset]).
*)
method content_type_params : (string * Mimestring.s_param) list
(** The parameters of the content type of the header, or [[]] when
* the header is missing. Below you find access method for frequently
* used parameters.
*)
method charset : string
(** The [charset] parameter of the content type of the header, or [""]
* when there is no such parameter, or no header.
*)
method filename : string option
(** The [filename] parameter found in the header of file uploads.
* When present, [Some name] is returned, and [None] otherwise.
*)
method representation : representation
(** The representation of the CGI argument *)
method finalize : unit -> unit
(** Arguments stored in temp files must be deleted when the argument is no
* longer used. You can call [finalize] to delete such files. The
* method does not have any effect when [store = `Memory].
* The method does never raise any exceptions. If the file does no longer
* exist (e.g. because it is moved away), or if there are any problems
* deleting the file, the error will be suppressed.
* The [finalize] method is not registered in the garbage collector.
* You can do that, but it is usually better to call this method manually.
* [cgi_activation] supports this.
*)
method set_value : string -> unit
(** If the [representation] supports mutable values, the value is set
* to the passed string. The other properties of the argument are not
* modified.
*
* If the [representation] does not support this feature, the exception
* {!Netmime.Immutable} will be raised.
*)
method open_value_wr : unit -> Netchannels.out_obj_channel
(** Opens the value for writing. The current value is overwritten.
* If the value is immutable, the exception {!Netmime.Immutable} will
* be raised.
*)
end
type cgi_cookie = Nethttp.cookie =
{ cookie_name : string;
(** The name of the cookie *)
cookie_value : string;
(** The value of the cookie. There are no restrictions on the
* value of the cookie
*)
cookie_expires : float option;
(** Expiration:
* - [None]: the cookie expires when the browser session ends.
* - [Some t]: the cookie expires at the time [t] (seconds since
* the epoch)
*)
cookie_domain : string option;
(** Cookies are bound to a certain domain, i.e. the browser sends
* them only when web pages of the domain are requested:
*
* - [None]: the domain is the hostname of the server
* - [Some domain]: the domain is [domain]
*)
cookie_path : string option;
(** Cookies are also bound to certain path prefixes, i.e. the browser
* sends them only when web pages at the path or below are requested.
*
* - [None]: the path is script name + path_info
* - [Some p]: the path is [p]. With [Some "/"] you can disable the
* path restriction completely.
*)
cookie_secure : bool;
(** Cookies are also bound to the type of the web server:
* [false] means servers without SSL, [true] means servers with
* activated SSL ("https").
*)
}
type status = Nethttp.http_status
type request_method =
[ `GET
| `HEAD
| `POST
| `DELETE
| `PUT of cgi_argument
]
(** The supported request methods:
* - [`GET]: Side effect-free request of a web resource
* - [`POST]: Request with side effects
* - [`HEAD]: Only the header of the corresponding [`GET] are requested
* - [`DELETE]: Request to delete the web resource
* - [`PUT arg]: Request to upload the web resource
*)
(* Note that there is also a configuration option in the environment
* that specifies which methods are allowed at all.
*)
type cache_control =
[ `No_cache
| `Max_age of int
| `Unspecified
]
(** This is only a small subset of the HTTP 1.1 cache control features,
* but they are usually sufficient, and they work for HTTP/1.0 as well.
* The directives mean:
* - [`No_cache]:
* Caches are disabled. The following headers are sent:
* [Cache-control: no-cache], [Pragma: no-cache], [Expires:] (now - 1 second)
* - [`Max_age n]:
* Caches are allowed to store a copy of the response for [n] seconds.
* After that, the response must be revalidated.
* [Cache-control: max-age n], [Cache-control: must-revalidate],
* [Expires:] (now + [n] seconds)
* - [`Unspecified]:
* No cache control header is added to the response.
*
* Notes:
* - Cache control directives only apply to GET requests; POST requests
* are never cached
* - Not only proxies are considered as cache, but also the local disk
* cache of the browser
* - HTTP/1.0 did not specify cache behaviour as strictly as HTTP/1.1
* does. Because of this the [Pragma] and [Expires] headers are sent, too.
* These fields are not interpreted by HTTP/1.1 clients because
* [Cache-control] has higher precedence.
*)
type query_string_spec =
[ `Initial | `Current | `Args of cgi_argument list | `None ]
(** Determines how the query part of URLs is generated:
*
* - [`Initial]: The query string is created from the initial
* CGI arguments
* - [`Current]: The query string is created from the current
* CGI arguments
* - [`Args l]: The query string is created from the specified argument list
* - [`None]: The query string is omitted
*)
type other_url_spec =
