1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>mod_negotiation - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body> 17<div id="page-header"> 18<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 19<p class="apache">Apache HTTP Server Version 2.2</p> 20<img alt="" src="/images/feather.gif" /></div> 21<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 22<div id="path"> 23<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.2</a> > <a href="./">Modules</a></div> 24<div id="page-content"> 25<div id="preamble"><h1>Apache Module mod_negotiation</h1> 26<div class="toplang"> 27<p><span>Available Languages: </span><a href="/en/mod/mod_negotiation.html" title="English"> en </a> | 28<a href="/ja/mod/mod_negotiation.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> 29</div> 30<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides for <a href="/content-negotiation.html">content negotiation</a></td></tr> 31<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr> 32<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>negotiation_module</td></tr> 33<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_negotiation.c</td></tr></table> 34<h3>Summary</h3> 35 36 <p>Content negotiation, or more accurately content selection, is 37 the selection of the document that best matches the clients 38 capabilities, from one of several available documents. There 39 are two implementations of this.</p> 40 41 <ul> 42 <li>A type map (a file with the handler 43 <code>type-map</code>) which explicitly lists the files 44 containing the variants.</li> 45 46 <li>A MultiViews search (enabled by the <code>MultiViews</code> 47 <code class="directive"><a href="/mod/core.html#options">Options</a></code>), where the server does 48 an implicit filename pattern match, and choose from amongst the 49 results.</li> 50 </ul> 51</div> 52<div id="quickview"><h3 class="directives">Directives</h3> 53<ul id="toc"> 54<li><img alt="" src="/images/down.gif" /> <a href="#cachenegotiateddocs">CacheNegotiatedDocs</a></li> 55<li><img alt="" src="/images/down.gif" /> <a href="#forcelanguagepriority">ForceLanguagePriority</a></li> 56<li><img alt="" src="/images/down.gif" /> <a href="#languagepriority">LanguagePriority</a></li> 57</ul> 58<h3>Topics</h3> 59<ul id="topics"> 60<li><img alt="" src="/images/down.gif" /> <a href="#typemaps">Type maps</a></li> 61<li><img alt="" src="/images/down.gif" /> <a href="#multiviews">MultiViews</a></li> 62</ul><h3>See also</h3> 63<ul class="seealso"> 64<li><code class="directive"><a href="/mod/core.html#options">Options</a></code></li> 65<li><code class="module"><a href="/mod/mod_mime.html">mod_mime</a></code></li> 66<li><a href="/content-negotiation.html">Content 67Negotiation</a></li> 68<li><a href="/env.html">Environment Variables</a></li> 69</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 70<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 71<div class="section"> 72<h2><a name="typemaps" id="typemaps">Type maps</a></h2> 73 <p>A type map has a format similar to RFC822 mail headers. It 74 contains document descriptions separated by blank lines, with 75 lines beginning with a hash character ('#') treated as 76 comments. A document description consists of several header 77 records; records may be continued on multiple lines if the 78 continuation lines start with spaces. The leading space will be 79 deleted and the lines concatenated. A header record consists of 80 a keyword name, which always ends in a colon, followed by a 81 value. Whitespace is allowed between the header name and value, 82 and between the tokens of value. The headers allowed are: </p> 83 84 <dl> 85 <dt><code>Content-Encoding:</code></dt> 86 <dd>The encoding of the file. Apache only recognizes 87 encodings that are defined by an <code class="directive"><a href="/mod/mod_mime.html#addencoding">AddEncoding</a></code> directive. 88 This normally includes the encodings <code>x-compress</code> 89 for compress'd files, and <code>x-gzip</code> for gzip'd 90 files. The <code>x-</code> prefix is ignored for encoding 91 comparisons.</dd> 92 93 <dt><code>Content-Language:</code></dt> 94 <dd>The language(s) of the variant, as an Internet standard 95 language tag (<a href="http://www.ietf.org/rfc/rfc1766.txt">RFC 1766</a>). An example is <code>en</code>, 96 meaning English. If the variant contains more than one 97 language, they are separated by a comma.</dd> 98 99 <dt><code>Content-Length:</code></dt> 100 <dd>The length of the file, in bytes. If this header is not 101 present, then the actual length of the file is used.</dd> 102 103 <dt><code>Content-Type:</code></dt> 104 105 <dd> 106 The <a class="glossarylink" href="/glossary.html#mime-type" title="see glossary">MIME media type</a> of 107 the document, with optional parameters. Parameters are 108 separated from the media type and from one another by a 109 semi-colon, with a syntax of <code>name=value</code>. Common 110 parameters include: 111 112 <dl> 113 <dt><code>level</code></dt> 114 <dd>an integer specifying the version of the media type. 115 For <code>text/html</code> this defaults to 2, otherwise 116 0.</dd> 117 118 <dt><code>qs</code></dt> 119 <dd>a floating-point number with a value in the range 0[.000] 120 to 1[.000], indicating the relative 'quality' of this variant 121 compared to the other available variants, independent of 122 the client's capabilities. For example, a jpeg file is 123 usually of higher source quality than an ascii file if it 124 is attempting to represent a photograph. However, if the 125 resource being represented is ascii art, then an ascii 126 file would have a higher source quality than a jpeg file. 127 All <code>qs</code> values are therefore specific to a given 128 resource.</dd> 129 </dl> 130 131 <div class="example"><h3>Example</h3><p><code> 132 Content-Type: image/jpeg; qs=0.8 133 </code></p></div> 134 </dd> 135 136 <dt><code>URI:</code></dt> 137 <dd>uri of the file containing the variant (of the given 138 media type, encoded with the given content encoding). These 139 are interpreted as URLs relative to the map file; they must 140 be on the same server (!), and they must refer to files to 141 which the client would be granted access if they were to be 142 requested directly.</dd> 143 144 <dt><code>Body:</code></dt> 145 <dd>New in Apache 2.0, the actual content of the resource may 146 be included in the type-map file using the Body header. This 147 header must contain a string that designates a delimiter for 148 the body content. Then all following lines in the type map 149 file will be considered part of the resource body until the 150 delimiter string is found. 151 152 <div class="example"><h3>Example:</h3><p><code> 153 Body:----xyz----<br /> 154 <html><br /> 155 <body><br /> 156 <p>Content of the page.</p><br /> 157 </body><br /> 158 </html><br /> 159 ----xyz---- 160 </code></p></div> 161 </dd> 162 </dl> 163</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 164<div class="section"> 165<h2><a name="multiviews" id="multiviews">MultiViews</a></h2> 166 <p>A MultiViews search is enabled by the <code>MultiViews</code> 167 <code class="directive"><a href="/mod/core.html#options">Options</a></code>. If the server receives a 168 request for <code>/some/dir/foo</code> and 169 <code>/some/dir/foo</code> does <em>not</em> exist, then the 170 server reads the directory looking for all files named 171 <code>foo.*</code>, and effectively fakes up a type map which 172 names all those files, assigning them the same media types and 173 content-encodings it would have if the client had asked for one 174 of them by name. It then chooses the best match to the client's 175 requirements, and returns that document.</p> 176 177 <p>The <code class="directive"><a href="/mod/mod_mime.html#multiviewsmatch">MultiViewsMatch</a></code> 178 directive configures whether Apache will consider files 179 that do not have content negotiation meta-information assigned 180 to them when choosing files.</p> 181</div> 182<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 183<div class="directive-section"><h2><a name="CacheNegotiatedDocs" id="CacheNegotiatedDocs">CacheNegotiatedDocs</a> <a name="cachenegotiateddocs" id="cachenegotiateddocs">Directive</a></h2> 184<table class="directive"> 185<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allows content-negotiated documents to be 186cached by proxy servers</td></tr> 187<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheNegotiatedDocs On|Off</code></td></tr> 188<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheNegotiatedDocs Off</code></td></tr> 189<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 190<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 191<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr> 192<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The syntax changed in version 2.0.</td></tr> 193</table> 194 <p>If set, this directive allows content-negotiated documents 195 to be cached by proxy servers. This could mean that clients 196 behind those proxys could retrieve versions of the documents 197 that are not the best match for their abilities, but it will 198 make caching more efficient.</p> 199 200 <p>This directive only applies to requests which come from 201 HTTP/1.0 browsers. HTTP/1.1 provides much better control over 202 the caching of negotiated documents, and this directive has no 203 effect in responses to HTTP/1.1 requests.</p> 204 205 <p>Prior to version 2.0, 206 <code class="directive">CacheNegotiatedDocs</code> did not take an 207 argument; it was turned on by the presence of the directive by 208 itself.</p> 209 210</div> 211<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 212<div class="directive-section"><h2><a name="ForceLanguagePriority" id="ForceLanguagePriority">ForceLanguagePriority</a> <a name="forcelanguagepriority" id="forcelanguagepriority">Directive</a></h2> 213<table class="directive"> 214<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Action to take if a single acceptable document is not 215found</td></tr> 216<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</code></td></tr> 217<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ForceLanguagePriority Prefer</code></td></tr> 218<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 219<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 220<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 221<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr> 222<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.0.30 and later</td></tr> 223</table> 224 <p>The <code class="directive">ForceLanguagePriority</code> directive uses 225 the given <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> to satisfy 226 negotation where the server could otherwise not return a single 227 matching document.</p> 228 229 <p><code>ForceLanguagePriority Prefer</code> uses 230 <code>LanguagePriority</code> to serve a one valid result, rather 231 than returning an HTTP result 300 (MULTIPLE CHOICES) when there 232 are several equally valid choices. If the directives below were 233 given, and the user's <code>Accept-Language</code> header assigned 234 <code>en</code> and <code>de</code> each as quality <code>.500</code> 235 (equally acceptable) then the first matching variant, <code>en</code>, 236 will be served.</p> 237 238 <div class="example"><p><code> 239 LanguagePriority en fr de<br /> 240 ForceLanguagePriority Prefer 241 </code></p></div> 242 243 <p><code>ForceLanguagePriority Fallback</code> uses 244 <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> to 245 serve a valid result, rather than returning an HTTP result 406 246 (NOT ACCEPTABLE). If the directives below were given, and the user's 247 <code>Accept-Language</code> only permitted an <code>es</code> 248 language response, but such a variant isn't found, then the first 249 variant from the <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> list below will be served.</p> 250 251 <div class="example"><p><code> 252 LanguagePriority en fr de<br /> 253 ForceLanguagePriority Fallback 254 </code></p></div> 255 256 <p>Both options, <code>Prefer</code> and <code>Fallback</code>, may be 257 specified, so either the first matching variant from <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> will be served if 258 more than one variant is acceptable, or first available document will 259 be served if none of the variants matched the client's acceptable list 260 of languages.</p> 261 262<h3>See also</h3> 263<ul> 264<li><code class="directive"><a href="/mod/mod_mime.html#addlanguage">AddLanguage</a></code></li> 265</ul> 266</div> 267<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 268<div class="directive-section"><h2><a name="LanguagePriority" id="LanguagePriority">LanguagePriority</a> <a name="languagepriority" id="languagepriority">Directive</a></h2> 269<table class="directive"> 270<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The precendence of language variants for cases where 271the client does not express a preference</td></tr> 272<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LanguagePriority <var>MIME-lang</var> [<var>MIME-lang</var>] 273...</code></td></tr> 274<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 275<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 276<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 277<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr> 278</table> 279 <p>The <code class="directive">LanguagePriority</code> sets the precedence 280 of language variants for the case where the client does not 281 express a preference, when handling a MultiViews request. The list 282 of <var>MIME-lang</var> are in order of decreasing preference.</p> 283 284 <div class="example"><h3>Example:</h3><p><code> 285 LanguagePriority en fr de 286 </code></p></div> 287 288 <p>For a request for <code>foo.html</code>, where 289 <code>foo.html.fr</code> and <code>foo.html.de</code> both 290 existed, but the browser did not express a language preference, 291 then <code>foo.html.fr</code> would be returned.</p> 292 293 <p>Note that this directive only has an effect if a 'best' 294 language cannot be determined by any other means or the <code class="directive"><a href="#forcelanguagepriority">ForceLanguagePriority</a></code> directive 295 is not <code>None</code>. In general, the client determines the 296 language preference, not the server.</p> 297 298<h3>See also</h3> 299<ul> 300<li><code class="directive"><a href="/mod/mod_mime.html#addlanguage">AddLanguage</a></code></li> 301</ul> 302</div> 303</div> 304<div class="bottomlang"> 305<p><span>Available Languages: </span><a href="/en/mod/mod_negotiation.html" title="English"> en </a> | 306<a href="/ja/mod/mod_negotiation.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> 307</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 308<script type="text/javascript"><!--//--><![CDATA[//><!-- 309var comments_shortname = 'httpd'; 310var comments_identifier = 'http://httpd.apache.org/docs/2.2/mod/mod_negotiation.html'; 311(function(w, d) { 312 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 313 d.write('<div id="comments_thread"><\/div>'); 314 var s = d.createElement('script'); 315 s.type = 'text/javascript'; 316 s.async = true; 317 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 318 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 319 } 320 else { 321 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 322 } 323})(window, document); 324//--><!]]></script></div><div id="footer"> 325<p class="apache">Copyright 2013 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 326<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 327if (typeof(prettyPrint) !== 'undefined') { 328 prettyPrint(); 329} 330//--><!]]></script> 331</body></html>
