class type cgi =object
..end
This is the minimal set of services a connector must provide.
Additional methods may be defined for specific connectors.
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.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
method environment : cgi_environment
method request_method : [ `DELETE | `GET | `HEAD | `POST | `PUT of cgi_argument ]
method finalize : unit -> unit
#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.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
protocol
: The URL scheme. By default, the URL scheme is
used that is described in the environmentwith_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.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
#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
method output : Netchannels.trans_out_obj_channel
#out_channel
instead.method out_channel : Netchannels.trans_out_obj_channel
#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.