.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "HTTP::Negotiate 3"
.TH HTTP::Negotiate 3 "2012-02-18" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTTP::Negotiate \- choose a variant to serve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use HTTP::Negotiate qw(choose);
\&
\& # ID QS Content\-Type Encoding Char\-Set Lang Size
\& $variants =
\& [[\*(Aqvar1\*(Aq, 1.000, \*(Aqtext/html\*(Aq, undef, \*(Aqiso\-8859\-1\*(Aq, \*(Aqen\*(Aq, 3000],
\& [\*(Aqvar2\*(Aq, 0.950, \*(Aqtext/plain\*(Aq, \*(Aqgzip\*(Aq, \*(Aqus\-ascii\*(Aq, \*(Aqno\*(Aq, 400],
\& [\*(Aqvar3\*(Aq, 0.3, \*(Aqimage/gif\*(Aq, undef, undef, undef, 43555],
\& ];
\&
\& @preferred = choose($variants, $request_headers);
\& $the_one = choose($variants);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a complete implementation of the \s-1HTTP\s0 content
negotiation algorithm specified in \fIdraft\-ietf\-http\-v11\-spec\-00.ps\fR
chapter 12. Content negotiation allows for the selection of a
preferred content representation based upon attributes of the
negotiable variants and the value of the various Accept* header fields
in the request.
.PP
The variants are ordered by preference by calling the function
\&\fIchoose()\fR.
.PP
The first parameter is reference to an array of the variants to
choose among.
Each element in this array is an array with the values [$id, \f(CW$qs\fR,
\&\f(CW$content_type\fR, \f(CW$content_encoding\fR, \f(CW$charset\fR, \f(CW$content_language\fR,
\&\f(CW$content_length\fR] whose meanings are described
below. The \f(CW$content_encoding\fR and \f(CW$content_language\fR can be either a
single scalar value or an array reference if there are several values.
.PP
The second optional parameter is either a HTTP::Headers or a HTTP::Request
object which is searched for \*(L"Accept*\*(R" headers. If this
parameter is missing, then the accept specification is initialized
from the \s-1CGI\s0 environment variables \s-1HTTP_ACCEPT, HTTP_ACCEPT_CHARSET,
HTTP_ACCEPT_ENCODING\s0 and \s-1HTTP_ACCEPT_LANGUAGE.\s0
.PP
In an array context, \fIchoose()\fR returns a list of [variant
identifier, calculated quality, size] tuples. The values are sorted by
quality, highest quality first. If the calculated quality is the same
for two variants, then they are sorted by size (smallest first). \fIE.g.\fR:
.PP
.Vb 1
\& ([\*(Aqvar1\*(Aq, 1, 2000], [\*(Aqvar2\*(Aq, 0.3, 512], [\*(Aqvar3\*(Aq, 0.3, 1024]);
.Ve
.PP
Note that also zero quality variants are included in the return list
even if these should never be served to the client.
.PP
In a scalar context, it returns the identifier of the variant with the
highest score or \f(CW\*(C`undef\*(C'\fR if none have non-zero quality.
.PP
If the \f(CW$HTTP::Negotiate::DEBUG\fR variable is set to \s-1TRUE,\s0 then a lot of
noise is generated on \s-1STDOUT\s0 during evaluation of \fIchoose()\fR.
.SH "VARIANTS"
.IX Header "VARIANTS"
A variant is described by a list of the following values. If the
attribute does not make sense or is unknown for a variant, then use
\&\f(CW\*(C`undef\*(C'\fR instead.
.IP "identifier" 3
.IX Item "identifier"
This is a string that you use as the name for the variant. This
identifier for the preferred variants returned by \fIchoose()\fR.
.IP "qs" 3
.IX Item "qs"
This is a number between 0.000 and 1.000 that describes the \*(L"source
quality\*(R". This is what \fIdraft\-ietf\-http\-v11\-spec\-00.ps\fR says about this
value:
.Sp
Source quality is measured by the content provider as representing the
amount of degradation from the original source. For example, a
picture in \s-1JPEG\s0 form would have a lower qs when translated to the \s-1XBM\s0
format, and much lower qs when translated to an ASCII-art
representation. Note, however, that this is a function of the source
\&\- an original piece of ASCII-art may degrade in quality if it is
captured in \s-1JPEG\s0 form. The qs values should be assigned to each
variant by the content provider; if no qs value has been assigned, the
default is generally \*(L"qs=1\*(R".
.IP "content-type" 3
.IX Item "content-type"
This is the media type of the variant. The media type does not
include a charset attribute, but might contain other parameters.
Examples are:
.Sp
.Vb 5
\& text/html
\& text/html;version=2.0
\& text/plain
\& image/gif
\& image/jpg
.Ve
.IP "content-encoding" 3
.IX Item "content-encoding"
This is one or more content encodings that has been applied to the
variant. The content encoding is generally used as a modifier to the
content media type. The most common content encodings are:
.Sp
.Vb 2
\& gzip
\& compress
.Ve
.IP "content-charset" 3
.IX Item "content-charset"
This is the character set used when the variant contains text.
The charset value should generally be \f(CW\*(C`undef\*(C'\fR or one of these:
.Sp
.Vb 8
\& us\-ascii
\& iso\-8859\-1 ... iso\-8859\-9
\& iso\-2022\-jp
\& iso\-2022\-jp\-2
\& iso\-2022\-kr
\& unicode\-1\-1
\& unicode\-1\-1\-utf\-7
\& unicode\-1\-1\-utf\-8
.Ve
.IP "content-language" 3
.IX Item "content-language"
This describes one or more languages that are used in the variant.
Language is described like this in \fIdraft\-ietf\-http\-v11\-spec\-00.ps\fR: A
language is in this context a natural language spoken, written, or
otherwise conveyed by human beings for communication of information to
other human beings. Computer languages are explicitly excluded.
.Sp
The language tags are defined by \s-1RFC 3066. \s0 Examples
are:
.Sp
.Vb 4
\& no Norwegian
\& en International English
\& en\-US US English
\& en\-cockney
.Ve
.IP "content-length" 3
.IX Item "content-length"
This is the number of bytes used to represent the content.
.SH "ACCEPT HEADERS"
.IX Header "ACCEPT HEADERS"
The following Accept* headers can be used for describing content
preferences in a request (This description is an edited extract from
\&\fIdraft\-ietf\-http\-v11\-spec\-00.ps\fR):
.IP "Accept" 3
.IX Item "Accept"
This header can be used to indicate a list of media ranges which are
acceptable as a response to the request. The \*(L"*\*(R" character is used to
group media types into ranges, with \*(L"*/*\*(R" indicating all media types
and \*(L"type/*\*(R" indicating all subtypes of that type.
.Sp
The parameter q is used to indicate the quality factor, which
represents the user's preference for that range of media types. The
parameter mbx gives the maximum acceptable size of the response
content. The default values are: q=1 and mbx=infinity. If no Accept
header is present, then the client accepts all media types with q=1.
.Sp
For example:
.Sp
.Vb 1
\& Accept: audio/*;q=0.2;mbx=200000, audio/basic
.Ve
.Sp
would mean: \*(L"I prefer audio/basic (of any size), but send me any audio
type if it is the best available after an 80% mark-down in quality and
its size is less than 200000 bytes\*(R"
.IP "Accept-Charset" 3
.IX Item "Accept-Charset"
Used to indicate what character sets are acceptable for the response.
The \*(L"us-ascii\*(R" character set is assumed to be acceptable for all user
agents. If no Accept-Charset field is given, the default is that any
charset is acceptable. Example:
.Sp
.Vb 1
\& Accept\-Charset: iso\-8859\-1, unicode\-1\-1
.Ve
.IP "Accept-Encoding" 3
.IX Item "Accept-Encoding"
Restricts the Content-Encoding values which are acceptable in the
response. If no Accept-Encoding field is present, the server may
assume that the client will accept any content encoding. An empty
Accept-Encoding means that no content encoding is acceptable. Example:
.Sp
.Vb 1
\& Accept\-Encoding: compress, gzip
.Ve
.IP "Accept-Language" 3
.IX Item "Accept-Language"
This field is similar to Accept, but restricts the set of natural
languages that are preferred in a response. Each language may be
given an associated quality value which represents an estimate of the
user's comprehension of that language. For example:
.Sp
.Vb 1
\& Accept\-Language: no, en\-gb;q=0.8, de;q=0.55
.Ve
.Sp
would mean: "I prefer Norwegian, but will accept British English (with
80% comprehension) or German (with 55% comprehension).
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 1996,2001 Gisle Aas.
.PP
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "AUTHOR"
.IX Header "AUTHOR"
Gisle Aas <gisle@aas.no>
@KyuuKazami