792 lines
17 KiB
HTML
792 lines
17 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of HTTP::Headers</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>HTTP::Headers</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::Headers - Class encapsulating HTTP Message headers
|
|
<A NAME="lbAC"> </A>
|
|
<H2>VERSION</H2>
|
|
|
|
|
|
|
|
version 6.22
|
|
<A NAME="lbAD"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
require HTTP::Headers;
|
|
$h = HTTP::Headers->new;
|
|
|
|
$h->header('Content-Type' => 'text/plain'); # set
|
|
$ct = $h->header('Content-Type'); # get
|
|
$h->remove_header('Content-Type'); # delete
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
The <TT>"HTTP::Headers"</TT> 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>
|
|
|
|
Instances of this class are usually created as member variables of the
|
|
<TT>"HTTP::Request"</TT> and <TT>"HTTP::Response"</TT> classes, internal to the
|
|
library.
|
|
<P>
|
|
|
|
The following methods are available:
|
|
<DL COMPACT>
|
|
<DT id="1">$h = HTTP::Headers->new<DD>
|
|
|
|
|
|
|
|
|
|
Constructs a new <TT>"HTTP::Headers"</TT> object. You might pass some initial
|
|
attribute-value pairs as parameters to the constructor. <I>E.g.</I>:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$h = HTTP::Headers->new(
|
|
Date => 'Thu, 03 Feb 1994 00:00:00 GMT',
|
|
Content_Type => 'text/html; version=3.2',
|
|
Content_Base => '<A HREF="http://www.perl.org/');">http://www.perl.org/');</A>
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The constructor arguments are passed to the <TT>"header"</TT> method which is
|
|
described below.
|
|
<DT id="2">$h->clone<DD>
|
|
|
|
|
|
|
|
|
|
Returns a copy of this <TT>"HTTP::Headers"</TT> object.
|
|
<DT id="3">$h->header( $field )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="4">$h->header( $field => $value )<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="5">$h->header( $f1 => $v1, $f2 => $v2, ... )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
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>
|
|
|
|
|
|
The <B>header()</B> method accepts multiple ($field => <TT>$value</TT>) pairs, which
|
|
means that you can update several fields with a single invocation.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>$value</TT> argument may be a plain string or a reference to an array
|
|
of strings for a multi-valued field. If the <TT>$value</TT> is provided as
|
|
<TT>"undef"</TT> then the field is removed. If the <TT>$value</TT> is not given, then
|
|
that header field will remain unchanged.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The old value (or values) of the last of the header fields is returned.
|
|
If no such field exists <TT>"undef"</TT> will be returned.
|
|
|
|
|
|
<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 <FONT SIZE="-1">HTTP</FONT> spec (<FONT SIZE="-1">RFC 2616</FONT>) promises 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
|
|
HTTP::Cookies) where ``,'' is used as part of the syntax of a single
|
|
field value.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Examples:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$header->header(MIME_Version => '1.0',
|
|
User_Agent => 'My-Web-Client/0.01');
|
|
$header->header(Accept => "text/html, text/plain, image/*");
|
|
$header->header(Accept => [qw(text/html text/plain image/*)]);
|
|
@accepts = $header->header('Accept'); # get multiple values
|
|
$accepts = $header->header('Accept'); # get values as a single string
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="6">$h->push_header( $field => $value )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="7">$h->push_header( $f1 => $v1, $f2 => $v2, ... )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Add a new field value for the specified header field. Previous values
|
|
for the same field are retained.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
As for the <B>header()</B> method, the field name ($field) is not case
|
|
sensitive and '_' can be used as a replacement for '-'.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>$value</TT> argument may be a scalar or a reference to a list of
|
|
scalars.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$header->push_header(Accept => 'image/jpeg');
|
|
$header->push_header(Accept => [map "image/$_", qw(gif png tiff)]);
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="8">$h->init_header( $field => $value )<DD>
|
|
|
|
|
|
|
|
|
|
Set the specified header to the given value, but only if no previous
|
|
value for that field is set.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The header field name ($field) is not case sensitive and '_'
|
|
can be used as a replacement for '-'.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The <TT>$value</TT> argument may be a scalar or a reference to a list of
|
|
scalars.
|
|
<DT id="9">$h->remove_header( $field, ... )<DD>
|
|
|
|
|
|
|
|
|
|
This function removes the header fields with the specified names.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The header field names ($field) are not case sensitive and '_'
|
|
can be used as a replacement for '-'.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The return value is the values of the fields removed. In scalar
|
|
context the number of fields removed is returned.
|
|
|
|
|
|
<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.
|
|
<DT id="10">$h->remove_content_headers<DD>
|
|
|
|
|
|
|
|
|
|
This will remove all the header fields used to describe the content of
|
|
a message. All header field names prefixed with <TT>"Content-"</TT> fall
|
|
into this category, as well as <TT>"Allow"</TT>, <TT>"Expires"</TT> and
|
|
<TT>"Last-Modified"</TT>. <FONT SIZE="-1">RFC 2616</FONT> denotes these fields as <I>Entity Header
|
|
Fields</I>.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The return value is a new <TT>"HTTP::Headers"</TT> object that contains the
|
|
removed headers only.
|
|
<DT id="11">$h->clear<DD>
|
|
|
|
|
|
|
|
|
|
This will remove all header fields.
|
|
<DT id="12">$h->header_field_names<DD>
|
|
|
|
|
|
|
|
|
|
Returns the list of distinct names for the fields present in the
|
|
header. The field names have case as suggested by <FONT SIZE="-1">HTTP</FONT> spec, and the
|
|
names are returned in the recommended ``Good Practice'' order.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
In scalar context return the number of distinct field names.
|
|
<DT id="13">$h->scan( \&process_header_field )<DD>
|
|
|
|
|
|
|
|
|
|
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 <FONT SIZE="-1">HTTP</FONT> spec, and the headers
|
|
will be visited in the recommended ``Good Practice'' order.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Any return values of the callback routine are ignored. The loop can
|
|
be broken by raising an exception (<TT>"die"</TT>), but the caller of <B>scan()</B>
|
|
would have to trap the exception itself.
|
|
<DT id="14">$h-><B>flatten()</B><DD>
|
|
|
|
|
|
|
|
|
|
Returns the list of pairs of keys and values.
|
|
<DT id="15">$h->as_string<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="16">$h->as_string( $eol )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Return the header fields as a formatted <FONT SIZE="-1">MIME</FONT> header. Since it
|
|
internally uses the <TT>"scan"</TT> method to build the string, the result
|
|
will use case as suggested by <FONT SIZE="-1">HTTP</FONT> spec, and it will follow
|
|
recommended ``Good Practice'' of ordering the header fields. Long header
|
|
values are not folded.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The optional <TT>$eol</TT> 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.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>CONVENIENCE METHODS</H2>
|
|
|
|
|
|
|
|
The most frequently used headers can also be accessed through the
|
|
following convenience methods. Most of these methods can both be used to read
|
|
and to set the value of a header. The header value is set if you pass
|
|
an argument to the method. The old header value is always returned.
|
|
If the given header did not exist then <TT>"undef"</TT> is returned.
|
|
<P>
|
|
|
|
Methods that deal with dates/times always convert their value to system
|
|
time (seconds since Jan 1, 1970) and they also expect this kind of
|
|
value when the header value is set.
|
|
<DL COMPACT>
|
|
<DT id="17">$h->date<DD>
|
|
|
|
|
|
|
|
|
|
This header represents the date and time at which the message was
|
|
originated. <I>E.g.</I>:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$h->date(time); # set current date
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="18">$h->expires<DD>
|
|
|
|
|
|
|
|
|
|
This header gives the date and time after which the entity should be
|
|
considered stale.
|
|
<DT id="19">$h->if_modified_since<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="20">$h->if_unmodified_since<DD>
|
|
|
|
|
|
|
|
|
|
|
|
These header fields are used to make a request conditional. If the requested
|
|
resource has (or has not) been modified since the time specified in this field,
|
|
then the server will return a <TT>"304 Not Modified"</TT> response instead of
|
|
the document itself.
|
|
<DT id="21">$h->last_modified<DD>
|
|
|
|
|
|
|
|
|
|
This header indicates the date and time at which the resource was last
|
|
modified. <I>E.g.</I>:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
# check if document is more than 1 hour old
|
|
if (my $last_mod = $h->last_modified) {
|
|
if ($last_mod < time - 60*60) {
|
|
...
|
|
}
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="22">$h->content_type<DD>
|
|
|
|
|
|
|
|
|
|
The Content-Type header field indicates the media type of the message
|
|
content. <I>E.g.</I>:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$h->content_type('text/html');
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The value returned will be converted to lower case, and potential
|
|
parameters will be chopped off and returned as a separate value if in
|
|
an array context. If there is no such header field, then the empty
|
|
string is returned. This makes it safe to do the following:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
if ($h->content_type eq 'text/html') {
|
|
# we enter this place even if the real header value happens to
|
|
# be 'TEXT/HTML; version=3.0'
|
|
...
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="23">$h->content_type_charset<DD>
|
|
|
|
|
|
|
|
|
|
Returns the upper-cased charset specified in the Content-Type header. In list
|
|
context return the lower-cased bare content type followed by the upper-cased
|
|
charset. Both values will be <TT>"undef"</TT> if not specified in the header.
|
|
<DT id="24">$h->content_is_text<DD>
|
|
|
|
|
|
|
|
|
|
Returns <FONT SIZE="-1">TRUE</FONT> if the Content-Type header field indicate that the
|
|
content is textual.
|
|
<DT id="25">$h->content_is_html<DD>
|
|
|
|
|
|
|
|
|
|
Returns <FONT SIZE="-1">TRUE</FONT> if the Content-Type header field indicate that the
|
|
content is some kind of <FONT SIZE="-1">HTML</FONT> (including <FONT SIZE="-1">XHTML</FONT>). This method can't be
|
|
used to set Content-Type.
|
|
<DT id="26">$h->content_is_xhtml<DD>
|
|
|
|
|
|
|
|
|
|
Returns <FONT SIZE="-1">TRUE</FONT> if the Content-Type header field indicate that the
|
|
content is <FONT SIZE="-1">XHTML.</FONT> This method can't be used to set Content-Type.
|
|
<DT id="27">$h->content_is_xml<DD>
|
|
|
|
|
|
|
|
|
|
Returns <FONT SIZE="-1">TRUE</FONT> if the Content-Type header field indicate that the
|
|
content is <FONT SIZE="-1">XML.</FONT> This method can't be used to set Content-Type.
|
|
<DT id="28">$h->content_encoding<DD>
|
|
|
|
|
|
|
|
|
|
The Content-Encoding header field is used as a modifier to the
|
|
media type. When present, its value indicates what additional
|
|
encoding mechanism has been applied to the resource.
|
|
<DT id="29">$h->content_length<DD>
|
|
|
|
|
|
|
|
|
|
A decimal number indicating the size in bytes of the message content.
|
|
<DT id="30">$h->content_language<DD>
|
|
|
|
|
|
|
|
|
|
The natural language(s) of the intended audience for the message
|
|
content. The value is one or more language tags as defined by <FONT SIZE="-1">RFC
|
|
1766.</FONT> Eg. ``no'' for some kind of Norwegian and ``en-US'' for English the
|
|
way it is written in the <FONT SIZE="-1">US.</FONT>
|
|
<DT id="31">$h->title<DD>
|
|
|
|
|
|
|
|
|
|
The title of the document. In libwww-perl this header will be
|
|
initialized automatically from the <<FONT SIZE="-1">TITLE</FONT>>...</TITLE> element
|
|
of <FONT SIZE="-1">HTML</FONT> documents. <I>This header is no longer part of the </I><FONT SIZE="-1"><I>HTTP</I></FONT><I>
|
|
standard.</I>
|
|
<DT id="32">$h->user_agent<DD>
|
|
|
|
|
|
|
|
|
|
This header field is used in request messages and contains information
|
|
about the user agent originating the request. <I>E.g.</I>:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$h->user_agent('Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 6.0)');
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="33">$h->server<DD>
|
|
|
|
|
|
|
|
|
|
The server header field contains information about the software being
|
|
used by the originating server program handling the request.
|
|
<DT id="34">$h->from<DD>
|
|
|
|
|
|
|
|
|
|
This header should contain an Internet e-mail address for the human
|
|
user who controls the requesting user agent. The address should be
|
|
machine-usable, as defined by <FONT SIZE="-1">RFC822.</FONT> E.g.:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$h->from('King Kong <<A HREF="mailto:king@kong.com">king@kong.com</A>>');
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
<I>This header is no longer part of the </I><FONT SIZE="-1"><I>HTTP</I></FONT><I> standard.</I>
|
|
<DT id="35">$h->referer<DD>
|
|
|
|
|
|
|
|
|
|
Used to specify the address (<FONT SIZE="-1">URI</FONT>) of the document from which the
|
|
requested resource address was obtained.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The ``Free On-line Dictionary of Computing'' as this to say about the
|
|
word <I>referer</I>:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
<World-Wide Web> A misspelling of "referrer" which
|
|
somehow made it into the {HTTP} standard. A given {web
|
|
page}'s referer (sic) is the {URL} of whatever web page
|
|
contains the link that the user followed to the current
|
|
page. Most browsers pass this information as part of a
|
|
request.
|
|
|
|
(1998-10-19)
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
By popular demand <TT>"referrer"</TT> exists as an alias for this method so you
|
|
can avoid this misspelling in your programs and still send the right
|
|
thing on the wire.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When setting the referrer, this method removes the fragment from the
|
|
given <FONT SIZE="-1">URI</FONT> if it is present, as mandated by <FONT SIZE="-1">RFC2616.</FONT> Note that
|
|
the removal does <I>not</I> happen automatically if using the <B>header()</B>,
|
|
<B>push_header()</B> or <B>init_header()</B> methods to set the referrer.
|
|
<DT id="36">$h->www_authenticate<DD>
|
|
|
|
|
|
|
|
|
|
This header must be included as part of a <TT>"401 Unauthorized"</TT> response.
|
|
The field value consist of a challenge that indicates the
|
|
authentication scheme and parameters applicable to the requested <FONT SIZE="-1">URI.</FONT>
|
|
<DT id="37">$h->proxy_authenticate<DD>
|
|
|
|
|
|
|
|
|
|
This header must be included in a <TT>"407 Proxy Authentication Required"</TT>
|
|
response.
|
|
<DT id="38">$h->authorization<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="39">$h->proxy_authorization<DD>
|
|
|
|
|
|
|
|
|
|
|
|
A user agent that wishes to authenticate itself with a server or a
|
|
proxy, may do so by including these headers.
|
|
<DT id="40">$h->authorization_basic<DD>
|
|
|
|
|
|
|
|
|
|
This method is used to get or set an authorization header that use the
|
|
``Basic Authentication Scheme''. In array context it will return two
|
|
values; the user name and the password. In scalar context it will
|
|
return <I>``uname:password''</I> as a single string value.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
When used to set the header value, it expects two arguments. <I>E.g.</I>:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
$h->authorization_basic($uname, $password);
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The method will croak if the <TT>$uname</TT> contains a colon ':'.
|
|
<DT id="41">$h->proxy_authorization_basic<DD>
|
|
|
|
|
|
|
|
|
|
Same as <B>authorization_basic()</B> but will set the ``Proxy-Authorization''
|
|
header instead.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>NON-CANONICALIZED FIELD NAMES</H2>
|
|
|
|
|
|
|
|
The header field name spelling is normally canonicalized including the
|
|
'_' to '-' translation. There are some application where this is not
|
|
appropriate. Prefixing field names with ':' allow you to force a
|
|
specific spelling. For example if you really want a header field name
|
|
to show up as <TT>"foo_bar"</TT> instead of ``Foo-Bar'', you might set it like
|
|
this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
$h->header(":foo_bar" => 1);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
These field names are returned with the ':' intact for
|
|
<TT>$h</TT>->header_field_names and the <TT>$h</TT>->scan callback, but the colons do
|
|
not show in <TT>$h</TT>->as_string.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Gisle Aas <<A HREF="mailto:gisle@activestate.com">gisle@activestate.com</A>>
|
|
<A NAME="lbAI"> </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="42"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="43"><A HREF="#lbAC">VERSION</A><DD>
|
|
<DT id="44"><A HREF="#lbAD">SYNOPSIS</A><DD>
|
|
<DT id="45"><A HREF="#lbAE">DESCRIPTION</A><DD>
|
|
<DT id="46"><A HREF="#lbAF">CONVENIENCE METHODS</A><DD>
|
|
<DT id="47"><A HREF="#lbAG">NON-CANONICALIZED FIELD NAMES</A><DD>
|
|
<DT id="48"><A HREF="#lbAH">AUTHOR</A><DD>
|
|
<DT id="49"><A HREF="#lbAI">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:45 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|