---+ Package =TWiki::Request=
Class to encapsulate request data.
Fields:
* =action= action requested (view, edit, save, ...)
* =cookies= hashref whose keys are cookie names and values
are CGI::Cookie objects
* =headers= hashref whose keys are header name
* =request_method= request method (GET, HEAD, POST)
* =param= hashref of parameters, both query and body ones
* =param_list= arrayref with parameter names in received order
* =path_info= path_info of request (eg. /WebName/TopciName)
* =remote_address= Client's IP address
* =remote_user= Remote HTTP authenticated user
* =secure= Boolean value about use of encryption
* =server_port= Port that the webserver listens on
* =uploads= hashref whose keys are parameter name of uploaded
files
* =uri= the request uri
%TOC%
---++ ClassMethod *new* ([$initializer])
Constructs a TWiki::Request object.
* =$initializer= - may be a filehandle or hashref.
* If it's a filehandle, it'll be used to reload the TWiki::Request
object. See =save= method. Note: Restore only parameters
* It can be a hashref whose keys are parameter names. Values may be
arrayref's to multivalued parameters. Same note as above.
---++ ObjectMethod *action* () -> $action
Gets/Sets action requested (view, edit, save, ...)
---++ ObjectMethod *method* ([$method]) -> $method
DEPRECATED. Sets/Gets request method (GET, HEAD, POST). Same as request_method() method.
---++ ObjectMethod *request_method* ([$method]) -> $method
Sets/Gets request method (GET, HEAD, POST).
---++ ObjectMethod *pathInfo* ([$path]) -> $path
Sets/Gets request path info.
Called without parameters returns current pathInfo.
There is a =path_info()= alias for compatibility with CGI.
---++ ObjectMethod *protocol* () -> $protocol
Returns 'https' if secure connection. 'http' otherwise.
---++ ObjectMethod *uri* ([$uri]) -> $uri
Gets/Sets request uri.
---++ ObjectMethod *queryString* () -> $query_string
Returns query_string part of request uri, if any.
=query_string()= alias provided for compatibility with CGI.
---++ ObjectMethod *url* ([-full=>1,
-base => 1,
-absolute => 1,
-relative => 1,
-path => 1,
-query => 1] ) -> $url
Returns many url info.
* If called without parameters or with -full => 1 returns full url, e.g.
http://twiki.org/cgi-bin/view
* If called with -base => 1 returns base url, e.g. http://twiki.org
* -absolute => 1 returns absolute action path, e.g. /cgi-bin/view
* -relative => 1 returns relative action path, e.g. view
* -path => 1, -query => 1 also includes path info and query string
respectively
Reasonably compatible with CGI corresponding method. Doesn't support
-rewrite. See Item5914.
---++ ObjectMethod *secure* ([$secure]) -> $secure
Gets/Sets connection's secure flag.
---++ ObjectMethod *remoteAddress* ([$ip]) -> $ip
Gets/Sets client IP address.
=remote_addr()= alias for compatibility with CGI.
---++ ObjectMethod *remoteUser* ([$userName]) -> $userName
Gets/Sets remote user's name.
=remote_user()= alias for compatibility with CGI.
---++ ObjectMethod *serverPort* ([$userName]) -> $userName
Gets/Sets server user's name.
=server_port()= alias for compatibility with CGI.
---++ ObjectMethod *queryParam* ([-name=>$name,-value=>$value|
-name => $name, -values => [ $v1, $v2, ... ] |
$name, $v1, $v2, ... |
name, [ $v1, $v2, ... ]
] ) -> @paramNames | @values | $firstValue
This methos is used by engines, during its prepare phase. Should not be used
anywhere else. Since bodyParam must exist and it has different semantics from
param method, this one exists for symmetry, and could be modified in the
future, so it could be possible to get query and body parameters independently.
---++ ObjectMethod *bodyParam* ([-name=>$name,-value=>$value|
-name => $name, -values => [ $v1, $v2, ... ] |
$name, $v1, $v2, ... |
name, [ $v1, $v2, ... ]
] ) -> @paramNames | @values | $firstValue
Adds parameters passed within request body. It keeps previous values,
but places new ones first. Should be called only by engines. Otherwise
use param() method.
---++ ObjectMethod *param* ([-name=>$name,-value=>$value|
-name => $name, -values => [ $v1, $v2, ... ] |
$name, $v1, $v2, ... |
name, [ $v1, $v2, ... ]
] ) -> @paramNames | @values | $firstValue
* Called without parameters returns all parameter names
* Called only with parameter name or with -name => 'name'
* In list context returns all associated values (maybe empty list)
* In scalar context returns first value (maybe undef)
* Called with name and list of values or with
-name => 'name', -value => 'value' or -name => 'name', -values => [ ... ]
sets parameter value
Resonably compatible with CGI.
---++ ObjectMethod *cookie* ($name[,$value,$path,$secure,$expires]) -> $value
* If called without parameters returns a list of cookie names.
* If called only with =$name= parameter returns value of cookie
with that name or undef if it doesn't exist.
* If called with defined $value and other parameters returns a
CGI::Cookie object created with those parameters. Doesn't
store this new created cookie within request object. This way
for compatibility with CGI.
ObjectMethod cookies( \%cookies ) -> $hashref
Gets/Sets cookies hashref. Keys are cookie names
and values CGI::Cookie objects.
---++ ObjectMethod *delete* (@paramNames)
Deletes parameters from request.
=Delete()= alias provided for compatibility with CGI
---++ ObjectMethod *deleteAll* ()
Deletes all parameter name and value(s).
=delete_all()= alias provided for compatibility with CGI.
---++ ObjectMethod *header* ([-name=>$name,-value=>$value|
-name => $name, -values => [ $v1, $v2, ... ] |
$name, $v1, $v2, ... |
name, [ $v1, $v2, ... ]
] ) -> @paramNames | @values | $firstValue
Gets/Sets a header field:
* Called without parameters returns all header field names
* Called only with header field name or with -name => 'name'
* In list context returns all associated values (maybe empty list)
* In scalar context returns the first value (maybe undef)
* Called with name and list of values or with
-name => 'name', -value => 'value' or -name => 'name', -values => [ ... ]
sets header field value
*Not compatible with CGI*, since CGI correspondent is a
response write method. CGI scripts obtain headers from %ENV
or =http= method. %ENV is not available and must be replaced
by calls to this and other methods of this class. =http= is
provided for compatibility, but is deprecated. Use this one
instead.
Calls to CGI =header= method must be replaced by calls to
TWiki::Response =header= method.
---++ ObjectMethod *save* ($fh)
Saves object state to filehandle. Object may be loaded latter
passing $fh to new constructor or by calling load().
---++ ObjectMethod *load* ($fh)
Loads object state from filehandle, probably created with
a previous save().
---++ ObjectMethod *upload* ($name) -> $handle
Called with file name parameter returns an open filehandle
to uploaded file.
* If called without parameters returns a list filenames, app trying to upload
---++ ObjectMethod *uploadInfo* ($fname) -> $headers
Returns a hashref to information about uploaded
files as sent by browser.
---++ ObjectMethod *tmpFileName* ($fname) -> $tmpFileName
Returns the name of temporarly created file to store uploaded $fname.
$fname may be obtained by calling =param()= with form field name.
---++ ObjectMethod *uploads* ([\%uploads]) -> $hashref
Gets/Sets request uploads field. Keys are uploaded file names,
as sent by browser, and values are TWiki::Request::Upload objects.
---++ ObjectMethod *http* ([$header]) -> $valueDEPRECATED
Called without parameters returns a list of all available header filed names.
Given a field name returns value associated.
http('HTTP_USER_AGENT'); http('User-Agent') and http('User_Agent')
are equivalent.
Please, use =header()= instead. Present only for compatibility with CGI.
---++ ObjectMethod *https* ([$name]) -> $value||$secureDEPRECATED
Similar to =http()= method above. Called with no parameters returns
secure flag.
Please, use =header()= and =secure()= instead.
Present only for compatibility with CGI.
---++ ObjectMethod *userAgent* () -> $userAgent;
Convenience method to get User-Agent string.
=user_agent()= alias provided for compatibility with CGI.
---++ ObjectMethod *referer* ()
Convenience method to get Referer uri.