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.

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.

This web site is published by Informatikbüro Gerd Stolpmann

Plasma	GitLab	Archive
Projects	Blog	Knowledge