1HTTP::Negotiate(3)    User Contributed Perl Documentation   HTTP::Negotiate(3)
2
3
4

NAME

6       HTTP::Negotiate - choose a variant to serve
7

SYNOPSIS

9        use HTTP::Negotiate qw(choose);
10
11        #  ID       QS     Content-Type   Encoding Char-Set        Lang   Size
12        $variants =
13         [['var1',  1.000, 'text/html',   undef,   'iso-8859-1',   'en',   3000],
14          ['var2',  0.950, 'text/plain',  'gzip',  'us-ascii',     'no',    400],
15          ['var3',  0.3,   'image/gif',   undef,   undef,          undef, 43555],
16         ];
17
18        @preferred = choose($variants, $request_headers);
19        $the_one   = choose($variants);
20

DESCRIPTION

22       This module provides a complete implementation of the HTTP content
23       negotiation algorithm specified in draft-ietf-http-v11-spec-00.ps
24       chapter 12.  Content negotiation allows for the selection of a
25       preferred content representation based upon attributes of the
26       negotiable variants and the value of the various Accept* header fields
27       in the request.
28
29       The variants are ordered by preference by calling the function
30       choose().
31
32       The first parameter is reference to an array of the variants to choose
33       among.  Each element in this array is an array with the values [$id,
34       $qs, $content_type, $content_encoding, $charset, $content_language,
35       $content_length] whose meanings are described below. The
36       $content_encoding and $content_language can be either a single scalar
37       value or an array reference if there are several values.
38
39       The second optional parameter is either a HTTP::Headers or a
40       HTTP::Request object which is searched for "Accept*" headers.  If this
41       parameter is missing, then the accept specification is initialized from
42       the CGI environment variables HTTP_ACCEPT, HTTP_ACCEPT_CHARSET,
43       HTTP_ACCEPT_ENCODING and HTTP_ACCEPT_LANGUAGE.
44
45       In an array context, choose() returns a list of [variant identifier,
46       calculated quality, size] tuples.  The values are sorted by quality,
47       highest quality first.  If the calculated quality is the same for two
48       variants, then they are sorted by size (smallest first). E.g.:
49
50         (['var1', 1, 2000], ['var2', 0.3, 512], ['var3', 0.3, 1024]);
51
52       Note that also zero quality variants are included in the return list
53       even if these should never be served to the client.
54
55       In a scalar context, it returns the identifier of the variant with the
56       highest score or "undef" if none have non-zero quality.
57
58       If the $HTTP::Negotiate::DEBUG variable is set to TRUE, then a lot of
59       noise is generated on STDOUT during evaluation of choose().
60

VARIANTS

62       A variant is described by a list of the following values.  If the
63       attribute does not make sense or is unknown for a variant, then use
64       "undef" instead.
65
66       identifier
67          This is a string that you use as the name for the variant.  This
68          identifier for the preferred variants returned by choose().
69
70       qs This is a number between 0.000 and 1.000 that describes the "source
71          quality".  This is what draft-ietf-http-v11-spec-00.ps says about
72          this value:
73
74          Source quality is measured by the content provider as representing
75          the amount of degradation from the original source.  For example, a
76          picture in JPEG form would have a lower qs when translated to the
77          XBM format, and much lower qs when translated to an ASCII-art
78          representation.  Note, however, that this is a function of the
79          source - an original piece of ASCII-art may degrade in quality if it
80          is captured in JPEG form.  The qs values should be assigned to each
81          variant by the content provider; if no qs value has been assigned,
82          the default is generally "qs=1".
83
84       content-type
85          This is the media type of the variant.  The media type does not
86          include a charset attribute, but might contain other parameters.
87          Examples are:
88
89            text/html
90            text/html;version=2.0
91            text/plain
92            image/gif
93            image/jpg
94
95       content-encoding
96          This is one or more content encodings that has been applied to the
97          variant.  The content encoding is generally used as a modifier to
98          the content media type.  The most common content encodings are:
99
100            gzip
101            compress
102
103       content-charset
104          This is the character set used when the variant contains text.  The
105          charset value should generally be "undef" or one of these:
106
107            us-ascii
108            iso-8859-1 ... iso-8859-9
109            iso-2022-jp
110            iso-2022-jp-2
111            iso-2022-kr
112            unicode-1-1
113            unicode-1-1-utf-7
114            unicode-1-1-utf-8
115
116       content-language
117          This describes one or more languages that are used in the variant.
118          Language is described like this in draft-ietf-http-v11-spec-00.ps: A
119          language is in this context a natural language spoken, written, or
120          otherwise conveyed by human beings for communication of information
121          to other human beings.  Computer languages are explicitly excluded.
122
123          The language tags are defined by RFC 3066.  Examples are:
124
125            no               Norwegian
126            en               International English
127            en-US            US English
128            en-cockney
129
130       content-length
131          This is the number of bytes used to represent the content.
132

ACCEPT HEADERS

134       The following Accept* headers can be used for describing content
135       preferences in a request (This description is an edited extract from
136       draft-ietf-http-v11-spec-00.ps):
137
138       Accept
139          This header can be used to indicate a list of media ranges which are
140          acceptable as a response to the request.  The "*" character is used
141          to group media types into ranges, with "*/*" indicating all media
142          types and "type/*" indicating all subtypes of that type.
143
144          The parameter q is used to indicate the quality factor, which
145          represents the user's preference for that range of media types.  The
146          parameter mbx gives the maximum acceptable size of the response
147          content. The default values are: q=1 and mbx=infinity. If no Accept
148          header is present, then the client accepts all media types with q=1.
149
150          For example:
151
152            Accept: audio/*;q=0.2;mbx=200000, audio/basic
153
154          would mean: "I prefer audio/basic (of any size), but send me any
155          audio type if it is the best available after an 80% mark-down in
156          quality and its size is less than 200000 bytes"
157
158       Accept-Charset
159          Used to indicate what character sets are acceptable for the
160          response.  The "us-ascii" character set is assumed to be acceptable
161          for all user agents.  If no Accept-Charset field is given, the
162          default is that any charset is acceptable.  Example:
163
164            Accept-Charset: iso-8859-1, unicode-1-1
165
166       Accept-Encoding
167          Restricts the Content-Encoding values which are acceptable in the
168          response.  If no Accept-Encoding field is present, the server may
169          assume that the client will accept any content encoding.  An empty
170          Accept-Encoding means that no content encoding is acceptable.
171          Example:
172
173            Accept-Encoding: compress, gzip
174
175       Accept-Language
176          This field is similar to Accept, but restricts the set of natural
177          languages that are preferred in a response.  Each language may be
178          given an associated quality value which represents an estimate of
179          the user's comprehension of that language.  For example:
180
181            Accept-Language: no, en-gb;q=0.8, de;q=0.55
182
183          would mean: "I prefer Norwegian, but will accept British English
184          (with 80% comprehension) or German (with 55% comprehension).
185
187       Copyright 1996,2001 Gisle Aas.
188
189       This library is free software; you can redistribute it and/or modify it
190       under the same terms as Perl itself.
191

AUTHOR

193       Gisle Aas <gisle@aas.no>
194
195
196
197perl v5.36.0                      2023-01-20                HTTP::Negotiate(3)
Impressum