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 than the standard HTTP::Request constructor for these common requests. The following functions are provided.

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

The GET() function returns a HTTP::Request object initialized 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 clutter. 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 the header values in the request by specifying some key/value pairs as optional arguments. 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 method, but this function also takes a second optional array reference parameter ($form_ref). This argument 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',
         email => 'gisle@aas.no',
         gender => 'm',
         born   => '1964',
         trust  => '3%',
	];

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

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

name=Gisle&email=gisle%40aas.no&gender=m&born=1964&trust=3%25

The POST method also supports the multipart/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'. 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 values:

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

The first value in the array ($file) is the name of a file to open. This file will be read an 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}/.profile"],
                     ]

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"; filename=".profile"
Content-Type: text/plain

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

--6G+f--

SEE ALSO

HTTP::Request, LWP::UserAgent

COPYRIGHT

Copyright 1997, Gisle Aas

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