522 lines
12 KiB
HTML
522 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of HTTP::Response</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>HTTP::Response</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2020-02-29<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
HTTP::Response - HTTP style response message
|
|
<A NAME="lbAC"> </A>
|
|
<H2>VERSION</H2>
|
|
|
|
|
|
|
|
version 6.22
|
|
<A NAME="lbAD"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
Response objects are returned by the <B>request()</B> method of the <TT>"LWP::UserAgent"</TT>:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
# ...
|
|
$response = $ua->request($request);
|
|
if ($response->is_success) {
|
|
print $response->decoded_content;
|
|
}
|
|
else {
|
|
print STDERR $response->status_line, "\n";
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The <TT>"HTTP::Response"</TT> class encapsulates <FONT SIZE="-1">HTTP</FONT> style responses. A
|
|
response consists of a response line, some headers, and a content
|
|
body. Note that the <FONT SIZE="-1">LWP</FONT> library uses <FONT SIZE="-1">HTTP</FONT> style responses even for
|
|
non-HTTP protocol schemes. Instances of this class are usually
|
|
created and returned by the <B>request()</B> method of an <TT>"LWP::UserAgent"</TT>
|
|
object.
|
|
<P>
|
|
|
|
<TT>"HTTP::Response"</TT> is a subclass of <TT>"HTTP::Message"</TT> and therefore
|
|
inherits its methods. The following additional methods are available:
|
|
<DL COMPACT>
|
|
<DT id="1">$r = HTTP::Response->new( $code )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="2">$r = HTTP::Response->new( $code, $msg )<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="3">$r = HTTP::Response->new( $code, $msg, $header )<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="4">$r = HTTP::Response->new( $code, $msg, $header, $content )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Constructs a new <TT>"HTTP::Response"</TT> object describing a response with
|
|
response code <TT>$code</TT> and optional message <TT>$msg</TT>. The optional <TT>$header</TT>
|
|
argument should be a reference to an <TT>"HTTP::Headers"</TT> object or a
|
|
plain array reference of key/value pairs. The optional <TT>$content</TT>
|
|
argument should be a string of bytes. The meanings of these arguments are
|
|
described below.
|
|
<DT id="5">$r = HTTP::Response->parse( $str )<DD>
|
|
|
|
|
|
|
|
|
|
This constructs a new response object by parsing the given string.
|
|
<DT id="6">$r->code<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="7">$r->code( $code )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This is used to get/set the code attribute. The code is a 3 digit
|
|
number that encode the overall outcome of an <FONT SIZE="-1">HTTP</FONT> response. The
|
|
<TT>"HTTP::Status"</TT> module provide constants that provide mnemonic names
|
|
for the code attribute.
|
|
<DT id="8">$r->message<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="9">$r->message( $message )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This is used to get/set the message attribute. The message is a short
|
|
human readable single line string that explains the response code.
|
|
<DT id="10">$r->header( $field )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="11">$r->header( $field => $value )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This is used to get/set header values and it is inherited from
|
|
<TT>"HTTP::Headers"</TT> via <TT>"HTTP::Message"</TT>. See HTTP::Headers for
|
|
details and other similar methods that can be used to access the
|
|
headers.
|
|
<DT id="12">$r->content<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="13">$r->content( $bytes )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This is used to get/set the raw content and it is inherited from the
|
|
<TT>"HTTP::Message"</TT> base class. See HTTP::Message for details and
|
|
other methods that can be used to access the content.
|
|
<DT id="14">$r->decoded_content( %options )<DD>
|
|
|
|
|
|
|
|
|
|
This will return the content after any <TT>"Content-Encoding"</TT> and
|
|
charsets have been decoded. See HTTP::Message for details.
|
|
<DT id="15">$r->request<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="16">$r->request( $request )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This is used to get/set the request attribute. The request attribute
|
|
is a reference to the request that caused this response. It does
|
|
not have to be the same request passed to the <TT>$ua</TT>-><B>request()</B> method,
|
|
because there might have been redirects and authorization retries in
|
|
between.
|
|
<DT id="17">$r->previous<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="18">$r->previous( $response )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This is used to get/set the previous attribute. The previous
|
|
attribute is used to link together chains of responses. You get
|
|
chains of responses if the first response is redirect or unauthorized.
|
|
The value is <TT>"undef"</TT> if this is the first response in a chain.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that the method <TT>$r</TT>->redirects is provided as a more convenient
|
|
way to access the response chain.
|
|
<DT id="19">$r->status_line<DD>
|
|
|
|
|
|
|
|
|
|
Returns the string ``<code> <message>''. If the message attribute
|
|
is not set then the official name of <code> (see HTTP::Status)
|
|
is substituted.
|
|
<DT id="20">$r->base<DD>
|
|
|
|
|
|
|
|
|
|
Returns the base <FONT SIZE="-1">URI</FONT> for this response. The return value will be a
|
|
reference to a <FONT SIZE="-1">URI</FONT> object.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The base <FONT SIZE="-1">URI</FONT> is obtained from one the following sources (in priority
|
|
order):
|
|
<DL COMPACT><DT id="21"><DD>
|
|
<DL COMPACT>
|
|
<DT id="22">1.<DD>
|
|
Embedded in the document content, for instance <<FONT SIZE="-1">BASE</FONT> HREF=``...''>
|
|
in <FONT SIZE="-1">HTML</FONT> documents.
|
|
<DT id="23">2.<DD>
|
|
A ``Content-Base:'' or a ``Content-Location:'' header in the response.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For backwards compatibility with older <FONT SIZE="-1">HTTP</FONT> implementations we will
|
|
also look for the ``Base:'' header.
|
|
<DT id="24">3.<DD>
|
|
The <FONT SIZE="-1">URI</FONT> used to request this response. This might not be the original
|
|
<FONT SIZE="-1">URI</FONT> that was passed to <TT>$ua</TT>-><B>request()</B> method, because we might have
|
|
received some redirect responses first.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="25"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If none of these sources provide an absolute <FONT SIZE="-1">URI,</FONT> undef is returned.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When the <FONT SIZE="-1">LWP</FONT> protocol modules produce the HTTP::Response object, then any base
|
|
<FONT SIZE="-1">URI</FONT> embedded in the document (step 1) will already have initialized the
|
|
``Content-Base:'' header. (See ``parse_head'' in LWP::UserAgent). This means that
|
|
this method only performs the last 2 steps (the content is not always available
|
|
either).
|
|
</DL>
|
|
|
|
<DT id="26">$r->filename<DD>
|
|
|
|
|
|
|
|
|
|
Returns a filename for this response. Note that doing sanity checks
|
|
on the returned filename (eg. removing characters that cannot be used
|
|
on the target filesystem where the filename would be used, and
|
|
laundering it for security purposes) are the caller's responsibility;
|
|
the only related thing done by this method is that it makes a simple
|
|
attempt to return a plain filename with no preceding path segments.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The filename is obtained from one the following sources (in priority
|
|
order):
|
|
<DL COMPACT><DT id="27"><DD>
|
|
<DL COMPACT>
|
|
<DT id="28">1.<DD>
|
|
A ``Content-Disposition:'' header in the response. Proper decoding of
|
|
<FONT SIZE="-1">RFC 2047</FONT> encoded filenames requires the <TT>"MIME::QuotedPrint"</TT> (for ``Q''
|
|
encoding), <TT>"MIME::Base64"</TT> (for ``B'' encoding), and <TT>"Encode"</TT> modules.
|
|
<DT id="29">2.<DD>
|
|
A ``Content-Location:'' header in the response.
|
|
<DT id="30">3.<DD>
|
|
The <FONT SIZE="-1">URI</FONT> used to request this response. This might not be the original
|
|
<FONT SIZE="-1">URI</FONT> that was passed to <TT>$ua</TT>-><B>request()</B> method, because we might have
|
|
received some redirect responses first.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="31"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If a filename cannot be derived from any of these sources, undef is
|
|
returned.
|
|
</DL>
|
|
|
|
<DT id="32">$r->as_string<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="33">$r->as_string( $eol )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Returns a textual representation of the response.
|
|
<DT id="34">$r->is_info<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="35">$r->is_success<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="36">$r->is_redirect<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="37">$r->is_error<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="38">$r->is_client_error<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="39">$r->is_server_error<DD>
|
|
|
|
|
|
|
|
|
|
|
|
These methods indicate if the response was informational, successful, a
|
|
redirection, or an error. See HTTP::Status for the meaning of these.
|
|
<DT id="40">$r->error_as_HTML<DD>
|
|
|
|
|
|
|
|
|
|
Returns a string containing a complete <FONT SIZE="-1">HTML</FONT> document indicating what
|
|
error occurred. This method should only be called when <TT>$r</TT>->is_error
|
|
is <FONT SIZE="-1">TRUE.</FONT>
|
|
<DT id="41">$r->redirects<DD>
|
|
|
|
|
|
|
|
|
|
Returns the list of redirect responses that lead up to this response
|
|
by following the <TT>$r</TT>->previous chain. The list order is oldest first.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In scalar context return the number of redirect responses leading up
|
|
to this one.
|
|
<DT id="42">$r->current_age<DD>
|
|
|
|
|
|
|
|
|
|
Calculates the ``current age'' of the response as specified by <FONT SIZE="-1">RFC 2616</FONT>
|
|
section 13.2.3. The age of a response is the time since it was sent
|
|
by the origin server. The returned value is a number representing the
|
|
age in seconds.
|
|
<DT id="43">$r->freshness_lifetime( %opt )<DD>
|
|
|
|
|
|
|
|
|
|
Calculates the ``freshness lifetime'' of the response as specified by
|
|
<FONT SIZE="-1">RFC 2616</FONT> section 13.2.4. The ``freshness lifetime'' is the length of
|
|
time between the generation of a response and its expiration time.
|
|
The returned value is the number of seconds until expiry.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
If the response does not contain an ``Expires'' or a ``Cache-Control''
|
|
header, then this function will apply some simple heuristic based on
|
|
the ``Last-Modified'' header to determine a suitable lifetime. The
|
|
following options might be passed to control the heuristics:
|
|
<DL COMPACT><DT id="44"><DD>
|
|
<DL COMPACT>
|
|
<DT id="45">heuristic_expiry => $bool<DD>
|
|
|
|
|
|
|
|
|
|
If passed as a <FONT SIZE="-1">FALSE</FONT> value, don't apply heuristics and just return
|
|
<TT>"undef"</TT> when ``Expires'' or ``Cache-Control'' is lacking.
|
|
<DT id="46">h_lastmod_fraction => $num<DD>
|
|
|
|
|
|
|
|
|
|
This number represent the fraction of the difference since the
|
|
``Last-Modified'' timestamp to make the expiry time. The default is
|
|
<TT>0.10</TT>, the suggested typical setting of 10% in <FONT SIZE="-1">RFC 2616.</FONT>
|
|
<DT id="47">h_min => $sec<DD>
|
|
|
|
|
|
|
|
|
|
This is the lower limit of the heuristic expiry age to use. The
|
|
default is <TT>60</TT> (1 minute).
|
|
<DT id="48">h_max => $sec<DD>
|
|
|
|
|
|
|
|
|
|
This is the upper limit of the heuristic expiry age to use. The
|
|
default is <TT>86400</TT> (24 hours).
|
|
<DT id="49">h_default => $sec<DD>
|
|
|
|
|
|
|
|
|
|
This is the expiry age to use when nothing else applies. The default
|
|
is <TT>3600</TT> (1 hour) or ``h_min'' if greater.
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="50"><DD>
|
|
</DL>
|
|
|
|
<DT id="51">$r->is_fresh( %opt )<DD>
|
|
|
|
|
|
|
|
|
|
Returns <FONT SIZE="-1">TRUE</FONT> if the response is fresh, based on the values of
|
|
<B>freshness_lifetime()</B> and <B>current_age()</B>. If the response is no longer
|
|
fresh, then it has to be re-fetched or re-validated by the origin
|
|
server.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Options might be passed to control expiry heuristics, see the
|
|
description of <B>freshness_lifetime()</B>.
|
|
<DT id="52">$r->fresh_until( %opt )<DD>
|
|
|
|
|
|
|
|
|
|
Returns the time (seconds since epoch) when this entity is no longer fresh.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Options might be passed to control expiry heuristics, see the
|
|
description of <B>freshness_lifetime()</B>.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
HTTP::Headers, HTTP::Message, HTTP::Status, HTTP::Request
|
|
<A NAME="lbAG"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Gisle Aas <<A HREF="mailto:gisle@activestate.com">gisle@activestate.com</A>>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>COPYRIGHT AND LICENSE</H2>
|
|
|
|
|
|
|
|
This software is copyright (c) 1994-2017 by Gisle Aas.
|
|
<P>
|
|
|
|
This is free software; you can redistribute it and/or modify it under
|
|
the same terms as the Perl 5 programming language system itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="53"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="54"><A HREF="#lbAC">VERSION</A><DD>
|
|
<DT id="55"><A HREF="#lbAD">SYNOPSIS</A><DD>
|
|
<DT id="56"><A HREF="#lbAE">DESCRIPTION</A><DD>
|
|
<DT id="57"><A HREF="#lbAF">SEE ALSO</A><DD>
|
|
<DT id="58"><A HREF="#lbAG">AUTHOR</A><DD>
|
|
<DT id="59"><A HREF="#lbAH">COPYRIGHT AND LICENSE</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:46 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|