📄 headers.html
字号:
<?xml version="1.0" ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<!-- saved from url=(0017)http://localhost/ -->
<script language="JavaScript" src="../../displayToc.js"></script>
<script language="JavaScript" src="../../tocParas.js"></script>
<script language="JavaScript" src="../../tocTab.js"></script>
<link rel="stylesheet" type="text/css" href="../../scineplex.css">
<title>HTTP::Headers - Class encapsulating HTTP Message headers</title>
<link rel="stylesheet" href="../../Active.css" type="text/css" />
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:" />
</head>
<body>
<script>writelinks('__top__',2);</script>
<h1><a>HTTP::Headers - Class encapsulating HTTP Message headers</a></h1>
<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="#convenience_methods">CONVENIENCE METHODS</a></li>
<li><a href="#noncanonicalized_field_names">NON-CANONICALIZED FIELD NAMES</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<!-- INDEX END -->
<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>HTTP::Headers - Class encapsulating HTTP Message headers</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
<span class="keyword">require</span> <span class="variable">HTTP::Headers</span><span class="operator">;</span>
<span class="variable">$h</span> <span class="operator">=</span> <span class="variable">HTTP::Headers</span><span class="operator">-></span><span class="variable">new</span><span class="operator">;</span>
</pre>
<pre>
<span class="variable">$h</span><span class="operator">-></span><span class="variable">header</span><span class="operator">(</span><span class="string">'Content-Type'</span> <span class="operator">=></span> <span class="string">'text/plain'</span><span class="operator">);</span> <span class="comment"># set</span>
<span class="variable">$ct</span> <span class="operator">=</span> <span class="variable">$h</span><span class="operator">-></span><span class="variable">header</span><span class="operator">(</span><span class="string">'Content-Type'</span><span class="operator">);</span> <span class="comment"># get</span>
<span class="variable">$h</span><span class="operator">-></span><span class="variable">remove_header</span><span class="operator">(</span><span class="string">'Content-Type'</span><span class="operator">);</span> <span class="comment"># delete</span>
</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>The <code>HTTP::Headers</code> class encapsulates HTTP-style message headers.
The headers consist of attribute-value pairs also called fields, which
may be repeated, and which are printed in a particular order. The
field names are cases insensitive.</p>
<p>Instances of this class are usually created as member variables of the
<code>HTTP::Request</code> and <code>HTTP::Response</code> classes, internal to the
library.</p>
<p>The following methods are available:</p>
<dl>
<dt><strong><a name="item_new">$h = HTTP::Headers->new</a></strong>
<dd>
<p>Constructs a new <code>HTTP::Headers</code> object. You might pass some initial
attribute-value pairs as parameters to the constructor. <em>E.g.</em>:</p>
</dd>
<dd>
<pre>
<span class="variable">$h</span> <span class="operator">=</span> <span class="variable">HTTP::Headers</span><span class="operator">-></span><span class="variable">new</span><span class="operator">(</span>
<span class="string">Date</span> <span class="operator">=></span> <span class="string">'Thu, 03 Feb 1994 00:00:00 GMT'</span><span class="operator">,</span>
<span class="string">Content_Type</span> <span class="operator">=></span> <span class="string">'text/html; version=3.2'</span><span class="operator">,</span>
<span class="string">Content_Base</span> <span class="operator">=></span> <span class="string">'http://www.perl.org/'</span><span class="operator">);</span>
</pre>
</dd>
<dd>
<p>The constructor arguments are passed to the <a href="#item_header"><code>header</code></a> method which is
described below.</p>
</dd>
</li>
<dt><strong><a name="item_clone">$h->clone</a></strong>
<dd>
<p>Returns a copy of this <code>HTTP::Headers</code> object.</p>
</dd>
</li>
<dt><strong><a name="item_header">$h->header( $field )</a></strong>
<dt><strong>$h->header( $field => $value, ... )</strong>
<dd>
<p>Get or set the value of one or more header fields. The header field
name ($field) is not case sensitive. To make the life easier for perl
users who wants to avoid quoting before the => operator, you can use
'_' as a replacement for '-' in header names.</p>
</dd>
<dd>
<p>The <a href="#item_header"><code>header()</code></a> method accepts multiple ($field => $value) pairs, which
means that you can update several fields with a single invocation.</p>
</dd>
<dd>
<p>The $value argument may be a plain string or a reference to an array
of strings for a multi-valued field. If the $value is provided as
<a href="../../lib/Pod/perlfunc.html#item_undef"><code>undef</code></a> then the field is removed. If the $value is not given, then
that header field will remain unchanged.</p>
</dd>
<dd>
<p>The old value (or values) of the last of the header fields is returned.
If no such field exists <a href="../../lib/Pod/perlfunc.html#item_undef"><code>undef</code></a> will be returned.</p>
</dd>
<dd>
<p>A multi-valued field will be returned as separate values in list
context and will be concatenated with ", " as separator in scalar
context. The HTTP spec (RFC 2616) promise that joining multiple
values in this way will not change the semantic of a header field, but
in practice there are cases like old-style Netscape cookies (see
<a href="../../lib/HTTP/Cookies.html">the HTTP::Cookies manpage</a>) where "," is used as part of the syntax of a single
field value.</p>
</dd>
<dd>
<p>Examples:</p>
</dd>
<dd>
<pre>
<span class="variable">$header</span><span class="operator">-></span><span class="variable">header</span><span class="operator">(</span><span class="string">MIME_Version</span> <span class="operator">=></span> <span class="string">'1.0'</span><span class="operator">,</span>
<span class="string">User_Agent</span> <span class="operator">=></span> <span class="string">'My-Web-Client/0.01'</span><span class="operator">);</span>
<span class="variable">$header</span><span class="operator">-></span><span class="variable">header</span><span class="operator">(</span><span class="string">Accept</span> <span class="operator">=></span> <span class="string">"text/html, text/plain, image/*"</span><span class="operator">);</span>
<span class="variable">$header</span><span class="operator">-></span><span class="variable">header</span><span class="operator">(</span><span class="string">Accept</span> <span class="operator">=></span> <span class="operator">[</span><span class="string">qw(text/html text/plain image/*)</span><span class="operator">]</span><span class="operator">);</span>
<span class="variable">@accepts</span> <span class="operator">=</span> <span class="variable">$header</span><span class="operator">-></span><span class="variable">header</span><span class="operator">(</span><span class="string">'Accept'</span><span class="operator">);</span> <span class="comment"># get multiple values</span>
<span class="variable">$accepts</span> <span class="operator">=</span> <span class="variable">$header</span><span class="operator">-></span><span class="variable">header</span><span class="operator">(</span><span class="string">'Accept'</span><span class="operator">);</span> <span class="comment"># get values as a single string</span>
</pre>
</dd>
</li>
<dt><strong><a name="item_push_header">$h->push_header( $field => $value )</a></strong>
<dd>
<p>Add a new field value for the specified header field. Previous values
for the same field are retained.</p>
</dd>
<dd>
<p>As for the <a href="#item_header"><code>header()</code></a> method, the field name ($field) is not case
sensitive and '_' can be used as a replacement for '-'.</p>
</dd>
<dd>
<p>The $value argument may be a scalar or a reference to a list of
scalars.</p>
</dd>
<dd>
<pre>
<span class="variable">$header</span><span class="operator">-></span><span class="variable">push_header</span><span class="operator">(</span><span class="string">Accept</span> <span class="operator">=></span> <span class="string">'image/jpeg'</span><span class="operator">);</span>
<span class="variable">$header</span><span class="operator">-></span><span class="variable">push_header</span><span class="operator">(</span><span class="string">Accept</span> <span class="operator">=></span> <span class="operator">[</span><span class="keyword">map</span> <span class="string">"image/$_"</span><span class="operator">,</span> <span class="string">qw(gif png tiff)</span><span class="operator">]</span><span class="operator">);</span>
</pre>
</dd>
</li>
<dt><strong><a name="item_init_header">$h->init_header( $field => $value )</a></strong>
<dd>
<p>Set the specified header to the given value, but only if no previous
value for that field is set.</p>
</dd>
<dd>
<p>The header field name ($field) is not case sensitive and '_'
can be used as a replacement for '-'.</p>
</dd>
<dd>
<p>The $value argument may be a scalar or a reference to a list of
scalars.</p>
</dd>
</li>
<dt><strong><a name="item_remove_header">$h->remove_header( $field, ... )</a></strong>
<dd>
<p>This function removes the header fields with the specified names.</p>
</dd>
<dd>
<p>The header field names ($field) are not case sensitive and '_'
can be used as a replacement for '-'.</p>
</dd>
<dd>
<p>The return value is the values of the fields removed. In scalar
context the number of fields removed is returned.</p>
</dd>
<dd>
<p>Note that if you pass in multiple field names then it is generally not
possible to tell which of the returned values belonged to which field.</p>
</dd>
</li>
<dt><strong><a name="item_remove_content_headers">$h->remove_content_headers</a></strong>
<dd>
<p>This will remove all the header fields used to describe the content of
a message. All header field names prefixed with <code>Content-</code> falls
into this category, as well as <code>Allow</code>, <code>Expires</code> and
<code>Last-Modified</code>. RFC 2616 denote these fields as <em>Entity Header
Fields</em>.</p>
</dd>
<dd>
<p>The return value is a new <code>HTTP::Headers</code> object that contains the
removed headers only.</p>
</dd>
</li>
<dt><strong><a name="item_clear">$h->clear</a></strong>
<dd>
<p>This will remove all header fields.</p>
</dd>
</li>
<dt><strong><a name="item_header_field_names">$h->header_field_names</a></strong>
<dd>
<p>Returns the list of distinct names for the fields present in the
header. The field names have case as suggested by HTTP spec, and the
names are returned in the recommended "Good Practice" order.</p>
</dd>
<dd>
<p>In scalar context return the number of distinct field names.</p>
</dd>
</li>
<dt><strong><a name="item_scan">$h->scan( \&process_header_field )</a></strong>
<dd>
<p>Apply a subroutine to each header field in turn. The callback routine
is called with two parameters; the name of the field and a single
value (a string). If a header field is multi-valued, then the
routine is called once for each value. The field name passed to the
callback routine has case as suggested by HTTP spec, and the headers
will be visited in the recommended "Good Practice" order.</p>
</dd>
<dd>
<p>Any return values of the callback routine are ignored. The loop can
be broken by raising an exception (<a href="../../lib/Pod/perlfunc.html#item_die"><code>die</code></a>), but the caller of <a href="#item_scan"><code>scan()</code></a>
would have to trap the exception itself.</p>
</dd>
</li>
<dt><strong><a name="item_as_string">$h->as_string</a></strong>
<dt><strong>$h->as_string( $eol )</strong>
<dd>
<p>Return the header fields as a formatted MIME header. Since it
internally uses the <a href="#item_scan"><code>scan</code></a> method to build the string, the result
will use case as suggested by HTTP spec, and it will follow
recommended "Good Practice" of ordering the header fields. Long header
values are not folded.</p>
</dd>
<dd>
<p>The optional $eol parameter specifies the line ending sequence to
use. The default is "\n". Embedded "\n" characters in header field
values will be substituted with this line ending sequence.</p>
</dd>
</li>
</dl>
<p>
</p>
<hr />
<h1><a name="convenience_methods">CONVENIENCE METHODS</a></h1>
<p>The most frequently used headers can also be accessed through the
following convenience methods. These methods can both be used to read
and to set the value of a header. The header value is set if you pass
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -