http::response(3)
NAME
HTTP::Response - Class encapsulating HTTP Responses
SYNOPSIS
require HTTP::Response;
DESCRIPTION
The "HTTP::Response" class encapsulates HTTP style
responses. A response consists of a response line, some
headers, and (potentially empty) content. Note that the
LWP library also uses HTTP style responses for non-HTTP
protocol schemes.
- Instances of this class are usually created and returned
by the "request()" method of an "LWP::UserAgent" object: - #...
$response = $ua->request($request)
if ($response->is_success) {print $response->content; - } else {
print $response->error_as_HTML;
- }
- "HTTP::Response" is a subclass of "HTTP::Message" and
therefore inherits its methods. The inherited methods
most often used are header(), push_header(), remove_header(), and content(). The header convenience methods are also available. See HTTP::Message for
details. - The following additional methods are available:
- $r = HTTP::Response->new($rc, [$msg, [$header, [$con
tent]]]) - Constructs a new "HTTP::Response" object describing a
response with response code $rc and optional message
$msg. The message is a short human readable single
line string that explains the response code. - $r->code([$code])
$r->message([$message])
$r->request([$request])
$r->previous([$previousResponse]) - These methods provide public access to the object
attributes. The first two contain respectively the
response code and the message of the response. - The request attribute is a reference the request that
caused this response. It does not have to be the same
request as passed to the $ua->request() method,
because there might have been redirects and authoriza
tion retries in between. - The previous attribute is used to link together chains
of responses. You get chains of responses if the
first response is redirect or unauthorized. - $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 substituted. - $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 priority 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 compatability with older HTTP imple
mentations 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. - 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
Returns a textual representation of the response.
Mainly useful for debugging purposes. It takes no
arguments. - $r->is_info
$r->is_success
$r->is_redirect
$r->is_error
These methods indicate if the response was informa
tional, sucessful, a redirection, or an error. - $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 speci
fied by <draft-ietf-http-v11-spec-07> 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. - $r->freshness_lifetime
Calculates the "freshness lifetime" of the response as
specified by <draft-ietf-http-v11-spec-07> 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 rep
resenting 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 entiy is no longer fresh.
COPYRIGHT
Copyright 1995-2001 Gisle Aas.
- This library is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.