# Class type Netcgi_env.cgi_environment

    class type cgi_environment = object .. end

The class type cgi_environment contains the resources by which the CGI activation is connected to the "outer world". In particular, the following applies:

- CGI properties: These are the global properties of the CGI request such as the HTTP method, which HTTP server serves the request, and which client sent the request. For a classic CGI environment, the properties are the environment variables not beginning with `"HTTP_"`, and neither `"CONTENT_LENGTH"` nor `"CONTENT_TYPE"`.
- Input header: The header of the HTTP request. For a classic CGI environment, the input header can be extracted from the process environment. It consists of all variables beginning with `"HTTP_"` and the variables `"CONTENT_LENGTH"` and `"CONTENT_TYPE"`.
- Input channel: Over the input channel the HTTP request can be read in. The input state tracks which parts of the request have already be read. For a classic CGI environment, the input channel contains only the body of the request, and the (required) header field content-length specifies the length of the body in bytes.
- Output header: The header of the HTTP response.
- Output channel: Over the output channel the HTTP response is sent. The output state tracks which parts of the response have already been sent.

The CGI environment cannot only be used for classic CGI but also for non-standard ways of communication with the HTTP server. By design, the header and the body of both the request and the response are separated, and because of this every of these message parts can be processed independently of the other parts.

There is a certain protocol between the environment and the `cgi_activation` objects.

- The `cgi_activation` object expects that the input state of the environment is at least ``Received_header` when it starts to process the request. This means that it is the task of the environment to read the request header in.
- The `cgi_activation` object reads the request body from `input_ch`, and modifies the input state as it reads the body
- The `cgi_activation` object sets the response header in the environment, and calls `send_output_header` when the right moment for sending the output header is reached. It does not write the response header to `output_ch` itself. This is the sole task of the `send_output_header` method of the environment.
- After the output header is sent, the `cgi_activation` object writes the response body to `output_ch`. The output state is modified by this object.

    method config : cgi_config

The CGI configuration

## Standard properties

The following properties are standardised by CGI. The methods return `""` or `None` (in the case of the port number) when the property is not available.

    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

## Non-standard properties

    method cgi_property : ?default:string -> string -> string

Returns a (possibly non-standard) environment property. If the property is not set, `Not_found` will be raised unless the `default` argument is passed. The `default` argument determines the result of the function in this case.

The method takes the case-sensitive name and returns the value of the property. Usually, these properties have uppercase names.

For example, `cgi_gateway_interface` returns the same as

     cgi_property ~default:"" "GATEWAY_INTERFACE"

You can normally not access those fields coming from the HTTP header. Use the method `input_header_field` instead.

    method cgi_properties : (string * string) list

All properties

    method cgi_https : bool

A well-known extension is the `HTTPS` property. It indicates whether a secure connection is used (SSL/TLS). This method interprets this property and returns true if the connection is secure. This method fails if there is a `HTTPS` property with an unknown value.

    method cgi_request_uri : string

This is the URI path as passed in the HTTP request, without preprocessing

    method protocol : protocol

## Request header

    method input_header : Netmime.mime_header

The whole header

    method input_header_field : ?default:string -> string -> string

Returns the value of a field of the request header. If the field does not exist, `Not_found` will be raised unless the `default` argument is passed. The `default` argument determines the result of the function in this case.

If there are several fields with the same name only the first field will be returned.

The anonymous string is the name of the field. The name is case-insensitive, and it does not matter whether it consists of lowercase or uppercase letters. If the name is a compound name, the parts are separated by "-", e.g. `"content-length"`.

    method multiple_input_header_field : string -> string list

Returns the values of all fields with the passed name of the request header.

    method input_header_fields : (string * string) list

Returns the input header as (name,value) pairs. The names may consist of lowercase or uppercase letters.

    method user_agent : string

Returns the `"User-agent"` field of the request header

    method cookies : (string * string) list

Returns the list of cookies found in the request header

    method input_content_length : int

Returns the `"Content-length"` request header field, or raises `Not_found` if it is not set

    method input_content_type_string : string

Returns the `"Content-type"` request header field or `""` if it is not set

    method input_content_type : string * (string * Mimestring.s_param) list

Returns the parsed `"Content-type"` request header field, or raises `Not_found` if it is not set. See also `Mimestring.scan_mime_type_ep`.

## The input channel transferring the request body

    method input_ch : Netchannels.in_obj_channel

The input channel as such

    method input_state : input_state

Returns the current input state

    method set_input_state : input_state -> unit

Sets the input state. This method should only be called by `cgi_activation` implementations.

## Response header

    method output_header : Netmime.mime_header

The whole response header

    method output_header_field : ?default:string -> string -> string

Returns the value of a field of the response header. If the field does not exist, `Not_found` will be raised unless the `default` argument is passed. The `default` argument determines the result of the function in this case.

If there are several fields with the same name only the first field will be returned.

The anonymous string is the name of the field. The name is case-insensitive, and it does not matter whether it consists of lowercase or uppercase letters. If the name is a compound name, the parts are separated by "-", e.g. `"content-length"`.

    method multiple_output_header_field : string -> string list

Returns the values of all fields with the passed name of the repsonse header.

    method output_header_fields : (string * string) list

Returns the output header as (name,value) pairs. The names may consist of lowercase or uppercase letters.

    method set_output_header_field : string -> string -> unit

Sets the value of a field of the response header. The previous value, if any, is overwritten. If there have been multiple values, all values will be removed and replaced by the single new value.

    method set_multiple_output_header_field : string -> string list -> unit

Sets multiple values of a field of the response header. Any previous values are removed and replaced by the new values.

    method set_output_header_fields : (string * string) list -> unit

Sets the complete repsonse header at once.

    method set_status : Nethttp.http_status -> unit

Sets the response status. This is by definition the same as setting the `Status` output header field.

    method send_output_header : unit -> unit

If the output state is ``Start`, this method will encode and send the output header to the output channel, and the state will be changed to ``Sent_header`.

The method will fail if the output state is not ``Start`.

Note that this method is usually only called by the `cgi_activation` object.

## The output channel transferring the response

    method output_ch : Netchannels.out_obj_channel

The output channel as such

    method output_state : output_state

Returns the output state

    method set_output_state : output_state -> unit

Sets the output state. This method should only be called by `cgi_activation` implementations.

    method log_error : string -> unit

Outputs a log message to the error log.