Syntax-K

Know-How für Ihr Projekt

Perl Documentation

NAME

LWP::UserAgent - Web user agent class

SYNOPSIS

require LWP::UserAgent;

my $ua = LWP::UserAgent->new;
$ua->timeout(10);
$ua->env_proxy;

my $response = $ua->get('http://search.cpan.org/');

if ($response->is_success) {
    print $response->decoded_content;  # or whatever
}
else {
    die $response->status_line;
}

DESCRIPTION

The LWP::UserAgent is a class implementing a web user agent. LWP::UserAgent objects can be used to dispatch web requests.

In normal use the application creates an LWP::UserAgent object, and then configures it with values for timeouts, proxies, name, etc. It then creates an instance of HTTP::Request for the request that needs to be performed. This request is then passed to one of the request method the UserAgent, which dispatches it using the relevant protocol, and returns a HTTP::Response object. There are convenience methods for sending the most common request types: get(), head(), post(), put() and delete(). When using these methods then the creation of the request object is hidden as shown in the synopsis above.

The basic approach of the library is to use HTTP style communication for all protocol schemes. This means that you will construct HTTP::Request objects and receive HTTP::Response objects even for non-HTTP resources like gopher and ftp. In order to achieve even more similarity to HTTP style communications, gopher menus and file directories are converted to HTML documents.

CONSTRUCTOR METHODS

The following constructor methods are available:

ATTRIBUTES

The settings of the configuration attributes modify the behaviour of the LWP::UserAgent when it dispatches requests. Most of these can also be initialized by options passed to the constructor method.

The following attribute methods are provided. The attribute value is left unchanged if no argument is given. The return value from each method is the old attribute value.

Proxy attributes

The following methods set up when requests should be passed via a proxy server.

Handlers

Handlers are code that injected at various phases during the processing of requests. The following methods are provided to manage the active handlers:

REQUEST METHODS

The methods described in this section are used to dispatch requests via the user agent. The following request methods are provided:

Callback methods

The following methods will be invoked as requests are processed. These methods are documented here because subclasses of LWP::UserAgent might want to override their behaviour.

SEE ALSO

See LWP for a complete overview of libwww-perl5. See lwpcook and the scripts lwp-request and lwp-download for examples of usage.

See HTTP::Request and HTTP::Response for a description of the message objects dispatched and received. See HTTP::Request::Common and HTML::Form for other ways to build request objects.

See WWW::Mechanize and WWW::Search for examples of more specialized user agents based on LWP::UserAgent.

COPYRIGHT

Copyright 1995-2009 Gisle Aas.

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