---+ Package ==

%TOC%
---+!! package TWiki::Request

Class to encapsulate request data.

Fields:
   * =action= action requested (view, edit, save, ...)
   * =body_param= hashref whose keys are parameter names
                  passed in request body
   * =cookies= hashref whose keys are cookie names and values
               are CGI::Cookie objects
   * =headers= hashref whose keys are header name
   * =method= request method (GET, HEAD, POST)
   * =param= hashref of parameters, both query and body ones
   * =path_info= path_info of request (eg. /WebName/TopciName)
   * =query_param= hashref whose keys are parameter names
                   passed in query_string
   * =remote_address= Client's IP address
   * =remote_port= Client's port
   * =remote_user= Remote HTTP authenticated user
   * =secure= Boolean value about use of encryption
   * =server_port=
   * =uploads= hashref whose keys are parameter name of uploaded
               files
   * =uri= the request uri


---++ ClassMethod *new* <tt>([$initializer])</tt>

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 and there's
        no way to distinguish between query and body ones.
      * It can be a hashref whose keys are parameter names. Values may be 
        arrayref's to multivalued parameters. Same note as above.



---++ ObjectMethod *action* <tt>() -> $action</tt>

Gets/Sets action requested (view, edit, save, ...)



---++ ObjectMethod *method* <tt>([$method]) -> $method</tt>

Sets/Gets request method (GET, HEAD, POST).



---++ ObjectMethod *pathInfo* <tt>([$path]) -> $path</tt>

Sets/Gets request path info. Implicitly sets request action.

Called with '/view/WebName/TopicName' sets request action to 'view' and
pathInfo to '/WebName/TopicName'. Called without parameters returns
current pathInfo.

There is a =path_info()= alias for compatibility with CGI.



---++ ObjectMethod *protocol* <tt>() -> $protocol</tt>

Returns 'https' if secure connection. 'http' otherwise.



---++ ObjectMethod *uri* <tt>([$uri]) -> $uri</tt>

Gets/Sets request uri.



---++ ObjectMethod *queryString* <tt>() -> $query_string</tt>

Returns query_string part of request uri, if any.

=query_string()= alias provided for compatibility with CGI.



---++ ObjectMethod *url* <tt>([-full=>1,</tt>
                         -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/Codev/WebHome?raw=on
   * -relative => 1 returns relative action path, e.g. view
   * -path => 1, -query => 1 also includes path info and query string
     respectively

Resonabily compatible with CGI corresponding method. Currently support
neither -absolute nor -rewrite.



---++ ObjectMethod *secure* <tt>([$secure]) -> $secure</tt>

Gets/Sets connection's secure flag.



---++ ObjectMethod *remoteAddress* <tt>([$ip]) -> $ip</tt>

Gets/Sets client IP address.

=remote_addr()= alias for compatibility with CGI.



---++ ObjectMethod *remotePort* <tt>([$port]) -> $port</tt>

Gets/sets client port.



---++ ObjectMethod *remoteUser* <tt>([$userName]) -> $userName</tt>

Gets/Sets remote user's name.

=remote_user()= alias for compatibility with CGI.



---++ ObjectMethod *queryParam* <tt>([-name=>$name,-value=>$value|</tt>
                                -name => $name, -values => [ $v1, $v2, ... ] |
                                $name, $v1, $v2, ...                         |
                                name, [ $v1, $v2, ... ]                     
                               ] ) -> @paramNames | @values | $firstValue

   * Called without parameters returns all query parameter names
   * Called only with parameter name or with -name => 'name'
      * In list context returns all values associated (maybe empity 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

This method is about parameters passed in query string.



---++ ObjectMethod *bodyParam* <tt>(...) -> ...</tt>

Analogous to queryParam above, but it's about parameters passed 
within request body



---++ ObjectMethod *param* <tt>(...) -> ...</tt>

Analogous to both queryParam and bodyParam, except it doesn't
distinguish between query and body parameters.

Resonably compatible with CGI.



---++ ObjectMethod *cookie* <tt>($name[,$value,$path,$secure,$expires]) -> $value</tt>

   * 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* <tt>($paramName)</tt>

Deletes parameter name and value(s) from request.

=Delete()= alias provided for compatibility with CGI



---++ ObjectMethod *deleteAll* <tt>()</tt>

Deletes all parameter name and value(s).

=delete_all()= alias provided for compatibility with CGI.



---++ ObjectMethod *header* <tt>([$name|$h1=>$v1,$h2=>$v2]) -> @values</tt>

Gets/Sets header field. If called without parametes returns
all present header field names. Multivalued header can be set
by passing an arrayref to values.

If called with only =$name= parameter, returns values associated.

Can be called with a hash to set multiple headers.

*Doesn't 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* <tt>($fh)</tt>

Saves object state to filehandle. Object may be loaded latter
passing $fh to new constructor.



---++ ObjectMethod *upload* <tt>($name) -> $handle</tt>

Called with file name parameter returns an open filehandle
to uploaded file.



---++ ObjectMethod *uploadInfo* <tt>() -> $headers</tt>

Returns a hashref to information about uploaded 
files as sent by browser.



---++ ObjectMethod *tmpFileName* <tt>($fname) -> $tmpFileName</tt>

Returns the name of temporarly created file to store uploaded $fname.

$fname may be obtained by calling =param()= with form field name.



---++ ObjectMethod *uploads* <tt>([\%uploads]) -> $hashref</tt>

Gets/Sets request uploads field. Keys are uploaded file names,
as sent by browser, and values are TWiki::Request::Upload objects.



---++ ObjectMethod *http* <tt>([$header]) -> $valueDEPRECATED</tt>

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* <tt>([$name]) -> $value||$secureDEPRECATED</tt>

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* <tt>() -> $userAgent;</tt>

Convenience method to get User-Agent string.

=user_agent()= alias provided for compatibility with CGI.



---++ ObjectMethod *referer* <tt>()</tt>

Convenience method to get Referer uri.


