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 @prefered = 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 chap‐
24 ter 12. Content negotiation allows for the selection of a preferred
25 content representation based upon attributes of the negotiable variants
26 and the value of the various Accept* header fields in the request.
27 The variants are ordered by preference by calling the function
29 choose().
30 The first parameter is reference to an array of the variants to choose
32 among. Each element in this array is an array with the values [$id,
33 $qs, $content_type, $content_encoding, $charset, $content_language,
34 $content_length] whose meanings are described below. The $con‐
35 tent_encoding and $content_language can be either a single scalar value
36 or an array reference if there are several values.
37 The second optional parameter is either a HTTP::Headers or a
39 HTTP::Request object which is searched for "Accept*" headers. If this
40 parameter is missing, then the accept specification is initialized from
41 the CGI environment variables HTTP_ACCEPT, HTTP_ACCEPT_CHARSET,
42 HTTP_ACCEPT_ENCODING and HTTP_ACCEPT_LANGUAGE.
43 In an array context, choose() returns a list of [variant identifier,
45 calculated quality, size] tuples. The values are sorted by quality,
46 highest quality first. If the calculated quality is the same for two
47 variants, then they are sorted by size (smallest first). E.g.:
48 (['var1', 1, 2000], ['var2', 0.3, 512], ['var3', 0.3, 1024]);
50 Note that also zero quality variants are included in the return list
52 even if these should never be served to the client.
53 In a scalar context, it returns the identifier of the variant with the
55 highest score or "undef" if none have non-zero quality.
56 If the $HTTP::Negotiate::DEBUG variable is set to TRUE, then a lot of
58 noise is generated on STDOUT during evaluation of choose().
59
61 A variant is described by a list of the following values. If the
62 attribute does not make sense or is unknown for a variant, then use
63 "undef" instead.
64 identifier
66 This is a string that you use as the name for the variant. This
67 identifier for the preferred variants returned by choose().
68 qs This is a number between 0.000 and 1.000 that describes the "source
70 quality". This is what draft-ietf-http-v11-spec-00.ps says about
71 this value:
72 Source quality is measured by the content provider as representing
74 the amount of degradation from the original source. For example, a
75 picture in JPEG form would have a lower qs when translated to the
76 XBM format, and much lower qs when translated to an ASCII-art repre‐
77 sentation. Note, however, that this is a function of the source -
78 an original piece of ASCII-art may degrade in quality if it is cap‐
79 tured in JPEG form. The qs values should be assigned to each vari‐
80 ant by the content provider; if no qs value has been assigned, the
81 default is generally "qs=1".
82 content-type
84 This is the media type of the variant. The media type does not
85 include a charset attribute, but might contain other parameters.
86 Examples are:
87 text/html
89 text/html;version=2.0
90 text/plain
91 image/gif
92 image/jpg
93 content-encoding
95 This is one or more content encodings that has been applied to the
96 variant. The content encoding is generally used as a modifier to
97 the content media type. The most common content encodings are:
98 gzip
100 compress
101 content-charset
103 This is the character set used when the variant contains text. The
104 charset value should generally be "undef" or one of these:
105 us-ascii
107 iso-8859-1 ... iso-8859-9
108 iso-2022-jp
109 iso-2022-jp-2
110 iso-2022-kr
111 unicode-1-1
112 unicode-1-1-utf-7
113 unicode-1-1-utf-8
114 content-language
116 This describes one or more languages that are used in the variant.
117 Language is described like this in draft-ietf-http-v11-spec-00.ps: A
118 language is in this context a natural language spoken, written, or
119 otherwise conveyed by human beings for communication of information
120 to other human beings. Computer languages are explicitly excluded.
121 The language tags are defined by RFC 3066. Examples are:
123 no Norwegian
125 en International English
126 en-US US English
127 en-cockney
128 content-length
130 This is the number of bytes used to represent the content.
131
133 The following Accept* headers can be used for describing content pref‐
134 erences in a request (This description is an edited extract from
135 draft-ietf-http-v11-spec-00.ps):
136 Accept
138 This header can be used to indicate a list of media ranges which are
139 acceptable as a response to the request. The "*" character is used
140 to group media types into ranges, with "*/*" indicating all media
141 types and "type/*" indicating all subtypes of that type.
142 The parameter q is used to indicate the quality factor, which repre‐
144 sents the user's preference for that range of media types. The
145 parameter mbx gives the maximum acceptable size of the response con‐
146 tent. The default values are: q=1 and mbx=infinity. If no Accept
147 header is present, then the client accepts all media types with q=1.
148 For example:
150 Accept: audio/*;q=0.2;mbx=200000, audio/basic
152 would mean: "I prefer audio/basic (of any size), but send me any
154 audio type if it is the best available after an 80% mark-down in
155 quality and its size is less than 200000 bytes"
156 Accept-Charset
158 Used to indicate what character sets are acceptable for the
159 response. The "us-ascii" character set is assumed to be acceptable
160 for all user agents. If no Accept-Charset field is given, the
161 default is that any charset is acceptable. Example:
162 Accept-Charset: iso-8859-1, unicode-1-1
164 Accept-Encoding
166 Restricts the Content-Encoding values which are acceptable in the
167 response. If no Accept-Encoding field is present, the server may
168 assume that the client will accept any content encoding. An empty
169 Accept-Encoding means that no content encoding is acceptable. Exam‐
170 ple:
171 Accept-Encoding: compress, gzip
173 Accept-Language
175 This field is similar to Accept, but restricts the set of natural
176 languages that are preferred in a response. Each language may be
177 given an associated quality value which represents an estimate of
178 the user's comprehension of that language. For example:
179 Accept-Language: no, en-gb;q=0.8, de;q=0.55
181 would mean: "I prefer Norwegian, but will accept British English
183 (with 80% comprehension) or German (with 55% comprehension).
184
186 Copyright 1996,2001 Gisle Aas.
187 This library is free software; you can redistribute it and/or modify it
189 under the same terms as Perl itself.
190
192 Gisle Aas <gisle@aas.no>
193perl v5.8.8 2004-04-06 HTTP::Negotiate(3)