NAME

Message::CGI::HTTP - An Object-Oriented HTTP CGI Interface


DESCRIPTION

The Message::CGI::HTTP module provides an object-oriented interface to handle input parameters (i.e. request) and output (i.e. response) of HTTP CGI scripts, as defined by CGI specification.

This module is part of manakai.


METHODS

$cgi = Message::CGI::HTTP->new;

Creates and returns a new instance of HTTP CGI interface object.

$value = $cgi->get_meta_variable ($name)

Returns the value of the meta-variable $name. The name specified by the $name SHOULD be a meta-variable name defined by a CGI specification, e.g. CONTENT_TYPE or HTTP_USER_AGENT. Otherwise, the result is implementation dependent. In an environment where meta-variables are supplied as envirnoment variables, specifying an environment variable that is not a meta-variable, such as PATH, results in the value of that environment variable. However, CGI scripts SHOULD NOT depend on such behavior.

This method might return undef when the meta-variable is not defined or is defined but its value is undef.

$list = $cgi->meta_variable_names;

Returns list of meta variables. Note that this list might contain other environmental variables than CGI meta variables, since they cannot distinglish unless we know what is CGI meta variable and what is not. Unfortunately, there is no complete list of CGI meta variables, whilst list of standarized meta variables is available.

NOTE: Some application might use an environmental variable named 'HTTP_HOME', which might make some confusion with CGI meta variable for HTTP 'Home:' header field. Fortunately, such name of HTTP header field is not intoroduced as far as I know.

This method returns a Message::DOM::DOMStringList.

$value = $cgi->get_parameter ($name);

Returns parameter value if any. Parameter value is set by query-string of Request-URI and/or entity-body value.

When multiple values with same parameter name is specified, the first one is returned in scalar context or an array reference of all values is returned in array context. (Note that query-string is "earlier" than entity-body.)

$keys = $cgi->parameter_names;

Returnes a list of parameter names provided.

This method returns a Message::DOM::DOMStringList.

$body = $cgi->entity_body;

Returns entity-body content if any.

$uri = $cgi->request_uri;

Returns Request-URI as a Message::URI::URIReference object.

Note that stringified value of returned value might not be same as the URI specified as the Request-URI of HTTP request or (possibly pseudo-) URI entered by the user, since no standarized way to get it is defined by HTTP and CGI/1.1 specifications.

$value = $cgi->path_info ([$new_value]);
$value = $cgi->remote_user ([$new_value]);

These methods reflect meta-variables with the same name (in uppercase).


TODO

multipart/form-data support


SEE ALSO

RFC 3875 (CGI/1.1) <http://tools.ietf.org/html/rfc3875>.


HISTORY

This module was originally developed as part of the SuikaWiki project <http://suika.fam.cx/~wakaba/wiki/sw/n/SuikaWiki> to implement the SuikaWiki CGI script and then transfered to the manakai project.

There is outdated draft specification of the DOM-like CGI scripting interface module <http://suika.fam.cx/gate/2005/sw/manakai/%E3%83%A1%E3%83%A2/2005-07-04>, although this module does not strictly conform to the specification.


AUTHOR

Wakaba <w@suika.fam.cx>


LICENSE

Copyright 2003-2010 Wakaba <w@suika.fam.cx>

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.