MAN page from Old RedHat 6.X perl-libwww-perl-5.47-6.i386.rpm

lib::HTTP::Request::Common

Section: User Contributed Perl Documentation (3)
Updated: libwww-perl-5.47
Index

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::Requestobjects. These functions are usually more convenient to use than thestandard HTTP::Request constructor for these common requests. Thefollowing functions are provided.

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

The GET() function returns a HTTP::Request object initialized with theGET method and the specified URL. Without additional arguments itis exactly equivalent to the following call

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

but is less cluttered. It also reads better when used together with theLWP::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 specifyingsome key/value pairs as optional arguments. For instance:

  $ua->request(GET 'http://www.sn.no',                   If_Match => 'foo',                   From     => 'gisleAATTaas.no',              );

A header key called `Content' is special and when seen the value willinitialize 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 functionalso takes a second optional array or hash reference parameter($form_ref). This argument can be used to pass key/value pairs forthe form content. By default we will initialize a request using theapplication/x-www-form-urlencoded content type. This means thatyou can emulate a HTML <form> POSTing like this:

  POST 'http://www.perl.org/survey.cgi',       [ name   => 'Gisle Aas',         email  => 'gisleAATTaas.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&gender=M&born=1964&perc=3%25

The POST method also supports the multipart/form-data content usedfor Form-based File Upload as specified in RFC 1867. You triggerthis content format by specifying a content type of 'form-data' asone of the request headers. If one of the values in the $form_ref isan array reference, then it is treated as a file part specificationwith 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. Theroutine will croak if the file can't be opened. Use an undef as $filevalue if you want to specify the content directly. The $filename isthe filename to report in the request. If this value is undefined,then the basename of the $file will be used. You can specify an emptystring as $filename if you don't want any filename in the request.

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

  POST 'http://www.perl.org/survey.cgi',       Content_Type => 'form-data',       Content      => [ name  => 'Gisle Aas',                         email => 'gisleAATTaas.no',                         gender => 'M',                         born   => '1964',                         init   => ["$ENV{HOME}/.profile"],                       ]

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

  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"    gisleAATTaas.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--

If you set the $DYNAMIC_FILE_UPLOAD variable (exportable) to some TRUEvalue, then you get back a request object with a subroutine closure asthe content attribute. This subroutine will read the content of anyfiles on demand and return it in suitable chunks. This allow you toupload arbitrary big files without using lots of memory. You can evenupload infinite files like /dev/audio if you wish. Anotherdifference is that there will be no Content-Length header defined forthe request if you use this feature. Not all servers (or serverapplications) like this.

COPYRIGHT

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

This document was created byman2html,using the manual pages.