RequestID

The request information object contains all request-local information and server as the vessel for most forms of intercommunication between modules, scripts, RXML and so on. It gets passed round to almost all API callbacks worth mentioning. A RequestID object is born when an incoming request is encountered, and its life expectancy is short, as it dies again when the request has passed through all levels of the module type calling sequence.

Note!

There are actually different request information objects for different protocols. To the programmer they try to look the same, but some slight differences might show up.

These are the member variables and methods of the RequestID object:

Protocol port_obj;

The port object this request came from.

int time;

Time of the request, standard unix time (seconds since the epoch; 1970).

string raw_url;

The nonparsed, nontouched, non-* URL requested by the client. Hence, this path is unlike not_query and virtfile not relative to the server URL and must be used in conjunction with the former to generate absolute paths within the server. Be aware that this string will contain any URL variables present in the request as well as the file path.

int do_not_disconnect;

Typically 0, meaning the channel to the client will be disconnected upon finishing the request and the RequestID object destroyed with it.

mapping(string:string) variables;

Form variables submitted by the client browser, as found in the form scope in RXML. Both query (as found in the query part of the URL) and POST (submitted in the request body) variables share this scope, with query variables having priority over POST ones. In other words, the query part of the URL overrides whatever variables are sent in the request body.

The indices and values of this mapping map to the names and values of the variable names. All data (names and values) are decoded from their possible transport encoding.

mapping(string:mixed) misc;

This mapping contains miscellaneous non-standardized information, and is the typical location to store away your own request-local data for passing between modules et cetera. Be sure to use a key unique to your own application.

mapping(string:string) cookies;

The indices and values map to the names and values of the cookies sent by the client for the requested page. All data (names and values) are decoded from their possible transport encoding.

mapping(string:string) request_headers;

Indices and values map to the names and values of all HTTP headers sent with the request; all data has been transport decoded, and the header names are canonized (lowercased) on top of that. Here is where you look for the "user-agent" header, the "referer" [sic!] header and similar interesting data provided by the client.

mapping(string:mixed) client_var;

The client scope; a mapping of various client-related variables, indices being the entity names and the values being their values respectively.

multiset(string) prestate;

A multiset of all prestates harvested from the URL. Prestates are boolean flags, who are introduced in an extra leading path segment of the URL path put within parentheses, as in http://docs.roxen.com/(tables)/, this rendering a prestate multiset (< "tables" >).

Prestates are mostly useful for debugging purposes, since prestates generally lead to multiple URLs for identical documents resulting in poor usage of browser/proxy caches and the like. See config.

multiset(string) config;

Much like prestates, the id->config multiset is typically used for boolean information of state supplied by the client. The config state, however, is hidden in a client-side cookie treated specially by roxen, namely the RoxenConfig cookie.

multiset(string) supports;

All flags set by the supports system.

multiset(string) pragma;

All pragmas (lower-cased for canonization) sent with the request. For real-world applications typically only pragma["no-cache"] is of any particular interest, this being sent when the user does a forced reload of the page.

string prot;

The protocol used for the request, e g "FTP", "HTTP/1.0", "HTTP/1.1". (Se also clientprot.)

string clientprot;

The protocol the client wanted to use in the request. This may not be the same as prot, if the client wanted to talk a higher protocol version than the server supports to date.

string method;

The method used by the client in this request, e g "GET", "POST".

string realfile;

When the the requested resource is an actual file in the real filesystem, this is its path.

string virtfile;

The mountpoint of the location module that provided the requested file.

Note!

This is not accessable from location modules; you need to keep track of your mountpoint on your own using defvar() and query(). This mountpoint is relative to the server URL.

string rest_query;

The scraps and leftovers of the requested URL's query part after removing all variables (that is, all key=value pairs) from it.

string raw;

The raw, untouched request in its entirety.

string query;

The entire raw query part (all characters after the first question mark, '?') of the requested URL.

string not_query;

The part of the path segment of the requested URL that is below the virtual server's mountpoint. For a typical server registering a URL with no ending path component, not_query will contain all characters from the leading '/' to, but not including, the first question mark ('?') of the URL.

string data;

The raw request body, containing non-decoded post variables et cetera.

string remoteaddr;

The client's IP address.

string host;

The client's hostname, if resolved.

Stdio.File connection()

Returns the file descriptor used for the connection to the client.

Configuration configuration()

Returns the Configuration object of the virtual server that is handling the request.