| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
| <HTML> |
| <HEAD> |
| <TITLE>Apache module mod_negotiation</TITLE> |
| </HEAD> |
| |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| <BODY |
| BGCOLOR="#FFFFFF" |
| TEXT="#000000" |
| LINK="#0000FF" |
| VLINK="#000080" |
| ALINK="#FF0000" |
| > |
| <!--#include virtual="header.html" --> |
| <H1 ALIGN="CENTER">Module mod_negotiation</H1> |
| |
| This module is contained in the <CODE>mod_negotiation.c</CODE> file, |
| and is compiled in by default. It provides for <A |
| HREF="../content-negotiation.html">content negotiation</A>. |
| |
| <H2>Summary</H2> |
| Content negotiation, or more accurately content selection, is the |
| selection of the document that best matches the clients |
| capabilities, from one of several available documents. |
| There are two implementations of this. |
| <UL> |
| <LI> A type map (a file with the handler <CODE>type-map</CODE>) |
| which explicitly lists the files containing the variants. |
| <LI> A MultiViews search (enabled by the MultiViews |
| <A HREF="core.html#options">Option</A>, where the server does an implicit |
| filename pattern match, and choose from amongst the results. |
| </UL> |
| |
| <H3>Type maps</H3> |
| A type map has the same format as RFC822 mail headers. It contains document |
| descriptions separated by blank lines, with lines beginning with a hash |
| character ('#') treated as comments. A document description consists of |
| several header records; records may be continued on multiple lines if the |
| continuation lines start with spaces. The leading space will be deleted |
| and the lines concatenated. A header record consists of a keyword |
| name, which always ends in a colon, followed by a value. Whitespace is allowed |
| between the header name and value, and between the tokens of value. |
| |
| The headers allowed are: |
| |
| <DL> |
| <DT>Content-Encoding: |
| <DD>The encoding of the file. Apache only recognizes encodings that are |
| defined by an <A HREF="mod_mime.html#addencoding">AddEncoding</A> directive. |
| This normally includes the encodings <CODE>x-compress</CODE> for compress'd |
| files, and <CODE>x-gzip</CODE> for gzip'd files. The <CODE>x-</CODE> prefix |
| is ignored for encoding comparisons. |
| <DT>Content-Language: |
| <DD>The language of the variant, as an Internet standard language tag |
| (RFC 1766). An example is <CODE>en</CODE>, meaning English. |
| <DT>Content-Length: |
| <DD>The length of the file, in bytes. If this header is not present, then |
| the actual length of the file is used. |
| <DT>Content-Type: |
| <DD>The MIME media type of the document, with optional parameters. |
| Parameters are separated from the media type and from one another by a |
| semi-colon, with a syntax of <CODE>name=value</CODE>. Common parameters |
| include: |
| <DL> |
| <DT>level |
| <DD>an integer specifying the version of the media type. |
| For <CODE>text/html</CODE> this defaults to 2, otherwise 0. |
| <DT>qs |
| <DD>a floating-point number with a value in the range 0.0 to 1.0, |
| indicating the relative 'quality' of this variant |
| compared to the other available variants, independent of the client's |
| capabilities. For example, a jpeg file is usually of higher source |
| quality than an ascii file if it is attempting to represent a |
| photograph. However, if the resource being represented is ascii art, |
| then an ascii file would have a higher source quality than a jpeg file. |
| All qs values are therefore specific to a given resource. |
| </DL> |
| Example: |
| <BLOCKQUOTE><CODE>Content-Type: image/jpeg; qs=0.8</CODE></BLOCKQUOTE> |
| <DT>URI: |
| <DD>The path to the file containing this variant, relative to the map file. |
| </DL> |
| |
| <H3>MultiViews</H3> |
| A MultiViews search is enabled by the MultiViews |
| <A HREF="core.html#options">Option</A>. |
| If the server receives a request for <CODE>/some/dir/foo</CODE> and |
| <CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the |
| directory looking for all files named <CODE>foo.*</CODE>, and effectively |
| fakes up a type map which names all those files, assigning them the same media |
| types and content-encodings it would have if the client had asked for |
| one of them by name. It then chooses the best match to the client's |
| requirements, and returns that document.<P> |
| |
| |
| |
| <H2>Directives</H2> |
| <UL> |
| <LI><A HREF="#cachenegotiateddocs">CacheNegotiatedDocs</A> |
| <LI><A HREF="#languagepriority">LanguagePriority</A> |
| </UL> |
| |
| <STRONG>See also</STRONG>: |
| <A HREF="./mod_mime.html#defaultlanguage">DefaultLanguage</A>, |
| <A HREF="./mod_mime.html#addencoding">AddEncoding</A>, |
| <A HREF="./mod_mime.html#addlanguage">AddLanguage</A>, |
| <A HREF="./mod_mime.html#addtype">AddType</A>, and |
| <A HREF="core.html#options">Option</A>. |
| |
| <HR> |
| |
| |
| <H2><A NAME="cachenegotiateddocs">CacheNegotiatedDocs</A></H2> |
| <A |
| HREF="directive-dict.html#Syntax" |
| REL="Help" |
| ><STRONG>Syntax:</STRONG></A> CacheNegotiatedDocs<BR> |
| <A |
| HREF="directive-dict.html#Context" |
| REL="Help" |
| ><STRONG>Context:</STRONG></A> server config<BR> |
| <A |
| HREF="directive-dict.html#Status" |
| REL="Help" |
| ><STRONG>Status:</STRONG></A> Base<BR> |
| <A |
| HREF="directive-dict.html#Module" |
| REL="Help" |
| ><STRONG>Module:</STRONG></A> mod_negotiation<BR> |
| <A |
| HREF="directive-dict.html#Compatibility" |
| REL="Help" |
| ><STRONG>Compatibility:</STRONG></A> CacheNegotiatedDocs is only available |
| in Apache 1.1 and later.<P> |
| |
| <P>If set, this directive allows content-negotiated documents to be |
| cached by proxy servers. This could mean that clients behind those |
| proxys could retrieve versions of the documents that are not the best |
| match for their abilities, but it will make caching more |
| efficient. |
| <P> |
| |
| This directive only applies to requests which come from HTTP/1.0 browsers. |
| HTTP/1.1 provides much better control over the caching of negotiated |
| documents, and this directive has no effect in responses to |
| HTTP/1.1 requests. |
| |
| |
| |
| <H2><A NAME="languagepriority">LanguagePriority</A></H2> |
| <!--%plaintext <?INDEX {\tt LanguagePriority} directive> --> |
| <A |
| HREF="directive-dict.html#Syntax" |
| REL="Help" |
| ><STRONG>Syntax:</STRONG></A> LanguagePriority <EM>MIME-lang MIME-lang...</EM><BR> |
| <A |
| HREF="directive-dict.html#Context" |
| REL="Help" |
| ><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> |
| <A |
| HREF="directive-dict.html#Override" |
| REL="Help" |
| ><STRONG>Override:</STRONG></A> FileInfo<BR> |
| <A |
| HREF="directive-dict.html#Status" |
| REL="Help" |
| ><STRONG>Status:</STRONG></A> Base<BR> |
| <A |
| HREF="directive-dict.html#Module" |
| REL="Help" |
| ><STRONG>Module:</STRONG></A> mod_negotiation<P> |
| |
| The LanguagePriority sets the precedence of language variants for the case |
| where the client does not express a preference, when handling a |
| MultiViews request. The list of <EM>MIME-lang</EM> are in order of decreasing |
| preference. Example: |
| |
| <BLOCKQUOTE><CODE>LanguagePriority en fr de</CODE></BLOCKQUOTE> |
| |
| For a request for <CODE>foo.html</CODE>, where <CODE>foo.html.fr</CODE> |
| and <CODE>foo.html.de</CODE> both existed, but the browser did not express |
| a language preference, then <CODE>foo.html.fr</CODE> would be returned.<P> |
| |
| <P> |
| |
| Note that this directive only has an effect if a 'best' language |
| cannot be determined by any other means. Correctly implemented |
| HTTP/1.1 requests will mean this directive has no effect. |
| |
| <P> |
| |
| <STRONG>See also</STRONG>: |
| <A HREF="./mod_mime.html#defaultlanguage">DefaultLanguage</A> and |
| <A HREF="./mod_mime.html#addlanguage">AddLanguage</A> |
| |
| |
| <!--#include virtual="footer.html" --> |
| </BODY> |
| </HTML> |
| |