mod_negotiation.html revision e8473024b09c065e495db650170f3c4abaa43f80
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco BGCOLOR="#FFFFFF"
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco TEXT="#000000"
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco LINK="#0000FF"
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riesco VLINK="#000080"
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco ALINK="#FF0000"
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<!--#include virtual="header.html" -->
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián RiescoThis module is contained in the <CODE>mod_negotiation.c</CODE> file,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescoand is compiled in by default. It provides for <A
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoHREF="/content-negotiation.html">content negotiation</A>.
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián RiescoContent negotiation, or more accurately content selection, is the
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riescoselection of the document that best matches the clients
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riescocapabilities, from one of several available documents.
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián RiescoThere are two implementations of this.
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco<LI> A type map (a file with the handler <CODE>type-map</CODE>)
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riescowhich explicitly lists the files containing the variants.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<LI> A MultiViews search (enabled by the MultiViews
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<A HREF="core.html#options">Option</A>, where the server does an implicit
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescofilename pattern match, and choose from amongst the results.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoA type map has the same format as RFC822 mail headers. It contains document
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescodescriptions separated by blank lines, with lines beginning with a hash
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescocharacter ('#') treated as comments. A document description consists of
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescoseveral header records; records may be continued on multiple lines if the
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescocontinuation lines start with spaces. The leading space will be deleted
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescoand the lines concatenated. A header record consists of a keyword
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesconame, which always ends in a colon, followed by a value. Whitespace is allowed
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescobetween the header name and value, and between the tokens of value.
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián RiescoThe headers allowed are:
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DT>Content-Encoding:
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DD>The encoding of the file. Apache only recognizes encodings that are
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescodefined by an <A HREF="mod_mime.html#addencoding">AddEncoding</A> directive.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoThis normally includes the encodings <CODE>x-compress</CODE> for compress'd
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescofiles, and <CODE>x-gzip</CODE> for gzip'd files. The <CODE>x-</CODE> prefix
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescois ignored for encoding comparisons.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DT>Content-Language:
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DD>The language of the variant, as an Internet standard language tag
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco(RFC 1766). An example is <CODE>en</CODE>, meaning English.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DT>Content-Length:
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DD>The length of the file, in bytes. If this header is not present, then
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescothe actual length of the file is used.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DT>Content-Type:
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DD>The MIME media type of the document, with optional parameters.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoParameters are separated from the media type and from one another by a
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescosemi-colon, with a syntax of <CODE>name=value</CODE>. Common parameters
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DD>an integer specifying the version of the media type.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoFor <CODE>text/html</CODE> this defaults to 2, otherwise 0.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DD>a floating-point number with a value in the range 0.0 to 1.0,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco indicating the relative 'quality' of this variant
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco compared to the other available variants, independent of the client's
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco capabilities. For example, a jpeg file is usually of higher source
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco quality than an ascii file if it is attempting to represent a
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco photograph. However, if the resource being represented is ascii art,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco then an ascii file would have a higher source quality than a jpeg file.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco All qs values are therefore specific to a given resource.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<BLOCKQUOTE><CODE>Content-Type: image/jpeg; qs=0.8</CODE></BLOCKQUOTE>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<DD>The path to the file containing this variant, relative to the map file.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoA MultiViews search is enabled by the MultiViews
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoIf the server receives a request for <CODE>/some/dir/foo</CODE> and
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescodirectory looking for all files named <CODE>foo.*</CODE>, and effectively
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescofakes up a type map which names all those files, assigning them the same media
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescotypes and content-encodings it would have if the client had asked for
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescoone of them by name. It then chooses the best match to the client's
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescorequirements, and returns that document.<P>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<LI><A HREF="#cachenegotiateddocs">CacheNegotiatedDocs</A>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<LI><A HREF="#languagepriority">LanguagePriority</A>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<A HREF="/mod_mime.html#defaultlanguage">DefaultLanguage</A>,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<A HREF="/mod_mime.html#addencoding">AddEncoding</A>,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<A HREF="/mod_mime.html#addlanguage">AddLanguage</A>,
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<A HREF="/mod_mime.html#addtype">AddType</A>, and
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<H2><A NAME="cachenegotiateddocs">CacheNegotiatedDocs</A></H2>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco><STRONG>Syntax:</STRONG></A> CacheNegotiatedDocs <EM>boolean</EM><BR>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco><STRONG>Default:</STRONG></A> <CODE>CacheNegotiatedDocs off</CODE><BR>
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco><STRONG>Context:</STRONG></A> server config<BR>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco><STRONG>Module:</STRONG></A> mod_negotiation<BR>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco HREF="directive-dict.html#Compatibility"
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco><STRONG>Compatibility:</STRONG></A> CacheNegotiatedDocs is only available
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescoin Apache 1.1 and later. The syntax changed in version 2.0.<P>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<P>If set, this directive allows content-negotiated documents to be
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riescocached by proxy servers. This could mean that clients behind those
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescoproxys could retrieve versions of the documents that are not the best
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescomatch for their abilities, but it will make caching more
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<P>This directive only applies to requests which come from HTTP/1.0 browsers.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoHTTP/1.1 provides much better control over the caching of negotiated
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescodocuments, and this directive has no effect in responses to
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<P>Prior to version 2.0, CacheNegotiatedDocs did not take an argument;
d72e314a1952b4418fb1c98b17dbab0d16bba585Adrián Riescoit was turned on by the presence of the directive by itself.
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<H2><A NAME="languagepriority">LanguagePriority</A></H2>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco<!--%plaintext <?INDEX {\tt LanguagePriority} directive> -->
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riesco><STRONG>Syntax:</STRONG></A> LanguagePriority <EM>MIME-lang MIME-lang...</EM><BR>
0f77efdcc159eee5682aabf2b9a3c178c467b466Adrián Riesco><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
3f8cdebaede9921402318d525b57a9af8f9279d3Adrián Riesco><STRONG>Module:</STRONG></A> mod_negotiation<P>
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoThe LanguagePriority sets the precedence of language variants for the case
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescowhere the client does not express a preference, when handling a
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián RiescoMultiViews request. The list of <EM>MIME-lang</EM> are in order of decreasing
5318901bb69bf247e0f341312c800ba4ea87e46bAdrián Riescopreference. Example:
fecce42517d20490f893c4a9dee29b000e1653eaAdrián Riesco<BLOCKQUOTE><CODE>LanguagePriority en fr de</CODE></BLOCKQUOTE>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián RiescoFor a request for <CODE>foo.html</CODE>, where <CODE>foo.html.fr</CODE>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riescoand <CODE>foo.html.de</CODE> both existed, but the browser did not express
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riescoa language preference, then <CODE>foo.html.fr</CODE> would be returned.<P>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián RiescoNote that this directive only has an effect if a 'best' language
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riescocannot be determined by any other means. Correctly implemented
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián RiescoHTTP/1.1 requests will mean this directive has no effect.
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<A HREF="/mod_mime.html#defaultlanguage">DefaultLanguage</A> and
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<A HREF="/mod_mime.html#addlanguage">AddLanguage</A>
aea9000fc94442cbfc92596f4264473c0fce51e4Adrián Riesco<!--#include virtual="footer.html" -->