Previous  Up  Next

Module CamlGI.Cgi


module Cgi: sig .. end
(F)CGI high level functions
exception HttpError of int
module Request: sig .. end

Setting up the application server


type connection 
val establish_server : ?max_conns:int ->
       ?max_reqs:int ->
       ?sockaddr:Unix.sockaddr ->
       ?post_max:int -> (connection -> unit) -> unit
establish_server ?max_conns ?max_reqs ?sockaddr ?post_max f starts a server listening on the socket appropriate for CGI or FCGI and, for each accepted connection conn, executes f conn. The exceptions possibly raised by f are not caught by establish_server. It is no problem that f starts a new thread to handle the connection (and thus returns immediately).
max_conns : is the maximum of connections the web server can make to this script. By default, each connection is processed sequentially, so the default value for max_conns is 1. If you start processes or threads to handle connections, it is your responsability not to accept more than max_conns connections. The value of max_conns only serves to inform the web server about the capabilities of the FCGI script.
max_reqs : is the maximum of requests a web server can multiplex through a given connection. Again, if you start processes ot threads to handle requests, it is your responsability to limit the number of them. max_reqs is only used to inform the web server about how many requests it can multiplex on a given connection. Beware that if you set max_reqs to 1 but have threads handling different requests of a given connection, the outputs may mix-up (thus be incorrect).
sockaddr : the unix or the TCP/IP socket that the script will use to communicate with the web server. Setting this implies that the script uses the FCGI protocol. By default, on uses what is appropriate for the CGI OR FCGI protocol. For example, if your script is listening on port 8888 on a possibly remote machine, you can use Unix.ADDR_INET(Unix.inet_addr_any, 8888).
post_max : set the maximum size for POSTed requests in bytes. This is a security feature to prevent clients from overrunning the server with data. The default is Sys.max_string_length, meaning no limit (besides OCaml ones).

For FastCGI, the environment variable FCGI_WEB_SERVER_ADDRS may be used to specify a coma separated list of IP addresses from which the web server can connect. If not set, any address is accepted.

val handle_requests : ?fork:((Request.t -> unit) -> Request.t -> unit) ->
       (Request.t -> unit) -> connection -> unit
handle_requests ?fork f conn listen on the connection conn for requests. For each completed request req, it executes fork f req.
fork : the function that starts a new process or thread. The default is to execute f and only after continue to listen for more requests.

Exceptions thrown by f are caught (so the possible thread executing f will not be terminated by these). The exception Exit is caught and ignored (this is considered a valid way of ending a script). CamlGI.Cgi.HttpError exceptions are turned into appropriate error codes. All other exceptions provoke a internal server error and are logged in the server error log.

Note that the exceptions raised by fork are NOT caught.

val register_script : ?sockaddr:Unix.sockaddr -> (Request.t -> unit) -> unit
Scripts must call register_script f once to register their main function f. This should be called last (nothing that follows will be executed). The data is buffered and may not be fully written before f ends.

This is actually a convenience function that sets up a server (with establish_server) and processes (through handle_requests) all connections and requests sequentially -- i.e. no fork/thread.


Cgi


class type template = object .. end
Type of acceptable template objects. 
exception Abort
Exception raised by all terminating cgi methods if the server requires to abort the request.

type upload_data = {
   upload_value : string;
   upload_filename : string;
   upload_content_type : string;
}
Type returned by cgi#upload method.
class cgi : Request.t -> object .. end
new cgi r creates a cgi object for the request r. 
val random_sessionid : unit -> string
Generates a 128 bit (32 hex digits) random string which can be used for session IDs, random cookies and so on. The string returned will be very random and hard to predict, at least if your platform possesses /dev/urandom
module Cgi_args: sig .. end

Apache names for HTTP errors


val cHTTP_CONTINUE : int
val cHTTP_SWITCHING_PROTOCOLS : int
val cHTTP_PROCESSING : int
val cHTTP_OK : int
val cHTTP_CREATED : int
val cHTTP_ACCEPTED : int
val cHTTP_NON_AUTHORITATIVE : int
val cHTTP_NO_CONTENT : int
val cHTTP_RESET_CONTENT : int
val cHTTP_PARTIAL_CONTENT : int
val cHTTP_MULTI_STATUS : int
val cHTTP_MULTIPLE_CHOICES : int
val cHTTP_MOVED_PERMANENTLY : int
val cHTTP_MOVED_TEMPORARILY : int
val cHTTP_SEE_OTHER : int
val cHTTP_NOT_MODIFIED : int
val cHTTP_USE_PROXY : int
val cHTTP_TEMPORARY_REDIRECT : int
val cHTTP_BAD_REQUEST : int
val cHTTP_UNAUTHORIZED : int
val cHTTP_PAYMENT_REQUIRED : int
val cHTTP_FORBIDDEN : int
val cHTTP_NOT_FOUND : int
val cHTTP_METHOD_NOT_ALLOWED : int
val cHTTP_NOT_ACCEPTABLE : int
val cHTTP_PROXY_AUTHENTICATION_REQUIRED : int
val cHTTP_REQUEST_TIME_OUT : int
val cHTTP_CONFLICT : int
val cHTTP_GONE : int
val cHTTP_LENGTH_REQUIRED : int
val cHTTP_PRECONDITION_FAILED : int
val cHTTP_REQUEST_ENTITY_TOO_LARGE : int
val cHTTP_REQUEST_URI_TOO_LARGE : int
val cHTTP_UNSUPPORTED_MEDIA_TYPE : int
val cHTTP_RANGE_NOT_SATISFIABLE : int
val cHTTP_EXPECTATION_FAILED : int
val cHTTP_UNPROCESSABLE_ENTITY : int
val cHTTP_LOCKED : int
val cHTTP_FAILED_DEPENDENCY : int
val cHTTP_INTERNAL_SERVER_ERROR : int
val cHTTP_NOT_IMPLEMENTED : int
val cHTTP_BAD_GATEWAY : int
val cHTTP_SERVICE_UNAVAILABLE : int
val cHTTP_GATEWAY_TIME_OUT : int
val cHTTP_VERSION_NOT_SUPPORTED : int
val cHTTP_VARIANT_ALSO_VARIES : int
val cHTTP_INSUFFICIENT_STORAGE : int
val cHTTP_NOT_EXTENDED : int
val cDOCUMENT_FOLLOWS : int
val cPARTIAL_CONTENT : int
val cMULTIPLE_CHOICES : int
val cMOVED : int
val cREDIRECT : int
val cUSE_LOCAL_COPY : int
val cBAD_REQUEST : int
val cAUTH_REQUIRED : int
val cFORBIDDEN : int
val cNOT_FOUND : int
val cMETHOD_NOT_ALLOWED : int
val cNOT_ACCEPTABLE : int
val cLENGTH_REQUIRED : int
val cPRECONDITION_FAILED : int
val cSERVER_ERROR : int
val cNOT_IMPLEMENTED : int
val cBAD_GATEWAY : int
val cVARIANT_ALSO_VARIES : int