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        use LWP::UserAgent ();
12
13        my $ua = LWP::UserAgent->new;
14        $ua->timeout(10);
15        $ua->env_proxy;
16
17        my $response = $ua->get('http://search.cpan.org/');
18
19        if ($response->is_success) {
20            print $response->decoded_content;  # or whatever
21        }
22        else {
23            die $response->status_line;
24        }
25

DESCRIPTION

27       The LWP::UserAgent is a class implementing a web user agent.
28       LWP::UserAgent objects can be used to dispatch web requests.
29
30       In normal use the application creates an LWP::UserAgent object, and
31       then configures it with values for timeouts, proxies, name, etc. It
32       then creates an instance of HTTP::Request for the request that needs to
33       be performed. This request is then passed to one of the request method
34       the UserAgent, which dispatches it using the relevant protocol, and
35       returns a HTTP::Response object.  There are convenience methods for
36       sending the most common request types: "get" in LWP::UserAgent, "head"
37       in LWP::UserAgent, "post" in LWP::UserAgent, "put" in LWP::UserAgent
38       and "delete" in LWP::UserAgent.  When using these methods, the creation
39       of the request object is hidden as shown in the synopsis above.
40
41       The basic approach of the library is to use HTTP-style communication
42       for all protocol schemes.  This means that you will construct
43       HTTP::Request objects and receive HTTP::Response objects even for non-
44       HTTP resources like gopher and ftp.  In order to achieve even more
45       similarity to HTTP-style communications, gopher menus and file
46       directories are converted to HTML documents.
47

CONSTRUCTOR METHODS

49       The following constructor methods are available:
50
51   clone
52           my $ua2 = $ua->clone;
53
54       Returns a copy of the LWP::UserAgent object.
55
56       CAVEAT: Please be aware that the clone method does not copy or clone
57       your "cookie_jar" attribute. Due to the limited restrictions on what
58       can be used for your cookie jar, there is no way to clone the
59       attribute. The "cookie_jar" attribute will be "undef" in the new object
60       instance.
61
62   new
63           my $ua = LWP::UserAgent->new( %options )
64
65       This method constructs a new LWP::UserAgent object and returns it.
66       Key/value pair arguments may be provided to set up the initial state.
67       The following options correspond to attribute methods described below:
68
69          KEY                     DEFAULT
70          -----------             --------------------
71          agent                   "libwww-perl/#.###"
72          from                    undef
73          conn_cache              undef
74          cookie_jar              undef
75          default_headers         HTTP::Headers->new
76          local_address           undef
77          ssl_opts                { verify_hostname => 1 }
78          max_size                undef
79          max_redirect            7
80          parse_head              1
81          protocols_allowed       undef
82          protocols_forbidden     undef
83          requests_redirectable   ['GET', 'HEAD']
84          timeout                 180
85          proxy                   undef
86          no_proxy                []
87
88       The following additional options are also accepted: If the "env_proxy"
89       option is passed in with a true value, then proxy settings are read
90       from environment variables (see "env_proxy" in LWP::UserAgent). If
91       "env_proxy" isn't provided, the "PERL_LWP_ENV_PROXY" environment
92       variable controls if "env_proxy" in LWP::UserAgent is called during
93       initialization.  If the "keep_alive" option is passed in, then a
94       "LWP::ConnCache" is set up (see "conn_cache" in LWP::UserAgent).  The
95       "keep_alive" value is passed on as the "total_capacity" for the
96       connection cache.
97
98       "proxy" must be set as an arrayref of key/value pairs. "no_proxy" takes
99       an arrayref of domains.
100

ATTRIBUTES

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

PROXY ATTRIBUTES

369       The following methods set up when requests should be passed via a proxy
370       server.
371
372   env_proxy
373           $ua->env_proxy;
374
375       Load proxy settings from *_proxy environment variables.  You might
376       specify proxies like this (sh-syntax):
377
378         gopher_proxy=http://proxy.my.place/
379         wais_proxy=http://proxy.my.place/
380         no_proxy="localhost,example.com"
381         export gopher_proxy wais_proxy no_proxy
382
383       csh or tcsh users should use the "setenv" command to define these
384       environment variables.
385
386       On systems with case insensitive environment variables there exists a
387       name clash between the CGI environment variables and the "HTTP_PROXY"
388       environment variable normally picked up by "env_proxy".  Because of
389       this "HTTP_PROXY" is not honored for CGI scripts.  The "CGI_HTTP_PROXY"
390       environment variable can be used instead.
391
392   no_proxy
393           $ua->no_proxy( @domains );
394           $ua->no_proxy('localhost', 'example.com');
395           $ua->no_proxy(); # clear the list
396
397       Do not proxy requests to the given domains.  Calling "no_proxy" without
398       any domains clears the list of domains.
399
400   proxy
401           $ua->proxy(\@schemes, $proxy_url)
402           $ua->proxy(['http', 'ftp'], 'http://proxy.sn.no:8001/');
403
404           # For a single scheme:
405           $ua->proxy($scheme, $proxy_url)
406           $ua->proxy('gopher', 'http://proxy.sn.no:8001/');
407
408           # To set multiple proxies at once:
409           $ua->proxy([
410               ftp => 'http://ftp.example.com:8001/',
411               [ 'http', 'https' ] => 'http://http.example.com:8001/',
412           ]);
413
414       Set/retrieve proxy URL for a scheme.
415
416       The first form specifies that the URL is to be used as a proxy for
417       access methods listed in the list in the first method argument, i.e.
418       "http" and "ftp".
419
420       The second form shows a shorthand form for specifying proxy URL for a
421       single access scheme.
422
423       The third form demonstrates setting multiple proxies at once. This is
424       also the only form accepted by the constructor.
425

HANDLERS

427       Handlers are code that injected at various phases during the processing
428       of requests.  The following methods are provided to manage the active
429       handlers:
430
431   add_handler
432           $ua->add_handler( $phase => \&cb, %matchspec )
433
434       Add handler to be invoked in the given processing phase.  For how to
435       specify %matchspec see "Matching" in HTTP::Config.
436
437       The possible values $phase and the corresponding callback signatures
438       are:
439
440       response_data => sub { my($response, $ua, $h, $data) = @_; ... }
441           This handler is called for each chunk of data received for the
442           response.  The handler might croak to abort the request.
443
444           This handler needs to return a TRUE value to be called again for
445           subsequent chunks for the same request.
446
447       response_done => sub { my($response, $ua, $h) = @_; ... }
448           The handler is called after the response has been fully received,
449           but before any redirect handling is attempted.  The handler can be
450           used to extract information or modify the response.
451
452       response_header => sub { my($response, $ua, $h) = @_; ... }
453           This handler is called right after the response headers have been
454           received, but before any content data.  The handler might set up
455           handlers for data and might croak to abort the request.
456
457           The handler might set the $response->{default_add_content} value to
458           control if any received data should be added to the response object
459           directly.  This will initially be false if the $ua->request()
460           method was called with a $content_file or $content_cb argument;
461           otherwise true.
462
463       request_prepare => sub { my($request, $ua, $h) = @_; ... }
464           The handler is called before the request is sent and can modify the
465           request any way it see fit.  This can for instance be used to add
466           certain headers to specific requests.
467
468           The method can assign a new request object to $_[0] to replace the
469           request that is sent fully.
470
471           The return value from the callback is ignored.  If an exception is
472           raised it will abort the request and make the request method return
473           a "400 Bad request" response.
474
475       request_preprepare => sub { my($request, $ua, $h) = @_; ... }
476           The handler is called before the "request_prepare" and other
477           standard initialization of the request.  This can be used to set up
478           headers and attributes that the "request_prepare" handler depends
479           on.  Proxy initialization should take place here; but in general
480           don't register handlers for this phase.
481
482       request_send => sub { my($request, $ua, $h) = @_; ... }
483           This handler gets a chance of handling requests before they're sent
484           to the protocol handlers.  It should return an HTTP::Response
485           object if it wishes to terminate the processing; otherwise it
486           should return nothing.
487
488           The "response_header" and "response_data" handlers will not be
489           invoked for this response, but the "response_done" will be.
490
491       response_redirect => sub { my($response, $ua, $h) = @_; ... }
492           The handler is called in $ua->request after "response_done".  If
493           the handler returns an HTTP::Request object we'll start over with
494           processing this request instead.
495
496   get_my_handler
497           $ua->get_my_handler( $phase, %matchspec );
498           $ua->get_my_handler( $phase, %matchspec, $init );
499
500       Will retrieve the matching handler as hash ref.
501
502       If $init is passed as a true value, create and add the handler if it's
503       not found.  If $init is a subroutine reference, then it's called with
504       the created handler hash as argument.  This sub might populate the hash
505       with extra fields; especially the callback.  If $init is a hash
506       reference, merge the hashes.
507
508   handlers
509           $ua->handlers( $phase, $request )
510           $ua->handlers( $phase, $response )
511
512       Returns the handlers that apply to the given request or response at the
513       given processing phase.
514
515   remove_handler
516           $ua->remove_handler( undef, %matchspec );
517           $ua->remove_handler( $phase, %matchspec );
518           $ua->remove_handlers(); # REMOVE ALL HANDLERS IN ALL PHASES
519
520       Remove handlers that match the given %matchspec.  If $phase is not
521       provided, remove handlers from all phases.
522
523       Be careful as calling this function with %matchspec that is not
524       specific enough can remove handlers not owned by you.  It's probably
525       better to use the "set_my_handler" in LWP::UserAgent method instead.
526
527       The removed handlers are returned.
528
529   set_my_handler
530           $ua->set_my_handler( $phase, $cb, %matchspec );
531           $ua->set_my_handler($phase, undef); # remove handler for phase
532
533       Set handlers private to the executing subroutine.  Works by defaulting
534       an "owner" field to the %matchspec that holds the name of the called
535       subroutine.  You might pass an explicit "owner" to override this.
536
537       If $cb is passed as "undef", remove the handler.
538

REQUEST METHODS

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

CALLBACK METHODS

746       The following methods will be invoked as requests are processed. These
747       methods are documented here because subclasses of LWP::UserAgent might
748       want to override their behaviour.
749
750   get_basic_credentials
751           # This checks wantarray and can either return an array:
752           my ($user, $pass) = $ua->get_basic_credentials( $realm, $uri, $isproxy );
753           # or a string that looks like "user:pass"
754           my $creds = $ua->get_basic_credentials($realm, $uri, $isproxy);
755
756       This is called by "request" in LWP::UserAgent to retrieve credentials
757       for documents protected by Basic or Digest Authentication.  The
758       arguments passed in is the $realm provided by the server, the $uri
759       requested and a "boolean flag" to indicate if this is authentication
760       against a proxy server.
761
762       The method should return a username and password.  It should return an
763       empty list to abort the authentication resolution attempt.  Subclasses
764       can override this method to prompt the user for the information. An
765       example of this can be found in "lwp-request" program distributed with
766       this library.
767
768       The base implementation simply checks a set of pre-stored member
769       variables, set up with the "credentials" in LWP::UserAgent method.
770
771   prepare_request
772           $request = $ua->prepare_request( $request );
773
774       This method is invoked by "simple_request" in LWP::UserAgent. Its task
775       is to modify the given $request object by setting up various headers
776       based on the attributes of the user agent. The return value should
777       normally be the $request object passed in.  If a different request
778       object is returned it will be the one actually processed.
779
780       The headers affected by the base implementation are; "User-Agent",
781       "From", "Range" and "Cookie".
782
783   progress
784           my $prog = $ua->progress( $status, $request_or_response );
785
786       This is called frequently as the response is received regardless of how
787       the content is processed.  The method is called with $status "begin" at
788       the start of processing the request and with $state "end" before the
789       request method returns.  In between these $status will be the fraction
790       of the response currently received or the string "tick" if the fraction
791       can't be calculated.
792
793       When $status is "begin" the second argument is the HTTP::Request
794       object, otherwise it is the HTTP::Response object.
795
796   redirect_ok
797           my $bool = $ua->redirect_ok( $prospective_request, $response );
798
799       This method is called by "request" in LWP::UserAgent before it tries to
800       follow a redirection to the request in $response.  This should return a
801       true value if this redirection is permissible.  The
802       $prospective_request will be the request to be sent if this method
803       returns true.
804
805       The base implementation will return false unless the method is in the
806       object's "requests_redirectable" list, false if the proposed
807       redirection is to a "file://..."  URL, and true otherwise.
808

SEE ALSO

810       See LWP for a complete overview of libwww-perl5.  See lwpcook and the
811       scripts lwp-request and lwp-download for examples of usage.
812
813       See HTTP::Request and HTTP::Response for a description of the message
814       objects dispatched and received.  See HTTP::Request::Common and
815       HTML::Form for other ways to build request objects.
816
817       See WWW::Mechanize and WWW::Search for examples of more specialized
818       user agents based on LWP::UserAgent.
819
821       Copyright 1995-2009 Gisle Aas.
822
823       This library is free software; you can redistribute it and/or modify it
824       under the same terms as Perl itself.
825
826
827
828perl v5.28.0                      2018-07-16                 LWP::UserAgent(3)
Impressum