Second pass at adding key files
This commit is contained in:
dsainty
584
site/glist/templates/help/GT/WWW/http/Header.html
Normal file
584
site/glist/templates/help/GT/WWW/http/Header.html
Normal file
@ -0,0 +1,584 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<title>GT::WWW::http::Header - Module for GT::WWW::http request/response headers.</title>
|
||||
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
||||
|
||||
<style type="text/css">
|
||||
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
||||
/* $MVD$:fontset("Arial","Arial") */
|
||||
/* $MVD$:fontset("Arial Black","Arial Black") */
|
||||
/* $MVD$:fontset("Algerian","Algerian") */
|
||||
|
||||
|
||||
body {
|
||||
background-color: white;
|
||||
font-family: Verdana, Arial, sans-serif;
|
||||
font-size: small;
|
||||
color: black;
|
||||
}
|
||||
|
||||
|
||||
p {
|
||||
background-color : white;
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
h1 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : medium;
|
||||
background-color : white;
|
||||
color : maroon;
|
||||
}
|
||||
|
||||
|
||||
h2 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : medium;
|
||||
font-weight : bold;
|
||||
color : blue;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
h3 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : medium;
|
||||
color : black;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
h4 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : small;
|
||||
color : maroon;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
h5 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : small;
|
||||
color : blue;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
h6 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : small;
|
||||
color : black;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
ul {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
ol {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
dl {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
li {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
th {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
td {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
dl {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
dd {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
dt {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
code {
|
||||
font-family : Courier;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
pre {
|
||||
font-family : Courier;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
.mvd-H1 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : 14.0pt;
|
||||
background-color : transparent;
|
||||
background-image : none;
|
||||
color : maroon;
|
||||
}
|
||||
|
||||
|
||||
.mvd-H2 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : 12.0pt;
|
||||
color : blue;
|
||||
}
|
||||
|
||||
|
||||
p.indent {
|
||||
font-family : "Verdana, Arial, sans-serif";
|
||||
list-style-type : circle;
|
||||
list-style-position : inside;
|
||||
color : black;
|
||||
margin-left : 16.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-P-indent {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
list-style-type : circle;
|
||||
list-style-position : inside;
|
||||
color : black;
|
||||
margin-left : 16.0pt;
|
||||
}
|
||||
|
||||
|
||||
pre.programlisting {
|
||||
font-size : 9.0pt;
|
||||
list-style-type : disc;
|
||||
margin-left : 16.0pt;
|
||||
margin-top : -14.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-PRE-programlisting {
|
||||
font-size : 9.0pt;
|
||||
list-style-type : disc;
|
||||
margin-left : 16.0pt;
|
||||
margin-top : -14.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-PRE {
|
||||
font-size : 9.0pt;
|
||||
}
|
||||
|
||||
|
||||
p.note {
|
||||
margin-left : 28.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-P-note {
|
||||
margin-left : 28.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-H4 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : normal;
|
||||
font-size : 9.0pt;
|
||||
color : black;
|
||||
margin-left : 6.0pt;
|
||||
margin-top : -14.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-P {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : 10.0pt;
|
||||
color : black;
|
||||
}
|
||||
|
||||
.mvd-BODY {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
p.indentnobullet {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
list-style-type : none;
|
||||
}
|
||||
|
||||
|
||||
.mvd-P-indentnobullet {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
list-style-type : none;
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head>
|
||||
|
||||
<body style="background-color: white">
|
||||
|
||||
<p><a name="__index__"></a></p>
|
||||
<!-- INDEX BEGIN -->
|
||||
|
||||
<ul>
|
||||
|
||||
<li><a href="#name">NAME</a></li>
|
||||
<li><a href="#synopsis">SYNOPSIS</a></li>
|
||||
<li><a href="#description">DESCRIPTION</a></li>
|
||||
<li><a href="#methods">METHODS</a></li>
|
||||
<ul>
|
||||
|
||||
<li><a href="#header">header</a></li>
|
||||
<li><a href="#header_words">header_words</a></li>
|
||||
<li><a href="#split_words">split_words</a></li>
|
||||
<li><a href="#contains">contains</a></li>
|
||||
<li><a href="#join_words">join_words</a></li>
|
||||
<li><a href="#delete_header_word">delete_header_word</a></li>
|
||||
<li><a href="#delete_header">delete_header</a></li>
|
||||
<li><a href="#format_headers">format_headers</a></li>
|
||||
<li><a href="#clear_headers">clear_headers</a></li>
|
||||
</ul>
|
||||
|
||||
<li><a href="#see_also">SEE ALSO</a></li>
|
||||
<li><a href="#maintainer">MAINTAINER</a></li>
|
||||
<li><a href="#copyright">COPYRIGHT</a></li>
|
||||
<li><a href="#version">VERSION</a></li>
|
||||
</ul>
|
||||
<!-- INDEX END -->
|
||||
|
||||
<hr />
|
||||
<p>
|
||||
</p>
|
||||
<h1><a name="name">NAME</a></h1>
|
||||
<p>GT::WWW::http::Header - Module for GT::WWW::http request/response headers.</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
||||
<p>Typically:</p>
|
||||
<pre>
|
||||
# Assuming $www is a GT::WWW::http object
|
||||
my $request_header = $www->header;</pre>
|
||||
<pre>
|
||||
# Set a header:
|
||||
$request_header->header('Some-Http-Header' => 'Header value');</pre>
|
||||
<pre>
|
||||
# After making a request:
|
||||
my $response_header = $www->response->header;
|
||||
# -- or --
|
||||
my $response_header = $response->header; # $response is the return of, e.g. $www->get</pre>
|
||||
<p>Much more advanced headers can be set and determined, using the various methods
|
||||
available as described below.</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="description">DESCRIPTION</a></h1>
|
||||
<p>This module provides an easy to use yet powerful header retrieval/manipulation
|
||||
object suitable for most HTTP headers.</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="methods">METHODS</a></h1>
|
||||
<p>First, a note about the methods described which add/change/delete headers: such
|
||||
methods should only be called on a request header, and only before making a
|
||||
request. Although nothing prevents you from making changes to the request
|
||||
header after having made the request, or from changing the headers of a
|
||||
response header object, such behaviour should be considered very bad practise
|
||||
and is <strong>strongly</strong> discouraged.</p>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="header">header</a></h2>
|
||||
<p>This is the most commonly used method as it is used both to add and retrieve
|
||||
headers, depending on its usage. The examples below assume the following
|
||||
header:</p>
|
||||
<pre>
|
||||
Date: Sun, 12 Jan 2003 08:21:21 GMT
|
||||
Server: Apache
|
||||
Keep-Alive: timeout=15, max=100
|
||||
Connection: Keep-Alive
|
||||
Content-Type: text/html
|
||||
Content-Encoding: gzip
|
||||
Content-Length: 3215
|
||||
X-Foo: bar1
|
||||
X-Foo: bar2, bar3</pre>
|
||||
<p>With no arguments, a list of all the header names is returned. Given the
|
||||
example, the following list would be returned:</p>
|
||||
<pre>
|
||||
('Date', 'Server', 'Keep-Alive', 'Connection', 'Content-Type', 'Content-Encoding', 'Content-Length', 'X-Foo', 'X-Foo')</pre>
|
||||
<p>With a single argument, a list of <code>value(s)</code> for headers of that name are
|
||||
returned. In scalar context, only the first value is returned. In list
|
||||
context, a list of all values is returned. Note that the header named passed
|
||||
in is case-insensitive.</p>
|
||||
<pre>
|
||||
my $server = $header->header('server'); # returns 'Apache'
|
||||
my $foo = $header->header('X-Foo'); # returns 'bar1'
|
||||
my @foo = $header->header('x-Foo'); # returns ('bar1', 'bar2, bar3')</pre>
|
||||
<p>Finally, when more than one argument is provided, header values are set. At
|
||||
its simplest level, it takes a list of key => value pairs (NOT a hash, since
|
||||
duplicate keys are possible) of headers to set. So, to set the headers
|
||||
'Server' and 'Content-Length' above at once, you could call:</p>
|
||||
<pre>
|
||||
$header->header(Server => 'Apache', 'Content-Length' => 3215);</pre>
|
||||
<p>Or, if you prefer:</p>
|
||||
<pre>
|
||||
$header->header(Server => 'Apache');
|
||||
$header->header('Content-Length' => 3215);</pre>
|
||||
<p>Note that the order in which headers are added is preserved, for times when the
|
||||
order of headers is important.</p>
|
||||
<p><strong>WARNING</strong>: Before reading the below information, you should first know that it
|
||||
describes advanced usage of the <code>header()</code> method and requires have a grasp of
|
||||
the intricacies of HTTP headers; the following is _not_ required knowledge for
|
||||
typical GT::WWW use.</p>
|
||||
<p>Consider the above Keep-Alive header an example. Instead of specifying:</p>
|
||||
<pre>
|
||||
$header->header('Keep-Alive' => 'timeout=15, max=100');</pre>
|
||||
<p>you could alternately write it as:</p>
|
||||
<pre>
|
||||
$header->header('Keep-Alive' => [timeout => 15, max => 100]);</pre>
|
||||
<p>This allows you a more pragmatic approach when you already have some sort of
|
||||
data structure of the header options. You can go a step further with this, by
|
||||
specifying <code>undef</code> as the value:</p>
|
||||
<pre>
|
||||
# Set the second X-Foo header in the example:
|
||||
$header->header('X-Foo' => [bar2 => undef, bar3 => undef]);</pre>
|
||||
<p><code>header()</code> also allows you to set values such as:</p>
|
||||
<pre>
|
||||
image/gif;q=0.2</pre>
|
||||
<p>As can be seen in this example:</p>
|
||||
<pre>
|
||||
Accept: image/png,image/jpeg,image/gif;q=0.2,*/*;q=0.1</pre>
|
||||
<p>To do so, specify the suboption value as another array reference. The first
|
||||
element of the array reference is usually undef, while the remaining are the
|
||||
k=v pairs in the segment. So, in the above header, the 'image/gif;q=0.2' section
|
||||
would be specified as:</p>
|
||||
<pre>
|
||||
'image/gif' => [undef, q => 0.2]</pre>
|
||||
<p>(If a segment such as ``foo=bar;bar=foo'' is ever needed, the <code>undef</code> would be
|
||||
changed to <code>"bar"</code>.)</p>
|
||||
<p>So, piecing it all together, the Accept header shown above could be specified
|
||||
like this:</p>
|
||||
<pre>
|
||||
$header->header(
|
||||
Accept => [
|
||||
'image/png' => undef,
|
||||
'image/jpeg' => undef,
|
||||
'image/gif' => [undef, q => 0.2],
|
||||
'*/*' => [undef, q => 0.1]
|
||||
]
|
||||
);</pre>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="header_words">header_words</a></h2>
|
||||
<p>When you need to see it a header value contains a particular ``word'', this
|
||||
method is the one to use. As an example, consider this header:</p>
|
||||
<pre>
|
||||
X-Foo: bar, bar2, bar3</pre>
|
||||
<p>In order to determine whether or not ``bar2'' has been specified as an X-Foo
|
||||
value, you could attempt some sort of regex - or you could just call this
|
||||
method. The return value splits up the header in such a way as to be useful to
|
||||
determine the exact information contained within the header.</p>
|
||||
<p>The method takes a case-insensitive header name, just like the single-argument
|
||||
form of header().</p>
|
||||
<p>A even-numbered hash-<em>like</em> list is always returned - though each element of
|
||||
that list depends on the content of the header. First of all, if the header
|
||||
specified does not exist, you'll get an empty list back.</p>
|
||||
<p>Assuming that the header does exist, it will first be broken up by <code>,</code>.</p>
|
||||
<p>The even-indexed (0, 2, 4, ...) elements of the list are the keys, while the
|
||||
odd numbered elements are the values associated with those keys - or undef if
|
||||
there is no value (as above; an example with values is shown below).</p>
|
||||
<p>So, using the above X-Foo header example, calling this method with <code>'X-Foo'</code>
|
||||
as an argument would give you back the list:</p>
|
||||
<pre>
|
||||
(bar => undef, bar2 => undef, bar3 => undef)</pre>
|
||||
<p>Getting a little more complicated, consider the following header:</p>
|
||||
<pre>
|
||||
X-Foo: bar, bar2=foo, bar3</pre>
|
||||
<p>Because of the ``=foo'' part, the list returned would now be:</p>
|
||||
<pre>
|
||||
(bar => undef, bar2 => "foo", bar3 => undef)</pre>
|
||||
<p>Quoting of values is also permitted, so the following would be parsed correctly
|
||||
with <code>'1;2,3=4"5\6'</code> being the value of bar2:</p>
|
||||
<pre>
|
||||
X-Foo: bar, bar2="1;2,3=4\"5\\6", bar3</pre>
|
||||
<p>Getting more complicated, this method also handles complex values containing
|
||||
more than one piece of information. A good example of this is in content type
|
||||
weighting used by most browsers. As a real life example (generated by
|
||||
the Phoenix web browser):</p>
|
||||
<pre>
|
||||
Accept: video/x-mng,image/png,image/jpeg,image/gif;q=0.2,*/*;q=0.1</pre>
|
||||
<p>Working that into the X-Foo example, consider this header:</p>
|
||||
<pre>
|
||||
X-Foo: bar, bar2=foo, bar3;foo1=24;foo2=10</pre>
|
||||
<p>In this case, the value for bar3 will become an array reference to handle the
|
||||
multiple pieces of information in the third part:</p>
|
||||
<pre>
|
||||
(bar => undef, bar2 => "foo", bar3 => [undef, foo1 => 24, foo2 => 10])</pre>
|
||||
<p>(If you've read the advanced section of the <a href="#header"><code>header()</code></a>
|
||||
documentation, and this looks familiar, you're right - the return value of this
|
||||
function, if put in an array reference, is completely compatible with a
|
||||
<code>header()</code> value.)</p>
|
||||
<p>The <code>undef</code> value at the beginning of the array reference is rarely anything other
|
||||
than <code>undef</code>, but it <em>could</em> be, if a header such as this were encountered:</p>
|
||||
<pre>
|
||||
X-Foo: bar=foo,foo1=10</pre>
|
||||
<p>That would return:</p>
|
||||
<pre>
|
||||
(bar => ["foo", foo1 => 10])</pre>
|
||||
<p>One additional thing to note is that <code>header_words()</code> returns the header words
|
||||
for <strong>all</strong> matching headers. Thus if the following two headers were set:</p>
|
||||
<pre>
|
||||
X-Foo: bar, bar2=foo
|
||||
X-Foo: bar3</pre>
|
||||
<p>You would get the same return as if this header was set (shown above):</p>
|
||||
<pre>
|
||||
X-Foo: bar, bar2=foo, bar3</pre>
|
||||
<p>A good example usage of this is for a file download. To get the filename, you
|
||||
would do something like:</p>
|
||||
<pre>
|
||||
my %cd = $header->header_words('Content-Disposition');
|
||||
my $filename;
|
||||
if ($cd{filename}) { $filename = $cd{filename} }
|
||||
else { $filename = "unknown" }</pre>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="split_words">split_words</a></h2>
|
||||
<p>This can be called as object method, class method, or function - it takes a
|
||||
single argument, a string, which it proceeds to split up as described for the
|
||||
above <code>header_words()</code> method. Note that this knows nothing about header names -
|
||||
it simply knows how to break a header value into the above format.</p>
|
||||
<p>This method is used internally by header_words(), but can be used separately if
|
||||
desired.</p>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="contains">contains</a></h2>
|
||||
<p>This method takes two arguments: a header, and a header word. It returns true
|
||||
if the header word passed is found in the header specified. For example, the
|
||||
following would return true:</p>
|
||||
<pre>
|
||||
$header->contains('X-Foo' => 'bar2')</pre>
|
||||
<p>for any of these headers:</p>
|
||||
<pre>
|
||||
X-Foo: bar2
|
||||
X-Foo: bar, bar2, bar3
|
||||
X-Foo: bar, bar2=10, bar3
|
||||
X-Foo: bar, bar2=10;q=0.3, bar3</pre>
|
||||
<p>but not for either of these:</p>
|
||||
<pre>
|
||||
X-Foo: bar, bar3=bar2
|
||||
X-Foo: bar, bar3;bar2=10</pre>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="join_words">join_words</a></h2>
|
||||
<p><code>join_words()</code> does the opposite of split_words(). That is, it takes a value such
|
||||
as might be returned by split_words(), and joins it up properly, quoting if
|
||||
necessary. This is called internally when creating the actual header, and can
|
||||
be called separately at a method or function if desired.</p>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="delete_header_word">delete_header_word</a></h2>
|
||||
<p>This takes a header and header word, and proceeds to remove any occurances of
|
||||
the header word from the header specified.</p>
|
||||
<p>After calling:</p>
|
||||
<pre>
|
||||
$header->delete_header_word('X-Foo', 'bar2');</pre>
|
||||
<p>this header:</p>
|
||||
<pre>
|
||||
X-Foo: bar, bar2;foo=bar, bar3</pre>
|
||||
<p>would become:</p>
|
||||
<pre>
|
||||
X-Foo: bar, bar3</pre>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="delete_header">delete_header</a></h2>
|
||||
<p>This takes a list of header names. The headers specified are completely
|
||||
removed.
|
||||
</p>
|
||||
<pre>
|
||||
|
||||
=head2 replace_header</pre>
|
||||
<p>This 2 or more arguments in exactly the same way as header(), however all the
|
||||
specified headers are deleted (assuming they exist) before being readded.</p>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="format_headers">format_headers</a></h2>
|
||||
<p>This returns a properly formatted (lines are CRLF delimited) header. If you
|
||||
use the header as a string (i.e. <code>"$header"</code>), this method will be internally
|
||||
called, and so generally does not need to be called directly.</p>
|
||||
<p>The returned string has the final blank line that identifies the end of the
|
||||
header.</p>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="clear_headers">clear_headers</a></h2>
|
||||
<p>This deletes all headers.</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="see_also">SEE ALSO</a></h1>
|
||||
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http.html">the GT::WWW::http manpage</a>
|
||||
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html">the GT::WWW manpage</a>
|
||||
RFC 2616: <a href="http://www.ietf.org/rfc/rfc2616.txt">http://www.ietf.org/rfc/rfc2616.txt</a></p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="maintainer">MAINTAINER</a></h1>
|
||||
<p>Jason Rhinelander</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="copyright">COPYRIGHT</a></h1>
|
||||
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
||||
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="version">VERSION</a></h1>
|
||||
<p>Revision: $Id: Header.pm,v 1.8 2004/02/17 01:33:08 jagerman Exp $</p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
478
site/glist/templates/help/GT/WWW/http/Response.html
Normal file
478
site/glist/templates/help/GT/WWW/http/Response.html
Normal file
@ -0,0 +1,478 @@
|
||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<head>
|
||||
<title>GT::WWW::http::Response::Status - Overloaded
|
||||
response objects for HTTP request data.</title>
|
||||
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
||||
|
||||
<style type="text/css">
|
||||
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
||||
/* $MVD$:fontset("Arial","Arial") */
|
||||
/* $MVD$:fontset("Arial Black","Arial Black") */
|
||||
/* $MVD$:fontset("Algerian","Algerian") */
|
||||
|
||||
|
||||
body {
|
||||
background-color: white;
|
||||
font-family: Verdana, Arial, sans-serif;
|
||||
font-size: small;
|
||||
color: black;
|
||||
}
|
||||
|
||||
|
||||
p {
|
||||
background-color : white;
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
h1 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : medium;
|
||||
background-color : white;
|
||||
color : maroon;
|
||||
}
|
||||
|
||||
|
||||
h2 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : medium;
|
||||
font-weight : bold;
|
||||
color : blue;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
h3 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : medium;
|
||||
color : black;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
h4 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : small;
|
||||
color : maroon;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
h5 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : small;
|
||||
color : blue;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
h6 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : small;
|
||||
color : black;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
ul {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
ol {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
dl {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
li {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
th {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
td {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
dl {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
dd {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
dt {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
code {
|
||||
font-family : Courier;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
|
||||
pre {
|
||||
font-family : Courier;
|
||||
font-size : small;
|
||||
color : black;
|
||||
}
|
||||
|
||||
.mvd-H1 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : bold;
|
||||
font-size : 14.0pt;
|
||||
background-color : transparent;
|
||||
background-image : none;
|
||||
color : maroon;
|
||||
}
|
||||
|
||||
|
||||
.mvd-H2 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : 12.0pt;
|
||||
color : blue;
|
||||
}
|
||||
|
||||
|
||||
p.indent {
|
||||
font-family : "Verdana, Arial, sans-serif";
|
||||
list-style-type : circle;
|
||||
list-style-position : inside;
|
||||
color : black;
|
||||
margin-left : 16.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-P-indent {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
list-style-type : circle;
|
||||
list-style-position : inside;
|
||||
color : black;
|
||||
margin-left : 16.0pt;
|
||||
}
|
||||
|
||||
|
||||
pre.programlisting {
|
||||
font-size : 9.0pt;
|
||||
list-style-type : disc;
|
||||
margin-left : 16.0pt;
|
||||
margin-top : -14.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-PRE-programlisting {
|
||||
font-size : 9.0pt;
|
||||
list-style-type : disc;
|
||||
margin-left : 16.0pt;
|
||||
margin-top : -14.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-PRE {
|
||||
font-size : 9.0pt;
|
||||
}
|
||||
|
||||
|
||||
p.note {
|
||||
margin-left : 28.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-P-note {
|
||||
margin-left : 28.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-H4 {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-weight : normal;
|
||||
font-size : 9.0pt;
|
||||
color : black;
|
||||
margin-left : 6.0pt;
|
||||
margin-top : -14.0pt;
|
||||
}
|
||||
|
||||
|
||||
.mvd-P {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
font-size : 10.0pt;
|
||||
color : black;
|
||||
}
|
||||
|
||||
.mvd-BODY {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
background-color : white;
|
||||
}
|
||||
|
||||
|
||||
p.indentnobullet {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
list-style-type : none;
|
||||
}
|
||||
|
||||
|
||||
.mvd-P-indentnobullet {
|
||||
font-family : Verdana, Arial, sans-serif;
|
||||
list-style-type : none;
|
||||
}
|
||||
</style>
|
||||
|
||||
|
||||
</head>
|
||||
|
||||
<body style="background-color: white">
|
||||
|
||||
<p><a name="__index__"></a></p>
|
||||
<!-- INDEX BEGIN -->
|
||||
|
||||
<ul>
|
||||
|
||||
<li><a href="#name">NAME</a></li>
|
||||
<li><a href="#synopsis">SYNOPSIS</a></li>
|
||||
<li><a href="#description">DESCRIPTION</a></li>
|
||||
<li><a href="#content">CONTENT</a></li>
|
||||
<li><a href="#methods">METHODS</a></li>
|
||||
<ul>
|
||||
|
||||
<li><a href="#content">content</a></li>
|
||||
<li><a href="#status">status</a></li>
|
||||
<li><a href="#header">header</a></li>
|
||||
</ul>
|
||||
|
||||
<li><a href="#caveats">CAVEATS</a></li>
|
||||
<li><a href="#see_also">SEE ALSO</a></li>
|
||||
<li><a href="#maintainer">MAINTAINER</a></li>
|
||||
<li><a href="#copyright">COPYRIGHT</a></li>
|
||||
<li><a href="#version">VERSION</a></li>
|
||||
</ul>
|
||||
<!-- INDEX END -->
|
||||
|
||||
<hr />
|
||||
<p>
|
||||
</p>
|
||||
<h1><a name="name">NAME</a></h1>
|
||||
<p>GT::WWW::http::Response and GT::WWW::http::Response::Status - Overloaded
|
||||
response objects for HTTP request data.</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
||||
<pre>
|
||||
# ($www is continued from GT::WWW::http SYNOPSIS)</pre>
|
||||
<pre>
|
||||
my $response = $www->get(); # or post(), or head()
|
||||
# -- or, after having called get(), post() or head(): --
|
||||
my $response = $www->response();</pre>
|
||||
<pre>
|
||||
my $status = $response->status();</pre>
|
||||
<pre>
|
||||
my $content = "$response";
|
||||
my $response_code = int($status); # i.e. 200, 404, 500
|
||||
my $response_str = "$status"; # i.e. 'OK', 'Not Found', 'Internal Server Error'
|
||||
if ($status) { # True for 2xx requests, false otherwise (e.g. 404, 500, etc.)
|
||||
...
|
||||
}</pre>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="description">DESCRIPTION</a></h1>
|
||||
<p>GT::WWW::http::Response objects are returned by the <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html#get"><code>get()</code></a>,
|
||||
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html#post"><code>post()</code></a>, and <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html#head"><code>head()</code></a> methods of GT::WWW
|
||||
HTTP requests (and derivatives - i.e. HTTPS), or by calling
|
||||
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http.html#response"><code>response()</code></a> after having made such a request. The
|
||||
objects are overloaded in order to provide a simple interface to the response,
|
||||
while still having all the information available.</p>
|
||||
<p>A response object always returns true in boolean context, allowing you to do
|
||||
things like <code>$www->get($url) or die;</code> - even when a page is empty, or
|
||||
contains just '0'.</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="content">CONTENT</a></h1>
|
||||
<p>In addition to the methods described below, the way to simply access the data
|
||||
returned by the server is to simply use it like a string - for example,
|
||||
printing it, concatenating it with another string, or quoting it.</p>
|
||||
<p>You should, however, take note that when using the <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html#chunk"><code>chunk()</code></a>
|
||||
option for an HTTP request, the content will not be available.</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="methods">METHODS</a></h1>
|
||||
<p>For simple requests, often the content alone is enough. The following methods
|
||||
are used to determine any other information available about the response.</p>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="content">content</a></h2>
|
||||
<p>Returns the content of the HTTP response. Note that this returns the exact
|
||||
same value as using the object in double quotes.</p>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="status">status</a></h2>
|
||||
<p>Returns the response status object for the request. This object provides three
|
||||
pieces of information, and has no public methods. Instead, the data is
|
||||
retrieved based on the context of the object.</p>
|
||||
<pre>
|
||||
my $status = $response->status;</pre>
|
||||
<p>(N.B. Though the examples below use a <code>$status</code> variable, there is no reason
|
||||
they couldn't be written to use <code>$response->status</code> instead.)</p>
|
||||
<dl>
|
||||
<dt><strong><a name="item_numeric_status">numeric status</a></strong><br />
|
||||
</dt>
|
||||
<dd>
|
||||
The numeric status of an HTTP request (e.g. 200, 404, 500) is available simply
|
||||
by using the status object as a number.
|
||||
</dd>
|
||||
<dd>
|
||||
<pre>
|
||||
my $numeric_status = int $status;</pre>
|
||||
</dd>
|
||||
<p></p>
|
||||
<dt><strong><a name="item_string_status">string status</a></strong><br />
|
||||
</dt>
|
||||
<dd>
|
||||
The string status of an HTTP request (e.g. ``OK'', ``Not Found'', ``Internal Server
|
||||
Error'') is available by using the status object as a string (e.g. printing it,
|
||||
or concatenating it with another string).
|
||||
</dd>
|
||||
<dd>
|
||||
<pre>
|
||||
# Assign the status string to a variable:
|
||||
my $status_string = "$status";</pre>
|
||||
</dd>
|
||||
<dd>
|
||||
<pre>
|
||||
# Print out the status string:
|
||||
print $status;</pre>
|
||||
</dd>
|
||||
<dd>
|
||||
<pre>
|
||||
# To get a string such as "500 Internal Server Error":
|
||||
my $string = int($status) . " " . $status;</pre>
|
||||
</dd>
|
||||
<p></p>
|
||||
<dt><strong><a name="item_boolean_status">boolean status</a></strong><br />
|
||||
</dt>
|
||||
<dd>
|
||||
In order to quickly determine whether or not a request was successful, you can
|
||||
use the status object in a boolean context.
|
||||
</dd>
|
||||
<dd>
|
||||
<p>Success is determined by the numeric status of the response. Any 2xx status
|
||||
(usually 200 OK, but there are others) counts as a successful response, while
|
||||
any other status counts as a failure.</p>
|
||||
</dd>
|
||||
<dd>
|
||||
<pre>
|
||||
if ($status) { print "Request successful!" }
|
||||
else { print "Request failed!" }</pre>
|
||||
</dd>
|
||||
<p></p></dl>
|
||||
<p>
|
||||
</p>
|
||||
<h2><a name="header">header</a></h2>
|
||||
<p>This method, called without arguments, returns the
|
||||
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Header.html">header</a> object for the response.</p>
|
||||
<pre>
|
||||
my $header = $response->header;</pre>
|
||||
<p>If this method is called with arguments, those arguments are passed to the
|
||||
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Header.html#header"><code>header()</code></a> method of the header object. This
|
||||
allows this useful shortcut:</p>
|
||||
<pre>
|
||||
my $some_header_value = $response->header("Some-Header");</pre>
|
||||
<p>instead of the alternative (which also works):</p>
|
||||
<pre>
|
||||
my $some_header_value = $response->header->header("Some-Header");</pre>
|
||||
<p>Information on header object usage is contained in <a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Header.html">the GT::WWW::http::Header manpage</a>.</p>
|
||||
<p>Note that although a header object allows for header manipulation, changing the
|
||||
headers of a response object should be considered bad practise, and is strongly
|
||||
discouraged.</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="caveats">CAVEATS</a></h1>
|
||||
<p>Although the response object _works_ like a string, keep in mind that it is
|
||||
still an object, and thus a reference. If you intend to pass the data to
|
||||
another subroutine expecting a string, it is recommended that you force the
|
||||
content into string form, either by quoting the variable (<code>"$var"</code>) or by
|
||||
calling the <code>content()</code> method (<code>$var->content</code>). Not doing so can lead to
|
||||
unexpected results, particularly in cases where another subroutine may
|
||||
differentiate between a string and a reference, and not just use the value as a
|
||||
string.</p>
|
||||
<p>Also, in terms of speed, obtaining the content (not the object) into another
|
||||
variable (either via <code>"$var"</code> or <code>$var->content</code>) can make quite a
|
||||
substantial difference when several string comparison operations are performed.
|
||||
The reason is simply that every time the object is used is a string, the
|
||||
content method is called, which can amount to a significant slowdown.</p>
|
||||
<p>Although string operations that change the string (i.e. s///) appear to work,
|
||||
they in fact clobber the reference and turn your variable into an ordinary
|
||||
string. This should not be done - if the string needs to be modified, take a
|
||||
copy of it first, and modify the copy.</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="see_also">SEE ALSO</a></h1>
|
||||
<p><a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW.html">the GT::WWW manpage</a>
|
||||
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http.html">the GT::WWW::http manpage</a>
|
||||
<a href="glist.cgi?do=admin_gtdoc&topic=/GT/WWW/http/Header.html">the GT::WWW::http::Header manpage</a>
|
||||
RFC 2616: <a href="http://www.ietf.org/rfc/rfc2616.txt">http://www.ietf.org/rfc/rfc2616.txt</a></p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="maintainer">MAINTAINER</a></h1>
|
||||
<p>Jason Rhinelander</p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="copyright">COPYRIGHT</a></h1>
|
||||
<p>Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved.
|
||||
<a href="http://www.gossamer-threads.com/">http://www.gossamer-threads.com/</a></p>
|
||||
<p>
|
||||
</p>
|
||||
<hr />
|
||||
<h1><a name="version">VERSION</a></h1>
|
||||
<p>Revision: $Id: Response.pm,v 1.8 2004/08/04 19:23:07 jagerman Exp $</p>
|
||||
|
||||
</body>
|
||||
|
||||
</html>
|
||||
Reference in New Issue
Block a user