NAME

CatalystX::ASP::Request - $Request Object

SYNOPSIS

use CatalystX::ASP::Request;

my $req = CatalystX::ASP::Request->new(asp => $asp);
my $session_cookie = $req->Cookies('session');
my $host = $req->ServerVariables('HTTP_HOST');

DESCRIPTION

The request object manages the input from the client browser, like posts, query strings, cookies, etc. Normal return results are values if an index is specified, or a collection / perl hash ref if no index is specified. WARNING: the latter property is not supported in ActiveState PerlScript, so if you use the hashes returned by such a technique, it will not be portable.

A normal use of this feature would be to iterate through the form variables in the form hash...

$form = $Request->Form();
for(keys %{$form}) {
  $Response->Write("$_: $form->{$_}<br>\n");
}

Note that if a form POST or query string contains duplicate values for a key, those values will be returned through normal use of the $Request object:

@values = $Request->Form('key');

but you can also access the internal storage, which is an array reference like so:

$array_ref = $Request->{Form}{'key'};
@values = @{$array_ref};

Please read the PERLSCRIPT section for more information on how things like $Request->QueryString() & $Request->Form() behave as collections.

ATTRIBUTES

$Request->{Method}

API extension. Returns the client HTTP request method, as in GET or POST. Added in version 2.31.

$Request->{TotalBytes}

The amount of data sent by the client in the body of the request, usually the length of the form data. This is the same value as $Request->ServerVariables('CONTENT_LENGTH')

METHODS

$Request->BinaryRead([$length])

Returns a string whose contents are the first $length bytes of the form data, or body, sent by the client request. If $length is not given, will return all of the form data. This data is the raw data sent by the client, without any parsing done on it by CatalystX::ASP.

Note that BinaryRead will not return any data for file uploads. Please see the $Request->FileUpload() interface for access to this data. $Request->Form() data will also be available as normal.

$Request->ClientCertificate()

Not implemented.

$Request->Cookies($name [,$key])

Returns the value of the Cookie with name $name. If a $key is specified, then a lookup will be done on the cookie as if it were a query string. So, a cookie set by:

Set-Cookie: test=data1=1&data2=2

would have a value of 2 returned by $Request->Cookies('test','data2').

If no name is specified, a hash will be returned of cookie names as keys and cookie values as values. If the cookie value is a query string, it will automatically be parsed, and the value will be a hash reference to these values.

When in doubt, try it out. Remember that unless you set the Expires attribute of a cookie with $Response->Cookies('cookie', 'Expires', $xyz), the cookies that you set will only last until you close your browser, so you may find your self opening & closing your browser a lot when debugging cookies.

For more information on cookies in ASP, please read $Response->Cookies()

$Request->FileUpload($form_field, $key)

API extension. The FileUpload interface to file upload data is stabilized. The internal representation of the file uploads is a hash of hashes, one hash per file upload found in the $Request->Form() collection. This collection of collections may be queried through the normal interface like so:

$Request->FileUpload('upload_file', 'ContentType');
$Request->FileUpload('upload_file', 'FileHandle');
$Request->FileUpload('upload_file', 'BrowserFile');
$Request->FileUpload('upload_file', 'Mime-Header');
$Request->FileUpload('upload_file', 'TempFile');

* note that TempFile must be use with the UploadTempFile configuration setting.

The above represents the old slow collection interface, but like all collections in CatalystX::ASP, you can reference the internal hash representation more easily.

my $fileup = $Request->{FileUpload}{upload_file};
$fileup->{ContentType};
$fileup->{BrowserFile};
$fileup->{FileHandle};
$fileup->{Mime-Header};
$fileup->{TempFile};

$Request->Form($name)

Returns the value of the input of name $name used in a form with POST method. If $name is not specified, returns a ref to a hash of all the form data. One can use this hash to create a nice alias to the form data like:

# in global.asa
use vars qw( $Form );
sub Script_OnStart {
  $Form = $Request->Form;
}
# then in ASP scripts
<%= $Form->{var} %>

File upload data will be loaded into $Request->Form('file_field'), where the value is the actual file name of the file uploaded, and the contents of the file can be found by reading from the file name as a file handle as in:

while(read($Request->Form('file_field_name'), $data, 1024)) {};

For more information, please see the CGI / File Upload section, as file uploads are implemented via the CGI.pm module.

$Request->Params($name)

API extension. If RequestParams CONFIG is set, the $Request->Params object is created with combined contents of $Request->QueryString and $Request->Form. This is for developer convenience simlar to CGI.pm's param() method. Just like for $Response->Form, one could create a nice alias like:

# in global.asa
use vars qw( $Params );
sub Script_OnStart {
  $Params = $Request->Params;
}

$Request->QueryString($name)

Returns the value of the input of name $name used in a form with GET method, or passed by appending a query string to the end of a url as in http://localhost/?data=value. If $name is not specified, returns a ref to a hash of all the query string data.

$Request->ServerVariables($name)

Returns the value of the server variable / environment variable with name $name. If $name is not specified, returns a ref to a hash of all the server / environment variables data. The following would be a common use of this method:

$env = $Request->ServerVariables();
# %{$env} here would be equivalent to the cgi %ENV in perl.

SEE ALSO

CatalystX::ASP::Session, CatalystX::ASP::Response, CatalystX::ASP::Application, CatalystX::ASP::Server