http::request::common(3)

NAME

HTTP::Request::Common - Construct common HTTP::Request
objects

SYNOPSIS

use HTTP::Request::Common;
$ua = LWP::UserAgent->new;
$ua->request(GET 'http://www.sn.no/');
$ua->request(POST 'http://somewhere/foo', [foo  =>  bar,
bar => foo]);

DESCRIPTION

This module provide functions that return newly created
HTTP::Request objects. These functions are usually more
convenient to use than the standard HTTP::Request con
structor for these common requests. The following func
tions are provided.

GET $url, Header => Value,...

The GET() function returns a HTTP::Request object ini
tialized with the GET method and the specified URL.
Without additional arguments it is exactly equivalent
to the following call

HTTP::Request->new(GET => $url)

but is less cluttered. It also reads better when used
together with the LWP::UserAgent->request() method:

my $ua = new LWP::UserAgent;
my $res = $ua->request(GET 'http://www.sn.no')
if ($res->is_success) { ...

You can also initialize header values in the request
by specifying some key/value pairs as optional argu
ments. For instance:

$ua->request(GET 'http://www.sn.no',

If_Match => 'foo',
From => 'gisle@aas.no',

);

A header key called 'Content' is special and when seen
the value will initialize the content part of the
request instead of setting a header.

HEAD $url, [Header => Value,...]

Like GET() but the method in the request is HEAD.

PUT $url, [Header => Value,...]

Like GET() but the method in the request is PUT.

POST $url, [$form_ref], [Header => Value,...]

This works mostly like GET() with POST as the method,
but this function also takes a second optional array
or hash reference parameter ($form_ref). This argu
ment can be used to pass key/value pairs for the form
content. By default we will initialize a request
using the "application/x-www-form-urlencoded" content
type. This means that you can emulate a HTML <form>
POSTing like this:

POST 'http://www.perl.org/survey.cgi',

[ name => 'Gisle Aas',

email => 'gisle@aas.no',
gender => 'M',
born => '1964',
perc => '3%',

];

This will create a HTTP::Request object that looks
like this:

POST http://www.perl.org/survey.cgi
Content-Length: 66
Content-Type: application/x-www-form-urlencoded

name=Gisle%20Aas&email=gisle%40aas.no&gen

der=M&born=1964&perc=3%25

The POST method also supports the "multi
part/form-data" content used for Form-based File Upload as specified in RFC 1867. You trigger this
content format by specifying a content type of
'form-data' as one of the request headers. If one of
the values in the $form_ref is an array reference,
then it is treated as a file part specification with
the following interpretation:

[ $file, $filename, Header => Value... ]

The first value in the array ($file) is the name of a
file to open. This file will be read and its content
placed in the request. The routine will croak if the
file can't be opened. Use an "undef" as $file value
if you want to specify the content directly. The
$filename is the filename to report in the request.
If this value is undefined, then the basename of the
$file will be used. You can specify an empty string
as $filename if you don't want any filename in the
request.

Sending my ~/.profile to the survey used as example above can be achieved by this:

POST 'http://www.perl.org/survey.cgi',

Content_Type => 'form-data',
Content => [ name => 'Gisle Aas',

email => 'gisle@aas.no',
gender => 'M',
born => '1964',
init => ["$ENV{HOME}/.pro

file"],

]

This will create a HTTP::Request object that almost
looks this (the boundary and the content of your
~/.profile is likely to be different):

POST http://www.perl.org/survey.cgi
Content-Length: 388
Content-Type: multipart/form-data; boundary="6G+f"

--6G+f
Content-Disposition: form-data; name="name"

Gisle Aas
--6G+f
Content-Disposition: form-data; name="email"

gisle@aas.no
--6G+f
Content-Disposition: form-data; name="gender"

M
--6G+f
Content-Disposition: form-data; name="born"

1964
--6G+f
Content-Disposition: form-data; name="init"; file

name=".profile"
Content-Type: text/plain

PATH=/local/perl/bin:$PATH
export PATH

--6G+f-

If you set the $DYNAMIC_FILE_UPLOAD variable
(exportable) to some TRUE value, then you get back a
request object with a subroutine closure as the con
tent attribute. This subroutine will read the content
of any files on demand and return it in suitable
chunks. This allow you to upload arbitrary big files
without using lots of memory. You can even upload
infinite files like /dev/audio if you wish; however, if the file is not a plain file, there will be no Con
tent-Length header defined for the request. Not all
servers (or server applications) like this. Also, if
the file(s) change in size between the time the Con
tent-Length is calculated and the time that the last
chunk is delivered, the subroutine will "Croak".

SEE ALSO

HTTP::Request, LWP::UserAgent

COPYRIGHT

Copyright 1997-2000, Gisle Aas

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

libwww-perl-5.65 2001-01-05 HTTP::Request::Common(3)