LWP::UserAgent

Requests over the network are performed with the LWP::UserAgent module. To create an LWP::UserAgent object, you would do:

$ua = new LWP::UserAgent;

The most useful method in this module is request( ), which contacts a server and returns the result of your query. Other methods in this module change the way request( ) behaves. You can change the timeout value, customize the value of the User-Agent header, or use a proxy server. Here's an overview of most of the useful methods:

$ua->request($request [, $subroutine [, $size]]): Performs a request for the resource specified by $request, which is an HTTP::Request object. Normally, doing a $result=$ua->request($request) is enough. On the other hand, if you want to request data as it becomes available, you can specify a reference to a subroutine as the second argument, and request( ) will call the subroutine whenever there are data to be processed. In that case, you can specify an optional third argument that specifies the desired size of the data to be processed. The subroutine should expect chunks of the entity-body data as a scalar as the first parameter, a reference to an HTTP::Response object as the second argument, and a reference to an LWP::Protocol object as the third argument.
$ua->request($request, $file_path): When invoked with a file path as the second parameter, this method writes the entity-body of the response to the file, instead of the HTTP::Response object that is returned. However, the HTTP::Response object can still be queried for its response code.
$ua->credentials($netloc, $realm, $uname, $pass): Use the supplied username and password for the given network location and realm. To use the username "webmaster" and password of "yourguess" with the "admin" realm at www.ora.com, you would do this:
$ua->credentials('www.ora.com', 'admin', 'webmaster', 'yourguess').
$ua->get_basic_credentials($realm, $url): Returns ($uname, $pass) for the given realm and URL. get_basic_credentials( ) is usually called by request( ). This method becomes useful when creating a subclass of LWP::UserAgent with its own version of get_basic_credentials( ). From there, you can rewrite get_basic_credentials( ) to do more flexible things, like asking the user for the account information, or referring to authentication information in a file, or whatever. All you need to do is return a list, where the first element is a username and the second element is a password.
$ua->agent([$product_id]): When invoked with no arguments, this method returns the current value of the identifier used in the User-Agent HTTP header. If invoked with an argument, the User-Agent header will use that identifier in the future. (As described in Chapter 3, the User-Agent header tells a web server what kind of client software is performing the request.)
$ua->from([$email_address]): When invoked with no arguments, this method returns the current value of the email address used in the From HTTP header. If invoked with an argument, the From header will use that email address in the future. (The From header tells the web server the email address of the person running the client software.)
$ua->timeout([$secs]): When invoked with no arguments, the timeout( ) method returns the timeout value of a request. By default, this value is three minutes. So if the client software doesn't hear back from the server within three minutes, it will stop the transaction and indicate that a timeout occurred in the HTTP response code. If invoked with an argument, the timeout value is redefined to be that value.
$ua->use_alarm([$boolean]): Retrieves or defines the ability to use alarm( ) for timeouts. By default, timeouts with alarm( ) are enabled. If you plan on using alarm( ) for your own purposes, or alarm( ) isn't supported on your system, it is recommended that you disable alarm( ) by calling this method with a value of 0 (zero).
$ua->is_protocol_supported($scheme): Given a scheme, this method returns a true or false (nonzero or zero) value. A true value means that LWP knows how to handle a URL with the specified scheme. If it returns a false value, LWP does not know how to handle the URL.
$ua->mirror($url, $file): Given a URL and file path, this method copies the contents of $url into the file when the length or modification date headers are different. If the file does not exist, it is created. This method returns an HTTP::Response object, where the response code indicates what happened.
$ua->proxy( (@scheme | $scheme), $proxy_url): Defines a URL to use with the specified schemes. The first parameter can be an array of scheme names or a scalar that defines a single scheme. The second argument defines the proxy's URL to use with the scheme.
$ua->env_proxy( ): Defines a scheme/proxy URL mapping by looking at environment variables. For example, to define the HTTP proxy, one would define the http_proxy environment variable with the proxy's URL. To define a domain to avoid the proxy, one would define the no_proxy environment variable with the domain that doesn't need a proxy.
$ua->timeout([$secs]): When invoked with no arguments, the timeout( ) method returns the timeout value of a request. By default, this value is three minutes. So if the client software doesn't hear back from the server within three minutes, it will stop the transaction and indicate that a timeout occurred in the HTTP response code. If invoked with an argument, the timeout value is redefined to be that value.
$ua->use_alarm([$boolean]): Retrieves or defines the ability to use alarm( ) for timeouts. By default, timeouts with alarm( ) are enabled. If you plan on using alarm( ) for your own purposes, or alarm( ) isn't supported on your system, it is recommended that you disable alarm( ) by calling this method with a value of 0 (zero).
$ua->is_protocol_supported($scheme): Given a scheme, this method returns a true or false (nonzero or zero) value. A true value means that LWP knows how to handle a URL with the specified scheme. If it returns a false value, LWP does not know how to handle the URL.
$ua->mirror($url, $file): Given a URL and file path, this method copies the contents of $url into the file when the length or modification date headers are different. If the file does not exist, it is created. This method returns an HTTP::Response object, where the response code indicates what happened.
$ua->proxy( (@scheme | $scheme), $proxy_url): Defines a URL to use with the specified schemes. The first parameter can be an array of scheme names or a scalar that defines a single scheme. The second argument defines the proxy's URL to use with the scheme.
$ua->env_proxy( ): Defines a scheme/proxy URL mapping by looking at environment variables. For example, to define the HTTP proxy, one would define the http_proxy environment variable with the proxy's URL. To define a domain to avoid the proxy, one would define the no_proxy environment variable with the domain that doesn't need a proxy.
$ua->no_proxy($domain,...): Do not use a proxy server for the domains given as parameters.

By: Jeff Sheffield