HTTP::Response
HTTP::Response(3) User Contributed Perl Documentation HTTP::Response(3)
NAME
HTTP::Response - HTTP style response message
SYNOPSIS
Response objects are returned by the request() method of the
"LWP::UserAgent":
# ...
$response = $ua->request($request)
if ($response->is_success) {
print $response->content;
}
else {
print STDERR $response->status_line, "\n";
}
DESCRIPTION
The "HTTP::Response" class encapsulates HTTP style responses. A
response consists of a response line, some headers, and a content body.
Note that the LWP library uses HTTP style responses even for non-HTTP
protocol schemes. Instances of this class are usually created and
returned by the request() method of an "LWP::UserAgent" object.
"HTTP::Response" is a subclass of "HTTP::Message" and therefore inher-
its its methods. The following additional methods are available:
$r = HTTP::Response->new( $code )
$r = HTTP::Response->new( $code, $msg )
$r = HTTP::Response->new( $code, $msg, $header )
$r = HTTP::Response->new( $code, $msg, $header, $content )
Constructs a new "HTTP::Response" object describing a response with
response code $code and optional message $msg. The optional
$header argument should be a reference to an "HTTP::Headers" object
or a plain array reference of key/value pairs. The optional $con-
tent argument should be a string of bytes. The meaning these argu-
ments are described below.
$r = HTTP::Response->parse( $str )
This constructs a new response object by parsing the given string.
$r->code
$r->code( $code )
This is used to get/set the code attribute. The code is a 3 digit
number that encode the overall outcome of a HTTP response. The
"HTTP::Status" module provide constants that provide mnemonic names
for the code attribute.
$r->message
$r->message( $message )
This is used to get/set the message attribute. The message is a
short human readable single line string that explains the response
code.
$r->header( $field )
$r->header( $field => $value )
This is used to get/set header values and it is inherited from
"HTTP::Headers" via "HTTP::Message". See HTTP::Headers for details
and other similar methods that can be used to access the headers.
$r->content
$r->content( $content )
This is used to get/set the raw content and it is inherited from
the "HTTP::Message" base class. See HTTP::Message for details and
other methods that can be used to access the content.
$r->decoded_content( %options )
This will return the content after any "Content-Encoding" and
charsets has been decoded. See HTTP::Message for details.
$r->request
$r->request( $request )
This is used to get/set the request attribute. The request
attribute is a reference to the the request that caused this
response. It does not have to be the same request passed to the
$ua->request() method, because there might have been redirects and
authorization retries in between.
$r->previous
$r->previous( $response )
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 unautho-
rized. The value is "undef" if this is the first response in a
chain.
$r->status_line
Returns the string "<code> <message>". If the message attribute is
not set then the official name of <code> (see HTTP::Status) is sub-
stituted.
$r->base
Returns the base URI for this response. The return value will be a
reference to a URI object.
The base URI is obtained from one the following sources (in prior-
ity order):
1. Embedded in the document content, for instance <BASE
HREF="..."> in HTML documents.
2. A "Content-Base:" or a "Content-Location:" header in the
response.
For backwards compatibility with older HTTP implementations we
will also look for the "Base:" header.
3. The URI used to request this response. This might not be the
original URI that was passed to $ua->request() method, because
we might have received some redirect responses first.
If neither of these sources provide an absolute URI, undef is
returned.
When the LWP protocol modules produce the HTTP::Response object,
then any base URI embedded in the document (step 1) will already
have initialized the "Content-Base:" header. This means that this
method only performs the last 2 steps (the content is not always
available either).
$r->as_string
$r->as_string( $eol )
Returns a textual representation of the response.
$r->is_info
$r->is_success
$r->is_redirect
$r->is_error
These methods indicate if the response was informational, success-
ful, a redirection, or an error. See HTTP::Status for the meaning
of these.
$r->error_as_HTML
Returns a string containing a complete HTML document indicating
what error occurred. This method should only be called when
$r->is_error is TRUE.
$r->current_age
Calculates the "current age" of the response as specified by RFC
2616 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 rep-
resenting the age in seconds.
$r->freshness_lifetime
Calculates the "freshness lifetime" of the response as specified by
RFC 2616 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 a number representing the freshness lifetime
in seconds.
If the response does not contain an "Expires" or a "Cache-Control"
header, then this function will apply some simple heuristic based
on 'Last-Modified' to determine a suitable lifetime.
$r->is_fresh
Returns TRUE if the response is fresh, based on the values of
freshness_lifetime() and current_age(). If the response is no
longer fresh, then it has to be refetched or revalidated by the
origin server.
$r->fresh_until
Returns the time when this entity is no longer fresh.
SEE ALSO
HTTP::Headers, HTTP::Message, HTTP::Status, HTTP::Request
COPYRIGHT
Copyright 1995-2004 Gisle Aas.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
perl v5.8.6 2005-12-06 HTTP::Response(3)
