1LWP::UserAgent(3)     User Contributed Perl Documentation    LWP::UserAgent(3)
2
3
4

NAME

6       LWP::UserAgent - Web user agent class
7

SYNOPSIS

9           use strict;
10           use warnings;
11
12           use LWP::UserAgent ();
13
14           my $ua = LWP::UserAgent->new(timeout => 10);
15           $ua->env_proxy;
16
17           my $response = $ua->get('http://example.com');
18
19           if ($response->is_success) {
20               print $response->decoded_content;
21           }
22           else {
23               die $response->status_line;
24           }
25
26       Extra layers of security (note the "cookie_jar" and
27       "protocols_allowed"):
28
29           use strict;
30           use warnings;
31
32           use HTTP::CookieJar::LWP ();
33           use LWP::UserAgent       ();
34
35           my $jar = HTTP::CookieJar::LWP->new;
36           my $ua  = LWP::UserAgent->new(
37               cookie_jar        => $jar,
38               protocols_allowed => ['http', 'https'],
39               timeout           => 10,
40           );
41
42           $ua->env_proxy;
43
44           my $response = $ua->get('http://example.com');
45
46           if ($response->is_success) {
47               print $response->decoded_content;
48           }
49           else {
50               die $response->status_line;
51           }
52

DESCRIPTION

54       The LWP::UserAgent is a class implementing a web user agent.
55       LWP::UserAgent objects can be used to dispatch web requests.
56
57       In normal use the application creates an LWP::UserAgent object, and
58       then configures it with values for timeouts, proxies, name, etc. It
59       then creates an instance of HTTP::Request for the request that needs to
60       be performed. This request is then passed to one of the request method
61       the UserAgent, which dispatches it using the relevant protocol, and
62       returns a HTTP::Response object.  There are convenience methods for
63       sending the most common request types: "get" in LWP::UserAgent, "head"
64       in LWP::UserAgent, "post" in LWP::UserAgent, "put" in LWP::UserAgent
65       and "delete" in LWP::UserAgent.  When using these methods, the creation
66       of the request object is hidden as shown in the synopsis above.
67
68       The basic approach of the library is to use HTTP-style communication
69       for all protocol schemes.  This means that you will construct
70       HTTP::Request objects and receive HTTP::Response objects even for non-
71       HTTP resources like gopher and ftp.  In order to achieve even more
72       similarity to HTTP-style communications, gopher menus and file
73       directories are converted to HTML documents.
74

CONSTRUCTOR METHODS

76       The following constructor methods are available:
77
78   clone
79           my $ua2 = $ua->clone;
80
81       Returns a copy of the LWP::UserAgent object.
82
83       CAVEAT: Please be aware that the clone method does not copy or clone
84       your "cookie_jar" attribute. Due to the limited restrictions on what
85       can be used for your cookie jar, there is no way to clone the
86       attribute. The "cookie_jar" attribute will be "undef" in the new object
87       instance.
88
89   new
90           my $ua = LWP::UserAgent->new( %options )
91
92       This method constructs a new LWP::UserAgent object and returns it.
93       Key/value pair arguments may be provided to set up the initial state.
94       The following options correspond to attribute methods described below:
95
96          KEY                     DEFAULT
97          -----------             --------------------
98          agent                   "libwww-perl/#.###"
99          from                    undef
100          conn_cache              undef
101          cookie_jar              undef
102          default_headers         HTTP::Headers->new
103          local_address           undef
104          ssl_opts                { verify_hostname => 1 }
105          max_size                undef
106          max_redirect            7
107          parse_head              1
108          protocols_allowed       undef
109          protocols_forbidden     undef
110          requests_redirectable   ['GET', 'HEAD']
111          timeout                 180
112          proxy                   undef
113          no_proxy                []
114
115       The following additional options are also accepted: If the "env_proxy"
116       option is passed in with a true value, then proxy settings are read
117       from environment variables (see "env_proxy" in LWP::UserAgent). If
118       "env_proxy" isn't provided, the "PERL_LWP_ENV_PROXY" environment
119       variable controls if "env_proxy" in LWP::UserAgent is called during
120       initialization.  If the "keep_alive" option is passed in, then a
121       "LWP::ConnCache" is set up (see "conn_cache" in LWP::UserAgent).  The
122       "keep_alive" value is passed on as the "total_capacity" for the
123       connection cache.
124
125       "proxy" must be set as an arrayref of key/value pairs. "no_proxy" takes
126       an arrayref of domains.
127

ATTRIBUTES

129       The settings of the configuration attributes modify the behaviour of
130       the LWP::UserAgent when it dispatches requests.  Most of these can also
131       be initialized by options passed to the constructor method.
132
133       The following attribute methods are provided.  The attribute value is
134       left unchanged if no argument is given.  The return value from each
135       method is the old attribute value.
136
137   agent
138           my $agent = $ua->agent;
139           $ua->agent('Checkbot/0.4 ');    # append the default to the end
140           $ua->agent('Mozilla/5.0');
141           $ua->agent("");                 # don't identify
142
143       Get/set the product token that is used to identify the user agent on
144       the network. The agent value is sent as the "User-Agent" header in the
145       requests.
146
147       The default is a string of the form "libwww-perl/#.###", where "#.###"
148       is substituted with the version number of this library.
149
150       If the provided string ends with space, the default "libwww-perl/#.###"
151       string is appended to it.
152
153       The user agent string should be one or more simple product identifiers
154       with an optional version number separated by the "/" character.
155
156   conn_cache
157           my $cache_obj = $ua->conn_cache;
158           $ua->conn_cache( $cache_obj );
159
160       Get/set the LWP::ConnCache object to use.  See LWP::ConnCache for
161       details.
162
163   cookie_jar
164           my $jar = $ua->cookie_jar;
165           $ua->cookie_jar( $cookie_jar_obj );
166
167       Get/set the cookie jar object to use.  The only requirement is that the
168       cookie jar object must implement the "extract_cookies($response)" and
169       "add_cookie_header($request)" methods.  These methods will then be
170       invoked by the user agent as requests are sent and responses are
171       received.  Normally this will be a HTTP::Cookies object or some
172       subclass.  You are, however, encouraged to use HTTP::CookieJar::LWP
173       instead.  See "BEST PRACTICES" for more information.
174
175           use HTTP::CookieJar::LWP ();
176
177           my $jar = HTTP::CookieJar::LWP->new;
178           my $ua = LWP::UserAgent->new( cookie_jar => $jar );
179
180           # or after object creation
181           $ua->cookie_jar( $cookie_jar );
182
183       The default is to have no cookie jar, i.e. never automatically add
184       "Cookie" headers to the requests.
185
186       Shortcut: If a reference to a plain hash is passed in, it is replaced
187       with an instance of HTTP::Cookies that is initialized based on the
188       hash. This form also automatically loads the HTTP::Cookies module.  It
189       means that:
190
191         $ua->cookie_jar({ file => "$ENV{HOME}/.cookies.txt" });
192
193       is really just a shortcut for:
194
195         require HTTP::Cookies;
196         $ua->cookie_jar(HTTP::Cookies->new(file => "$ENV{HOME}/.cookies.txt"));
197
198   credentials
199           my $creds = $ua->credentials();
200           $ua->credentials( $netloc, $realm );
201           $ua->credentials( $netloc, $realm, $uname, $pass );
202           $ua->credentials("www.example.com:80", "Some Realm", "foo", "secret");
203
204       Get/set the user name and password to be used for a realm.
205
206       The $netloc is a string of the form "<host>:<port>".  The username and
207       password will only be passed to this server.
208
209   default_header
210           $ua->default_header( $field );
211           $ua->default_header( $field => $value );
212           $ua->default_header('Accept-Encoding' => scalar HTTP::Message::decodable());
213           $ua->default_header('Accept-Language' => "no, en");
214
215       This is just a shortcut for "$ua->default_headers->header( $field =>
216       $value )".
217
218   default_headers
219           my $headers = $ua->default_headers;
220           $ua->default_headers( $headers_obj );
221
222       Get/set the headers object that will provide default header values for
223       any requests sent.  By default this will be an empty HTTP::Headers
224       object.
225
226   from
227           my $from = $ua->from;
228           $ua->from('foo@bar.com');
229
230       Get/set the email address for the human user who controls the
231       requesting user agent.  The address should be machine-usable, as
232       defined in RFC2822 <https://tools.ietf.org/html/rfc2822>. The "from"
233       value is sent as the "From" header in the requests.
234
235       The default is to not send a "From" header.  See "default_headers" in
236       LWP::UserAgent for the more general interface that allow any header to
237       be defaulted.
238
239   local_address
240           my $address = $ua->local_address;
241           $ua->local_address( $address );
242
243       Get/set the local interface to bind to for network connections.  The
244       interface can be specified as a hostname or an IP address.  This value
245       is passed as the "LocalAddr" argument to IO::Socket::INET.
246
247   max_redirect
248           my $max = $ua->max_redirect;
249           $ua->max_redirect( $n );
250
251       This reads or sets the object's limit of how many times it will obey
252       redirection responses in a given request cycle.
253
254       By default, the value is 7. This means that if you call "request" in
255       LWP::UserAgent and the response is a redirect elsewhere which is in
256       turn a redirect, and so on seven times, then LWP gives up after that
257       seventh request.
258
259   max_size
260           my $size = $ua->max_size;
261           $ua->max_size( $bytes );
262
263       Get/set the size limit for response content.  The default is "undef",
264       which means that there is no limit.  If the returned response content
265       is only partial, because the size limit was exceeded, then a
266       "Client-Aborted" header will be added to the response.  The content
267       might end up longer than "max_size" as we abort once appending a chunk
268       of data makes the length exceed the limit.  The "Content-Length"
269       header, if present, will indicate the length of the full content and
270       will normally not be the same as "length($res->content)".
271
272   parse_head
273           my $bool = $ua->parse_head;
274           $ua->parse_head( $boolean );
275
276       Get/set a value indicating whether we should initialize response
277       headers from the <head> section of HTML documents. The default is true.
278       Do not turn this off unless you know what you are doing.
279
280   protocols_allowed
281           my $aref = $ua->protocols_allowed;      # get allowed protocols
282           $ua->protocols_allowed( \@protocols );  # allow ONLY these
283           $ua->protocols_allowed(undef);          # delete the list
284           $ua->protocols_allowed(['http',]);      # ONLY allow http
285
286       By default, an object has neither a "protocols_allowed" list, nor a
287       "protocols_forbidden" in LWP::UserAgent list.
288
289       This reads (or sets) this user agent's list of protocols that the
290       request methods will exclusively allow.  The protocol names are case
291       insensitive.
292
293       For example: "$ua->protocols_allowed( [ 'http', 'https'] );" means that
294       this user agent will allow only those protocols, and attempts to use
295       this user agent to access URLs with any other schemes (like
296       "ftp://...") will result in a 500 error.
297
298       Note that having a "protocols_allowed" list causes any
299       "protocols_forbidden" in LWP::UserAgent list to be ignored.
300
301   protocols_forbidden
302           my $aref = $ua->protocols_forbidden;    # get the forbidden list
303           $ua->protocols_forbidden(\@protocols);  # do not allow these
304           $ua->protocols_forbidden(['http',]);    # All http reqs get a 500
305           $ua->protocols_forbidden(undef);        # delete the list
306
307       This reads (or sets) this user agent's list of protocols that the
308       request method will not allow. The protocol names are case insensitive.
309
310       For example: "$ua->protocols_forbidden( [ 'file', 'mailto'] );" means
311       that this user agent will not allow those protocols, and attempts to
312       use this user agent to access URLs with those schemes will result in a
313       500 error.
314
315   requests_redirectable
316           my $aref = $ua->requests_redirectable;
317           $ua->requests_redirectable( \@requests );
318           $ua->requests_redirectable(['GET', 'HEAD',]); # the default
319
320       This reads or sets the object's list of request names that
321       "redirect_ok" in LWP::UserAgent will allow redirection for. By default,
322       this is "['GET', 'HEAD']", as per RFC 2616
323       <https://tools.ietf.org/html/rfc2616>.  To change to include "POST",
324       consider:
325
326          push @{ $ua->requests_redirectable }, 'POST';
327
328   send_te
329           my $bool = $ua->send_te;
330           $ua->send_te( $boolean );
331
332       If true, will send a "TE" header along with the request. The default is
333       true. Set it to false to disable the "TE" header for systems who can't
334       handle it.
335
336   show_progress
337           my $bool = $ua->show_progress;
338           $ua->show_progress( $boolean );
339
340       Get/set a value indicating whether a progress bar should be displayed
341       on the terminal as requests are processed. The default is false.
342
343   ssl_opts
344           my @keys = $ua->ssl_opts;
345           my $val = $ua->ssl_opts( $key );
346           $ua->ssl_opts( $key => $value );
347
348       Get/set the options for SSL connections.  Without argument return the
349       list of options keys currently set.  With a single argument return the
350       current value for the given option.  With 2 arguments set the option
351       value and return the old.  Setting an option to the value "undef"
352       removes this option.
353
354       The options that LWP relates to are:
355
356       "verify_hostname" => $bool
357           When TRUE LWP will for secure protocol schemes ensure it connects
358           to servers that have a valid certificate matching the expected
359           hostname.  If FALSE no checks are made and you can't be sure that
360           you communicate with the expected peer.  The no checks behaviour
361           was the default for libwww-perl-5.837 and earlier releases.
362
363           This option is initialized from the "PERL_LWP_SSL_VERIFY_HOSTNAME"
364           environment variable.  If this environment variable isn't set; then
365           "verify_hostname" defaults to 1.
366
367       "SSL_ca_file" => $path
368           The path to a file containing Certificate Authority certificates.
369           A default setting for this option is provided by checking the
370           environment variables "PERL_LWP_SSL_CA_FILE" and "HTTPS_CA_FILE" in
371           order.
372
373       "SSL_ca_path" => $path
374           The path to a directory containing files containing Certificate
375           Authority certificates.  A default setting for this option is
376           provided by checking the environment variables
377           "PERL_LWP_SSL_CA_PATH" and "HTTPS_CA_DIR" in order.
378
379       Other options can be set and are processed directly by the SSL Socket
380       implementation in use.  See IO::Socket::SSL or Net::SSL for details.
381
382       The libwww-perl core no longer bundles protocol plugins for SSL.  You
383       will need to install LWP::Protocol::https separately to enable support
384       for processing https-URLs.
385
386   timeout
387           my $secs = $ua->timeout;
388           $ua->timeout( $secs );
389
390       Get/set the timeout value in seconds. The default value is 180 seconds,
391       i.e. 3 minutes.
392
393       The request is aborted if no activity on the connection to the server
394       is observed for "timeout" seconds.  This means that the time it takes
395       for the complete transaction and the "request" in LWP::UserAgent method
396       to actually return might be longer.
397
398       When a request times out, a response object is still returned.  The
399       response will have a standard HTTP Status Code (500).  This response
400       will have the "Client-Warning" header set to the value of "Internal
401       response".  See the "get" in LWP::UserAgent method description below
402       for further details.
403

PROXY ATTRIBUTES

405       The following methods set up when requests should be passed via a proxy
406       server.
407
408   env_proxy
409           $ua->env_proxy;
410
411       Load proxy settings from *_proxy environment variables.  You might
412       specify proxies like this (sh-syntax):
413
414         gopher_proxy=http://proxy.my.place/
415         wais_proxy=http://proxy.my.place/
416         no_proxy="localhost,example.com"
417         export gopher_proxy wais_proxy no_proxy
418
419       csh or tcsh users should use the "setenv" command to define these
420       environment variables.
421
422       On systems with case insensitive environment variables there exists a
423       name clash between the CGI environment variables and the "HTTP_PROXY"
424       environment variable normally picked up by "env_proxy".  Because of
425       this "HTTP_PROXY" is not honored for CGI scripts.  The "CGI_HTTP_PROXY"
426       environment variable can be used instead.
427
428   no_proxy
429           $ua->no_proxy( @domains );
430           $ua->no_proxy('localhost', 'example.com');
431           $ua->no_proxy(); # clear the list
432
433       Do not proxy requests to the given domains.  Calling "no_proxy" without
434       any domains clears the list of domains.
435
436   proxy
437           $ua->proxy(\@schemes, $proxy_url)
438           $ua->proxy(['http', 'ftp'], 'http://proxy.sn.no:8001/');
439
440           # For a single scheme:
441           $ua->proxy($scheme, $proxy_url)
442           $ua->proxy('gopher', 'http://proxy.sn.no:8001/');
443
444           # To set multiple proxies at once:
445           $ua->proxy([
446               ftp => 'http://ftp.example.com:8001/',
447               [ 'http', 'https' ] => 'http://http.example.com:8001/',
448           ]);
449
450       Set/retrieve proxy URL for a scheme.
451
452       The first form specifies that the URL is to be used as a proxy for
453       access methods listed in the list in the first method argument, i.e.
454       "http" and "ftp".
455
456       The second form shows a shorthand form for specifying proxy URL for a
457       single access scheme.
458
459       The third form demonstrates setting multiple proxies at once. This is
460       also the only form accepted by the constructor.
461

HANDLERS

463       Handlers are code that injected at various phases during the processing
464       of requests.  The following methods are provided to manage the active
465       handlers:
466
467   add_handler
468           $ua->add_handler( $phase => \&cb, %matchspec )
469
470       Add handler to be invoked in the given processing phase.  For how to
471       specify %matchspec see "Matching" in HTTP::Config.
472
473       The possible values $phase and the corresponding callback signatures
474       are as follows.  Note that the handlers are documented in the order in
475       which they will be run, which is:
476
477           request_preprepare
478           request_prepare
479           request_send
480           response_header
481           response_data
482           response_done
483           response_redirect
484
485       request_preprepare => sub { my($request, $ua, $handler) = @_; ... }
486           The handler is called before the "request_prepare" and other
487           standard initialization of the request.  This can be used to set up
488           headers and attributes that the "request_prepare" handler depends
489           on.  Proxy initialization should take place here; but in general
490           don't register handlers for this phase.
491
492       request_prepare => sub { my($request, $ua, $handler) = @_; ... }
493           The handler is called before the request is sent and can modify the
494           request any way it see fit.  This can for instance be used to add
495           certain headers to specific requests.
496
497           The method can assign a new request object to $_[0] to replace the
498           request that is sent fully.
499
500           The return value from the callback is ignored.  If an exception is
501           raised it will abort the request and make the request method return
502           a "400 Bad request" response.
503
504       request_send => sub { my($request, $ua, $handler) = @_; ... }
505           This handler gets a chance of handling requests before they're sent
506           to the protocol handlers.  It should return an HTTP::Response
507           object if it wishes to terminate the processing; otherwise it
508           should return nothing.
509
510           The "response_header" and "response_data" handlers will not be
511           invoked for this response, but the "response_done" will be.
512
513       response_header => sub { my($response, $ua, $handler) = @_; ... }
514           This handler is called right after the response headers have been
515           received, but before any content data.  The handler might set up
516           handlers for data and might croak to abort the request.
517
518           The handler might set the "$response->{default_add_content}" value
519           to control if any received data should be added to the response
520           object directly.  This will initially be false if the
521           "$ua->request()" method was called with a $content_file or
522           "$content_cb argument"; otherwise true.
523
524       response_data => sub { my($response, $ua, $handler, $data) = @_; ... }
525           This handler is called for each chunk of data received for the
526           response.  The handler might croak to abort the request.
527
528           This handler needs to return a TRUE value to be called again for
529           subsequent chunks for the same request.
530
531       response_done => sub { my($response, $ua, $handler) = @_; ... }
532           The handler is called after the response has been fully received,
533           but before any redirect handling is attempted.  The handler can be
534           used to extract information or modify the response.
535
536       response_redirect => sub { my($response, $ua, $handler) = @_; ... }
537           The handler is called in "$ua->request" after "response_done".  If
538           the handler returns an HTTP::Request object we'll start over with
539           processing this request instead.
540
541       For all of these, $handler is a code reference to the handler that is
542       currently being run.
543
544   get_my_handler
545           $ua->get_my_handler( $phase, %matchspec );
546           $ua->get_my_handler( $phase, %matchspec, $init );
547
548       Will retrieve the matching handler as hash ref.
549
550       If $init is passed as a true value, create and add the handler if it's
551       not found.  If $init is a subroutine reference, then it's called with
552       the created handler hash as argument.  This sub might populate the hash
553       with extra fields; especially the callback.  If $init is a hash
554       reference, merge the hashes.
555
556   handlers
557           $ua->handlers( $phase, $request )
558           $ua->handlers( $phase, $response )
559
560       Returns the handlers that apply to the given request or response at the
561       given processing phase.
562
563   remove_handler
564           $ua->remove_handler( undef, %matchspec );
565           $ua->remove_handler( $phase, %matchspec );
566           $ua->remove_handlers(); # REMOVE ALL HANDLERS IN ALL PHASES
567
568       Remove handlers that match the given %matchspec.  If $phase is not
569       provided, remove handlers from all phases.
570
571       Be careful as calling this function with %matchspec that is not
572       specific enough can remove handlers not owned by you.  It's probably
573       better to use the "set_my_handler" in LWP::UserAgent method instead.
574
575       The removed handlers are returned.
576
577   set_my_handler
578           $ua->set_my_handler( $phase, $cb, %matchspec );
579           $ua->set_my_handler($phase, undef); # remove handler for phase
580
581       Set handlers private to the executing subroutine.  Works by defaulting
582       an "owner" field to the %matchspec that holds the name of the called
583       subroutine.  You might pass an explicit "owner" to override this.
584
585       If $cb is passed as "undef", remove the handler.
586

REQUEST METHODS

588       The methods described in this section are used to dispatch requests via
589       the user agent.  The following request methods are provided:
590
591   delete
592           my $res = $ua->delete( $url );
593           my $res = $ua->delete( $url, $field_name => $value, ... );
594
595       This method will dispatch a "DELETE" request on the given URL.
596       Additional headers and content options are the same as for the "get" in
597       LWP::UserAgent method.
598
599       This method will use the DELETE() function from HTTP::Request::Common
600       to build the request.  See HTTP::Request::Common for a details on how
601       to pass form content and other advanced features.
602
603   get
604           my $res = $ua->get( $url );
605           my $res = $ua->get( $url , $field_name => $value, ... );
606
607       This method will dispatch a "GET" request on the given URL.  Further
608       arguments can be given to initialize the headers of the request. These
609       are given as separate name/value pairs.  The return value is a response
610       object.  See HTTP::Response for a description of the interface it
611       provides.
612
613       There will still be a response object returned when LWP can't connect
614       to the server specified in the URL or when other failures in protocol
615       handlers occur.  These internal responses use the standard HTTP status
616       codes, so the responses can't be differentiated by testing the response
617       status code alone.  Error responses that LWP generates internally will
618       have the "Client-Warning" header set to the value "Internal response".
619       If you need to differentiate these internal responses from responses
620       that a remote server actually generates, you need to test this header
621       value.
622
623       Fields names that start with ":" are special.  These will not
624       initialize headers of the request but will determine how the response
625       content is treated.  The following special field names are recognized:
626
627           :content_file   => $filename
628           :content_cb     => \&callback
629           :read_size_hint => $bytes
630
631       If a $filename is provided with the ":content_file" option, then the
632       response content will be saved here instead of in the response object.
633       If a callback is provided with the ":content_cb" option then this
634       function will be called for each chunk of the response content as it is
635       received from the server.  If neither of these options are given, then
636       the response content will accumulate in the response object itself.
637       This might not be suitable for very large response bodies.  Only one of
638       ":content_file" or ":content_cb" can be specified.  The content of
639       unsuccessful responses will always accumulate in the response object
640       itself, regardless of the ":content_file" or ":content_cb" options
641       passed in.  Note that errors writing to the content file (for example
642       due to permission denied or the filesystem being full) will be reported
643       via the "Client-Aborted" or "X-Died" response headers, and not the
644       "is_success" method.
645
646       The ":read_size_hint" option is passed to the protocol module which
647       will try to read data from the server in chunks of this size.  A
648       smaller value for the ":read_size_hint" will result in a higher number
649       of callback invocations.
650
651       The callback function is called with 3 arguments: a chunk of data, a
652       reference to the response object, and a reference to the protocol
653       object.  The callback can abort the request by invoking die().  The
654       exception message will show up as the "X-Died" header field in the
655       response returned by the get() function.
656
657   head
658           my $res = $ua->head( $url );
659           my $res = $ua->head( $url , $field_name => $value, ... );
660
661       This method will dispatch a "HEAD" request on the given URL.  Otherwise
662       it works like the "get" in LWP::UserAgent method described above.
663
664   is_protocol_supported
665           my $bool = $ua->is_protocol_supported( $scheme );
666
667       You can use this method to test whether this user agent object supports
668       the specified "scheme".  (The "scheme" might be a string (like "http"
669       or "ftp") or it might be an URI object reference.)
670
671       Whether a scheme is supported is determined by the user agent's
672       "protocols_allowed" or "protocols_forbidden" lists (if any), and by the
673       capabilities of LWP.  I.e., this will return true only if LWP supports
674       this protocol and it's permitted for this particular object.
675
676   is_online
677           my $bool = $ua->is_online;
678
679       Tries to determine if you have access to the Internet. Returns 1 (true)
680       if the built-in heuristics determine that the user agent is able to
681       access the Internet (over HTTP) or 0 (false).
682
683       See also LWP::Online.
684
685   mirror
686           my $res = $ua->mirror( $url, $filename );
687
688       This method will get the document identified by URL and store it in
689       file called $filename.  If the file already exists, then the request
690       will contain an "If-Modified-Since" header matching the modification
691       time of the file.  If the document on the server has not changed since
692       this time, then nothing happens.  If the document has been updated, it
693       will be downloaded again.  The modification time of the file will be
694       forced to match that of the server.
695
696       The return value is an HTTP::Response object.
697
698   post
699           my $res = $ua->post( $url, \%form );
700           my $res = $ua->post( $url, \@form );
701           my $res = $ua->post( $url, \%form, $field_name => $value, ... );
702           my $res = $ua->post( $url, $field_name => $value, Content => \%form );
703           my $res = $ua->post( $url, $field_name => $value, Content => \@form );
704           my $res = $ua->post( $url, $field_name => $value, Content => $content );
705
706       This method will dispatch a "POST" request on the given URL, with %form
707       or @form providing the key/value pairs for the fill-in form content.
708       Additional headers and content options are the same as for the "get" in
709       LWP::UserAgent method.
710
711       This method will use the "POST" function from HTTP::Request::Common to
712       build the request.  See HTTP::Request::Common for a details on how to
713       pass form content and other advanced features.
714
715   put
716           # Any version of HTTP::Message works with this form:
717           my $res = $ua->put( $url, $field_name => $value, Content => $content );
718
719           # Using hash or array references requires HTTP::Message >= 6.07
720           use HTTP::Request 6.07;
721           my $res = $ua->put( $url, \%form );
722           my $res = $ua->put( $url, \@form );
723           my $res = $ua->put( $url, \%form, $field_name => $value, ... );
724           my $res = $ua->put( $url, $field_name => $value, Content => \%form );
725           my $res = $ua->put( $url, $field_name => $value, Content => \@form );
726
727       This method will dispatch a "PUT" request on the given URL, with %form
728       or @form providing the key/value pairs for the fill-in form content.
729       Additional headers and content options are the same as for the "get" in
730       LWP::UserAgent method.
731
732       CAVEAT:
733
734       This method can only accept content that is in key-value pairs when
735       using HTTP::Request::Common prior to version 6.07. Any use of hash or
736       array references will result in an error prior to version 6.07.
737
738       This method will use the "PUT" function from HTTP::Request::Common to
739       build the request.  See HTTP::Request::Common for a details on how to
740       pass form content and other advanced features.
741
742   request
743           my $res = $ua->request( $request );
744           my $res = $ua->request( $request, $content_file );
745           my $res = $ua->request( $request, $content_cb );
746           my $res = $ua->request( $request, $content_cb, $read_size_hint );
747
748       This method will dispatch the given $request object. Normally this will
749       be an instance of the HTTP::Request class, but any object with a
750       similar interface will do. The return value is an HTTP::Response
751       object.
752
753       The "request" method will process redirects and authentication
754       responses transparently. This means that it may actually send several
755       simple requests via the "simple_request" in LWP::UserAgent method
756       described below.
757
758       The request methods described above; "get" in LWP::UserAgent, "head" in
759       LWP::UserAgent, "post" in LWP::UserAgent and "mirror" in LWP::UserAgent
760       will all dispatch the request they build via this method. They are
761       convenience methods that simply hide the creation of the request object
762       for you.
763
764       The $content_file, $content_cb and $read_size_hint all correspond to
765       options described with the "get" in LWP::UserAgent method above. Note
766       that errors writing to the content file (for example due to permission
767       denied or the filesystem being full) will be reported via the
768       "Client-Aborted" or "X-Died" response headers, and not the "is_success"
769       method.
770
771       You are allowed to use a CODE reference as "content" in the request
772       object passed in.  The "content" function should return the content
773       when called.  The content can be returned in chunks.  The content
774       function will be invoked repeatedly until it return an empty string to
775       signal that there is no more content.
776
777   simple_request
778           my $request = HTTP::Request->new( ... );
779           my $res = $ua->simple_request( $request );
780           my $res = $ua->simple_request( $request, $content_file );
781           my $res = $ua->simple_request( $request, $content_cb );
782           my $res = $ua->simple_request( $request, $content_cb, $read_size_hint );
783
784       This method dispatches a single request and returns the response
785       received.  Arguments are the same as for the "request" in
786       LWP::UserAgent described above.
787
788       The difference from "request" in LWP::UserAgent is that
789       "simple_request" will not try to handle redirects or authentication
790       responses.  The "request" in LWP::UserAgent method will, in fact,
791       invoke this method for each simple request it sends.
792

CALLBACK METHODS

794       The following methods will be invoked as requests are processed. These
795       methods are documented here because subclasses of LWP::UserAgent might
796       want to override their behaviour.
797
798   get_basic_credentials
799           # This checks wantarray and can either return an array:
800           my ($user, $pass) = $ua->get_basic_credentials( $realm, $uri, $isproxy );
801           # or a string that looks like "user:pass"
802           my $creds = $ua->get_basic_credentials($realm, $uri, $isproxy);
803
804       This is called by "request" in LWP::UserAgent to retrieve credentials
805       for documents protected by Basic or Digest Authentication.  The
806       arguments passed in is the $realm provided by the server, the $uri
807       requested and a "boolean flag" to indicate if this is authentication
808       against a proxy server.
809
810       The method should return a username and password.  It should return an
811       empty list to abort the authentication resolution attempt.  Subclasses
812       can override this method to prompt the user for the information. An
813       example of this can be found in "lwp-request" program distributed with
814       this library.
815
816       The base implementation simply checks a set of pre-stored member
817       variables, set up with the "credentials" in LWP::UserAgent method.
818
819   prepare_request
820           $request = $ua->prepare_request( $request );
821
822       This method is invoked by "simple_request" in LWP::UserAgent. Its task
823       is to modify the given $request object by setting up various headers
824       based on the attributes of the user agent. The return value should
825       normally be the $request object passed in.  If a different request
826       object is returned it will be the one actually processed.
827
828       The headers affected by the base implementation are; "User-Agent",
829       "From", "Range" and "Cookie".
830
831   progress
832           my $prog = $ua->progress( $status, $request_or_response );
833
834       This is called frequently as the response is received regardless of how
835       the content is processed.  The method is called with $status "begin" at
836       the start of processing the request and with $state "end" before the
837       request method returns.  In between these $status will be the fraction
838       of the response currently received or the string "tick" if the fraction
839       can't be calculated.
840
841       When $status is "begin" the second argument is the HTTP::Request
842       object, otherwise it is the HTTP::Response object.
843
844   redirect_ok
845           my $bool = $ua->redirect_ok( $prospective_request, $response );
846
847       This method is called by "request" in LWP::UserAgent before it tries to
848       follow a redirection to the request in $response.  This should return a
849       true value if this redirection is permissible.  The
850       $prospective_request will be the request to be sent if this method
851       returns true.
852
853       The base implementation will return false unless the method is in the
854       object's "requests_redirectable" list, false if the proposed
855       redirection is to a "file://..."  URL, and true otherwise.
856

BEST PRACTICES

858       The default settings can get you up and running quickly, but there are
859       settings you can change in order to make your life easier.
860
861   Handling Cookies
862       You are encouraged to install Mozilla::PublicSuffix and use
863       HTTP::CookieJar::LWP as your cookie jar.  HTTP::CookieJar::LWP provides
864       a better security model matching that of current Web browsers when
865       Mozilla::PublicSuffix is installed.
866
867           use HTTP::CookieJar::LWP ();
868
869           my $jar = HTTP::CookieJar::LWP->new;
870           my $ua = LWP::UserAgent->new( cookie_jar => $jar );
871
872       See "cookie_jar" for more information.
873
874   Managing Protocols
875       "protocols_allowed" gives you the ability to whitelist the protocols
876       you're willing to allow.
877
878           my $ua = LWP::UserAgent->new(
879               protocols_allowed => [ 'http', 'https' ]
880           );
881
882       This will prevent you from inadvertently following URLs like
883       "file:///etc/passwd".  See "protocols_allowed".
884
885       "protocols_forbidden" gives you the ability to blacklist the protocols
886       you're unwilling to allow.
887
888           my $ua = LWP::UserAgent->new(
889               protocols_forbidden => [ 'file', 'mailto', 'ssh', ]
890           );
891
892       This can also prevent you from inadvertently following URLs like
893       "file:///etc/passwd".  See "protocols_forbidden".
894

SEE ALSO

896       See LWP for a complete overview of libwww-perl5.  See lwpcook and the
897       scripts lwp-request and lwp-download for examples of usage.
898
899       See HTTP::Request and HTTP::Response for a description of the message
900       objects dispatched and received.  See HTTP::Request::Common and
901       HTML::Form for other ways to build request objects.
902
903       See WWW::Mechanize and WWW::Search for examples of more specialized
904       user agents based on LWP::UserAgent.
905
907       Copyright 1995-2009 Gisle Aas.
908
909       This library is free software; you can redistribute it and/or modify it
910       under the same terms as Perl itself.
911
912
913
914perl v5.28.1                      2019-05-06                 LWP::UserAgent(3)
Impressum