395 lines
8.9 KiB
HTML
395 lines
8.9 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of HTTP::Negotiate</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>HTTP::Negotiate</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2018-04-14<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::Negotiate - choose a variant to serve
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
use HTTP::Negotiate qw(choose);
|
|
|
|
# ID QS Content-Type Encoding Char-Set Lang Size
|
|
$variants =
|
|
[['var1', 1.000, 'text/html', undef, 'iso-8859-1', 'en', 3000],
|
|
['var2', 0.950, 'text/plain', 'gzip', 'us-ascii', 'no', 400],
|
|
['var3', 0.3, 'image/gif', undef, undef, undef, 43555],
|
|
];
|
|
|
|
@preferred = choose($variants, $request_headers);
|
|
$the_one = choose($variants);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
This module provides a complete implementation of the <FONT SIZE="-1">HTTP</FONT> content
|
|
negotiation algorithm specified in <I>draft-ietf-http-v11-spec-00.ps</I>
|
|
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.
|
|
<P>
|
|
|
|
The variants are ordered by preference by calling the function
|
|
<I>choose()</I>.
|
|
<P>
|
|
|
|
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, <TT>$qs</TT>,
|
|
<TT>$content_type</TT>, <TT>$content_encoding</TT>, <TT>$charset</TT>, <TT>$content_language</TT>,
|
|
<TT>$content_length</TT>] whose meanings are described
|
|
below. The <TT>$content_encoding</TT> and <TT>$content_language</TT> can be either a
|
|
single scalar value or an array reference if there are several values.
|
|
<P>
|
|
|
|
The second optional parameter is either a HTTP::Headers or a HTTP::Request
|
|
object which is searched for ``Accept*'' headers. If this
|
|
parameter is missing, then the accept specification is initialized
|
|
from the <FONT SIZE="-1">CGI</FONT> environment variables <FONT SIZE="-1">HTTP_ACCEPT, HTTP_ACCEPT_CHARSET,
|
|
HTTP_ACCEPT_ENCODING</FONT> and <FONT SIZE="-1">HTTP_ACCEPT_LANGUAGE.</FONT>
|
|
<P>
|
|
|
|
In an array context, <I>choose()</I> 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). <I>E.g.</I>:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
(['var1', 1, 2000], ['var2', 0.3, 512], ['var3', 0.3, 1024]);
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Note that also zero quality variants are included in the return list
|
|
even if these should never be served to the client.
|
|
<P>
|
|
|
|
In a scalar context, it returns the identifier of the variant with the
|
|
highest score or <TT>"undef"</TT> if none have non-zero quality.
|
|
<P>
|
|
|
|
If the <TT>$HTTP::Negotiate::DEBUG</TT> variable is set to <FONT SIZE="-1">TRUE,</FONT> then a lot of
|
|
noise is generated on <FONT SIZE="-1">STDOUT</FONT> during evaluation of <I>choose()</I>.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>VARIANTS</H2>
|
|
|
|
|
|
|
|
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
|
|
<TT>"undef"</TT> instead.
|
|
<DL COMPACT>
|
|
<DT id="1">identifier<DD>
|
|
|
|
|
|
This is a string that you use as the name for the variant. This
|
|
identifier for the preferred variants returned by <I>choose()</I>.
|
|
<DT id="2">qs<DD>
|
|
|
|
|
|
This is a number between 0.000 and 1.000 that describes the ``source
|
|
quality''. This is what <I>draft-ietf-http-v11-spec-00.ps</I> says about this
|
|
value:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Source quality is measured by the content provider as representing the
|
|
amount of degradation from the original source. For example, a
|
|
picture in <FONT SIZE="-1">JPEG</FONT> form would have a lower qs when translated to the <FONT SIZE="-1">XBM</FONT>
|
|
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 <FONT SIZE="-1">JPEG</FONT> 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 ``qs=1''.
|
|
<DT id="3">content-type<DD>
|
|
|
|
|
|
This is the media type of the variant. The media type does not
|
|
include a charset attribute, but might contain other parameters.
|
|
Examples are:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
text/html
|
|
text/html;version=2.0
|
|
text/plain
|
|
image/gif
|
|
image/jpg
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="4">content-encoding<DD>
|
|
|
|
|
|
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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
gzip
|
|
compress
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="5">content-charset<DD>
|
|
|
|
|
|
This is the character set used when the variant contains text.
|
|
The charset value should generally be <TT>"undef"</TT> or one of these:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
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
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="6">content-language<DD>
|
|
|
|
|
|
This describes one or more languages that are used in the variant.
|
|
Language is described like this in <I>draft-ietf-http-v11-spec-00.ps</I>: 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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
The language tags are defined by <FONT SIZE="-1">RFC 3066.</FONT> Examples
|
|
are:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
no Norwegian
|
|
en International English
|
|
en-US US English
|
|
en-cockney
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="7">content-length<DD>
|
|
|
|
|
|
This is the number of bytes used to represent the content.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ACCEPT HEADERS</H2>
|
|
|
|
|
|
|
|
The following Accept* headers can be used for describing content
|
|
preferences in a request (This description is an edited extract from
|
|
<I>draft-ietf-http-v11-spec-00.ps</I>):
|
|
<DL COMPACT>
|
|
<DT id="8">Accept<DD>
|
|
|
|
|
|
This header can be used to indicate a list of media ranges which are
|
|
acceptable as a response to the request. The ``*'' character is used to
|
|
group media types into ranges, with ``*/*'' indicating all media types
|
|
and ``type/*'' indicating all subtypes of that type.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
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.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
For example:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Accept: audio/*;q=0.2;mbx=200000, audio/basic
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
would mean: ``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''
|
|
<DT id="9">Accept-Charset<DD>
|
|
|
|
|
|
Used to indicate what character sets are acceptable for the response.
|
|
The ``us-ascii'' 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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Accept-Charset: iso-8859-1, unicode-1-1
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="10">Accept-Encoding<DD>
|
|
|
|
|
|
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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Accept-Encoding: compress, gzip
|
|
|
|
</PRE>
|
|
|
|
|
|
<DT id="11">Accept-Language<DD>
|
|
|
|
|
|
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:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
Accept-Language: no, en-gb;q=0.8, de;q=0.55
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
would mean: "I prefer Norwegian, but will accept British English (with
|
|
80% comprehension) or German (with 55% comprehension).
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright 1996,2001 Gisle Aas.
|
|
<P>
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the same terms as Perl itself.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Gisle Aas <<A HREF="mailto:gisle@aas.no">gisle@aas.no</A>>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="12"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="13"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="14"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="15"><A HREF="#lbAE">VARIANTS</A><DD>
|
|
<DT id="16"><A HREF="#lbAF">ACCEPT HEADERS</A><DD>
|
|
<DT id="17"><A HREF="#lbAG">COPYRIGHT</A><DD>
|
|
<DT id="18"><A HREF="#lbAH">AUTHOR</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:46 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|