Ocamlnet 3 Reference Manual : Netcgi.cgi

# Class type Netcgi.cgi

    class type cgi = object .. end

Object symbolizing a CGI-like request/response cycle.

This is the minimal set of services a connector must provide. Additional methods may be defined for specific connectors.

### Arguments -- data sent to the script

    method argument : string -> cgi_argument

`#argument name` returns the value of the argument named `name`. If the argument appears several times, only one of its instances is used.
Raises `Not_found` if no such argument exists.

    method argument_value : ?default:string -> string -> string

`#argument_value` returns the value of the argument as a string. If the argument does not exist, the `default` is returned.
`default` : defaults to `""`.

    method argument_exists : string -> bool

`#argument_exists` returns `false` if the named parameter is missing and `true` otherwise.

    method multiple_argument : string -> cgi_argument list

`#multiple_argument name` returns all the values of the argument named `name`.

    method arguments : cgi_argument list

The complete list of arguments.

    method environment : cgi_environment

The environment object. This object is the "outer layer" of the activation object that connects it with real I/O channels.

    method request_method : [ `DELETE | `GET | `HEAD | `POST | `PUT of cgi_argument ]

The HTTP method used to make the request.

    method finalize : unit -> unit

This method calls `#finalize` for every CGI argument (including the possible one of PUT) to ensure that all files are deleted. It also executes all functions registered with `#at_exit`. It does not close the in/out channels, however. This method is not registered in the garbage collector, and it is a bad idea to do so. However, all connectors offered in Netcgi automatically call `#finalize` at the end of the request cycle (even when its terminated by an uncaught exception when `#config.default_exn_handler` is true) so you do not have to worry much about calling it yourself.

### Self-referencing URL

    method url : ?protocol:Nethttp.protocol ->
           ?with_authority:other_url_spec ->
           ?with_script_name:other_url_spec ->
           ?with_path_info:other_url_spec ->
           ?with_query_string:query_string_spec -> unit -> string

Returns the URL of the current CGI-like script. (Note that it may differ from the actual URL that requested the script if, for example, rewriting rules were specified in the web server configuration.)
`protocol` : The URL scheme. By default, the URL scheme is used that is described in the environment
`with_authority` : Whether to include authority part (e.g. http or https) of the URL, and if yes, from which source. Default: ``Env`.
`with_script_name` : Whether to include the part of the URL path identifying the CGI script, and if yes, from which source. Default: ``Env`.
`with_path_info` : Whether to include the rest of the URL path exceeding the script name, and if yes, from which source. Default: ``Env`.
`with_query_string` : Whether to include a query string, and if yes, which one. Only arguments with `#store` being ``Memory` will be added. Default: ``None`, i.e. no query string.

### Outputting

    method set_header : ?status:Nethttp.http_status ->
           ?content_type:string ->
           ?content_length:int ->
           ?set_cookie:Nethttp.cookie list ->
           ?set_cookies:Cookie.t list ->
           ?cache:cache_control ->
           ?filename:string ->
           ?language:string ->
           ?script_type:string ->
           ?style_type:string -> ?fields:(string * string list) list -> unit -> unit

Sets the header (removing any previous one). When the output channel supports transactions, it is possible to set the header (possibly several times) until the `#out_channel` is commited for the first time or `#env#send_output_header()` is called. When there is no support for transactions, the header must be set before the first byte of output is written.

If `#set_header` is called a second time, it will overwrite all the header fields.

`status` : Sets the HTTP status of the reply according to RFC 2616. Defaults to "no status", but the server normally complements an ``Ok` status in this case.
`content_type` : Sets the content type. Defaults to `"text/html"`.
`content_length` : Sets the content length (in bytes). Default: No such field.
`set_cookie` : Deprecated, use `set_cookies`.
`set_cookies` : Sets a number of cookies. Default: `[]`. Remember that the browser may not support more than 20 cookies per web server. You can query the cookies using `env#cookies` and `env#cookie`. If you set cookies, you want to think about an appropriate `cache` setting. You may also want to add a P3P header (Platform for Privacy Preferences) -- otherwise your cookies may be discarded by some browsers.
`cache` : Sets the cache behavior for replies to GET requests. The default is ``Unspecified`. It is strongly recommended to specify the caching behaviour!!! You are on the safe side with ``No_cache`, forcing every page to be regenerated. If your data do not change frequently, ``Max_age n` tells the caches to store the data at most `n` seconds.
`filename` : Sets the filename associated with the page. This filename is taken for the "save as..." dialog. Default: `""`, i.e. no filename. Note: It is bad practice if the filename contains problematic characters (backslash, double quote, space), or the names of directories. It is recommended that you set `content_type` to "application/octet-stream" for this feture to work with most browsers and, if possible, to set `content_length` because that usually improves the download dialog.)
`script_type` : Sets the language of the script tag (for HTML replies). It is recommended to use this field if there are `ONXXX` attributes containing scripts before the first `<SCRIPT>` element, because you cannot specify the script language for the `ONXXX` attributes otherwise. `script_type` must be a media type, e.g. "text/javascript". Default: no language is specified.
`style_type` : Sets the language of the style tag (for HTML replies). It is recommended to use this field if there are `STYLE` attributes containing scripts before the first `<STYLE>` element, because you cannot specify the style language for the `STYLE` attributes otherwise. `style_type` must be a media type, e.g. "text/css". Default: no language is specified.
`fields` : Sets additional fields of the header. Default: `[]`.

    method set_redirection_header : ?set_cookies:Cookie.t list ->
           ?fields:(string * string list) list -> string -> unit

Sets the header such that a redirection to the specified URL is performed. If the URL begins with "http:" the redirection directive is passed back to the client, and the client will repeat the request for the new location (with a GET method). If the URL begins with "/", the server performs the redirection, and it is invisible for the client.

    method output : Netchannels.trans_out_obj_channel

Deprecated.Use `#out_channel` instead.

    method out_channel : Netchannels.trans_out_obj_channel

The output channel to which the generated content is intended to be written. The header is not stored in this channel, so `#pos_out` returns the size of the DATA in bytes (useful to set Content-Length). Note that HEAD requests must not send back a message body so, in this case, all data sent to this channel is discarded. This allows your scripts to work unmodified for GET, POST and HEAD requests.

The output channel may have transactional semantics, and because of this, it is an `trans_out_obj_channel`. Implementations are free to support transactions or not.

After all data have been written, the method `#commit_work()` must be called, even if there is no support for transactions.

Simple Example:

            cgi # out_channel # output_string "Hello world!\n";
            cgi # out_channel # commit_work()

Example for an error handler and a transaction buffer: If an error happens, it is possible to roll the channel back, and to write the error message.

            try
              cgi # set_header ... ();
              cgi # out_channel # output_string "Hello World!"; ...
              cgi # out_channel # commit_work();
            with err ->
              cgi # out_channel # rollback_work();
              cgi # set_header ... ();
              cgi # out_channel # output_string "Software error!"; ...
              cgi # out_channel # commit_work();

    method at_exit : (unit -> unit) -> unit

`#at_exit f` registers the function `f` to be executed when `#finalize` is called (which is done automatically when the request finishes). The functions are executed in the reverse order in which they were registered.