1HTTP::Negotiate(3) User Contributed Perl Documentation HTTP::Negotiate(3)
2
6 HTTP::Negotiate - choose a variant to serve
7
9 use HTTP::Negotiate qw(choose);
10 # 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 @preferred = choose($variants, $request_headers);
19 $the_one = choose($variants);
20
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 The variants are ordered by preference by calling the function
30 choose().
31 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 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 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 (['var1', 1, 2000], ['var2', 0.3, 512], ['var3', 0.3, 1024]);
51 Note that also zero quality variants are included in the return list
53 even if these should never be served to the client.
54 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 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
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 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 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 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 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 text/html
90 text/html;version=2.0
91 text/plain
92 image/gif
93 image/jpg
94 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 gzip
101 compress
102 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 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 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 The language tags are defined by RFC 3066. Examples are:
124 no Norwegian
126 en International English
127 en-US US English
128 en-cockney
129 content-length
131 This is the number of bytes used to represent the content.
132
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 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 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 For example:
151 Accept: audio/*;q=0.2;mbx=200000, audio/basic
153 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 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 Accept-Charset: iso-8859-1, unicode-1-1
165 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 Accept-Encoding: compress, gzip
174 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 Accept-Language: no, en-gb;q=0.8, de;q=0.55
182 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 This library is free software; you can redistribute it and/or modify it
190 under the same terms as Perl itself.
191
193 Gisle Aas <gisle@aas.no>
194perl v5.36.0 2023-01-20 HTTP::Negotiate(3)