# Check the outcome of the response  if ($res->is_success) {      print $res->content;  } else {      print "Bad luck this time\n";  }The $ua is created once when the application starts up.  New requestobjects should normally created for each request sent.=head1 NETWORK SUPPORTThis section discusses the various protocol schemes andthe HTTP style methods that headers may be used for each.For all requests, a "User-Agent" header is added and initialized fromthe $ua->agent attribute before the request is handed to the networklayer.  In the same way, a "From" header is initialized from the$ua->from attribute.For all responses, the library adds a header called "Client-Date".This header holds the time when the response was received byyour application.  The format and semantics of the header are thesame as the server created "Date" header.  You may also encounter other"Client-XXX" headers.  They are all generated by the libraryinternally and are not received from the servers.=head2 HTTP RequestsHTTP requests are just handed off to an HTTP server and itdecides what happens.  Few servers implement methods beside the usual"GET", "HEAD", "POST" and "PUT", but CGI-scripts may implementany method they like.If the server is not available then the library will generate aninternal error response.The library automatically adds a "Host" and a "Content-Length" headerto the HTTP request before it is sent over the network.For GET request you might want to add a "If-Modified-Since" or"If-None-Match" header to make the request conditional.For POST request you should add the "Content-Type" header.  When youtry to emulate HTML E<lt>FORM> handling you should usually let the valueof the "Content-Type" header be "application/x-www-form-urlencoded".See L<lwpcook> for examples of this.The libwww-perl HTTP implementation currently support the HTTP/1.1and HTTP/1.0 protocol.The library allows you to access proxy server through HTTP.  Thismeans that you can set up the library to forward all types of requestthrough the HTTP protocol module.  See L<LWP::UserAgent> fordocumentation of this.=head2 HTTPS RequestsHTTPS requests are HTTP requests over an encrypted network connectionusing the SSL protocol developed by Netscape.  Everything about HTTPrequests above also apply to HTTPS requests.  In addition the librarywill add the headers "Client-SSL-Cipher", "Client-SSL-Cert-Subject" and"Client-SSL-Cert-Issuer" to the response.  These headers denote theencryption method used and the name of the server owner.The request can contain the header "If-SSL-Cert-Subject" in order tomake the request conditional on the content of the server certificate.If the certificate subject does not match, no request is sent to theserver and an internally generated error response is returned.  Thevalue of the "If-SSL-Cert-Subject" header is interpreted as a Perlregular expression.=head2 FTP RequestsThe library currently supports GET, HEAD and PUT requests.  GETretrieves a file or a directory listing from an FTP server.  PUTstores a file on a ftp server.You can specify a ftp account for servers that want this in additionto user name and password.  This is specified by including an "Account"header in the request.User name/password can be specified using basic authorization or beencoded in the URL.  Failed logins return an UNAUTHORIZED response with"WWW-Authenticate: Basic" and can be treated like basic authorizationfor HTTP.The library supports ftp ASCII transfer mode by specifying the "type=a"parameter in the URL. It also supports transfer of ranges for FTP transfersusing the "Range" header.Directory listings are by default returned unprocessed (as returnedfrom the ftp server) with the content media type reported to be"text/ftp-dir-listing". The C<File::Listing> module provides methodsfor parsing of these directory listing.The ftp module is also able to convert directory listings to HTML andthis can be requested via the standard HTTP content negotiationmechanisms (add an "Accept: text/html" header in the request if youwant this).For normal file retrievals, the "Content-Type" is guessed based on thefile name suffix. See L<LWP::MediaTypes>.The "If-Modified-Since" request header works for servers that implementthe MDTM command.  It will probably not work for directory listings though.Example:  $req = HTTP::Request->new(GET => 'ftp://me:passwd@ftp.some.where.com/');  $req->header(Accept => "text/html, */*;q=0.1");=head2 News RequestsAccess to the USENET News system is implemented through the NNTPprotocol.  The name of the news server is obtained from theNNTP_SERVER environment variable and defaults to "news".  It is notpossible to specify the hostname of the NNTP server in news: URLs.The library supports GET and HEAD to retrieve news articles through theNNTP protocol.  You can also post articles to newsgroups by using(surprise!) the POST method.GET on newsgroups is not implemented yet.Examples:  $req = HTTP::Request->new(GET => 'news:abc1234@a.sn.no');  $req = HTTP::Request->new(POST => 'news:comp.lang.perl.test');  $req->header(Subject => 'This is a test',               From    => 'me@some.where.org');  $req->content(<<EOT);  This is the content of the message that we are sending to  the world.  EOT=head2 Gopher RequestThe library supports the GET and HEAD methods for gopher requests.  Allrequest header values are ignored.  HEAD cheats and returns aresponse without even talking to server.Gopher menus are always converted to HTML.The response "Content-Type" is generated from the document typeencoded (as the first letter) in the request URL path itself.Example:  $req = HTTP::Request->new(GET => 'gopher://gopher.sn.no/');=head2 File RequestThe library supports GET and HEAD methods for file requests.  The"If-Modified-Since" header is supported.  All other headers areignored.  The I<host> component of the file URL must be empty or setto "localhost".  Any other I<host> value will be treated as an error.Directories are always converted to an HTML document.  For normalfiles, the "Content-Type" and "Content-Encoding" in the response areguessed based on the file suffix.Example:  $req = HTTP::Request->new(GET => 'file:/etc/passwd');=head2 Mailto RequestYou can send (aka "POST") mail messages using the library.  Allheaders specified for the request are passed on to the mail system.The "To" header is initialized from the mail address in the URL.Example:  $req = HTTP::Request->new(POST => 'mailto:libwww@perl.org');  $req->header(Subject => "subscribe");  $req->content("Please subscribe me to the libwww-perl mailing list!\n");=head1 OVERVIEW OF CLASSES AND PACKAGESThis table should give you a quick overview of the classes provided by thelibrary. Indentation shows class inheritance. LWP::MemberMixin   -- Access to member variables of Perl5 classes   LWP::UserAgent   -- WWW user agent class     LWP::RobotUA   -- When developing a robot applications   LWP::Protocol          -- Interface to various protocol schemes     LWP::Protocol::http  -- http:// access     LWP::Protocol::file  -- file:// access     LWP::Protocol::ftp   -- ftp:// access     ... LWP::Authen::Basic -- Handle 401 and 407 responses LWP::Authen::Digest HTTP::Headers      -- MIME/RFC822 style header (used by HTTP::Message) HTTP::Message      -- HTTP style message   HTTP::Request    -- HTTP request   HTTP::Response   -- HTTP response HTTP::Daemon       -- A HTTP server class WWW::RobotRules    -- Parse robots.txt files   WWW::RobotRules::AnyDBM_File -- Persistent RobotRules Net::HTTP          -- Low level HTTP clientThe following modules provide various functions and definitions. LWP                -- This file.  Library version number and documentation. LWP::MediaTypes    -- MIME types configuration (text/html etc.) LWP::Debug         -- Debug logging module LWP::Simple        -- Simplified procedural interface for common functions HTTP::Status       -- HTTP status code (200 OK etc) HTTP::Date         -- Date parsing module for HTTP date formats HTTP::Negotiate    -- HTTP content negotiation calculation File::Listing      -- Parse directory listings HTML::Form         -- Processing for <form>s in HTML documents=head1 MORE DOCUMENTATIONAll modules contain detailed information on the interfaces theyprovide.  The I<lwpcook> manpage is the libwww-perl cookbook that containexamples of typical usage of the library.  You might want to take alook at how the scripts C<lwp-request>, C<lwp-rget> and C<lwp-mirror>are implemented.=head1 ENVIRONMENTThe following environment variables are used by LWP:=over=item HOMEThe C<LWP::MediaTypes> functions will look for the F<.media.types> andF<.mime.types> files relative to you home directory.=item http_proxy=item ftp_proxy=item xxx_proxy=item no_proxyThese environment variables can be set to enable communication througha proxy server.  See the description of the C<env_proxy> method inL<LWP::UserAgent>.=item PERL_LWP_USE_HTTP_10Enable the old HTTP/1.0 protocol driver instead of the new HTTP/1.1driver.  You might want to set this to a TRUE value if you discoverthat your old LWP applications fails after you installed LWP-5.60 orbetter.=item PERL_HTTP_URI_CLASSUsed to decide what URI objects to instantiate.  The default is C<URI>.You might want to set it to C<URI::URL> for compatiblity with old times.=back=head1 BUGSThe library can not handle multiple simultaneous requests yet.  Also,check out what's left in the TODO file.=head1 ACKNOWLEDGEMENTSThis package owes a lot in motivation, design, and code, to thelibwww-perl library for Perl 4, maintained by Roy FieldingE<lt>fielding@ics.uci.edu>.That package used work from Alberto Accomazzi, James Casey, BrooksCutter, Martijn Koster, Oscar Nierstrasz, Mel Melchner, Gertjan vanOosten, Jared Rhine, Jack Shirazi, Gene Spafford, Marc VanHeyningen,Steven E. Brenner, Marion Hakanson, Waldemar Kebsch, Tony Sanders, andLarry Wall; see the libwww-perl-0.40 library for details.The primary architect for this Perl 5 library is Martijn Koster andGisle Aas, with lots of help from Graham Barr, Tim Bunce, AndreasKoenig, Jared Rhine, and Jack Shirazi.=head1 COPYRIGHT  Copyright 1995-2001, Gisle Aas  Copyright 1995, Martijn KosterThis library is free software; you can redistribute it and/ormodify it under the same terms as Perl itself.=head1 AVAILABILITYThe latest version of this library is likely to be available from CPANas well as: http://www.linpro.no/lwp/The best place to discuss this code is on the <libwww@perl.org>mailing list.=cut