mod_negotiation.html revision d030d579df50673f566f5dbcd1904fd59cd310e0
40742313779ee5e43be93a9191f1c86412cf183bKrzysztof Kosiński<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler BGCOLOR="#FFFFFF"
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler TEXT="#000000"
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler LINK="#0000FF"
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler VLINK="#000080"
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler ALINK="#FF0000"
40742313779ee5e43be93a9191f1c86412cf183bKrzysztof Kosiński<!--#include virtual="header.html" -->
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerThis module is contained in the <CODE>mod_negotiation.c</CODE> file,
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerand is compiled in by default. It provides for <A
b980eb7f577389245ccf42ab7fa9e19801fecbd2Krzysztof KosińskiHREF="/content-negotiation.html">content negotiation</A>.
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerContent negotiation, or more accurately content selection, is the
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerselection of the document that best matches the clients
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlercapabilities, from one of several available documents.
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerThere are two implementations of this.
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<LI> A type map (a file with the handler <CODE>type-map</CODE>)
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerwhich explicitly lists the files containing the variants.
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<LI> A MultiViews search (enabled by the MultiViews
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<A HREF="core.html#options">Option</A>, where the server does an implicit
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerfilename pattern match, and choose from amongst the results.
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerA type map has the same format as RFC822 mail headers. It contains document
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerdescriptions separated by blank lines, with lines beginning with a hash
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlercharacter ('#') treated as comments. A document description consists of
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerseveral header records; records may be continued on multiple lines if the
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlercontinuation lines start with spaces. The leading space will be deleted
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerand the lines concatenated. A header record consists of a keyword
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlername, which always ends in a colon, followed by a value. Whitespace is allowed
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerbetween the header name and value, and between the tokens of value.
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerThe headers allowed are:
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<DT>Content-Encoding:
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<DD>The encoding of the file. Currently only two encodings are recognized
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerby http; <CODE>x-compress</CODE> for compressed files, and <CODE>x-gzip</CODE>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerfor gzipped files.
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<DT>Content-Language:
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<DD>The language of the variant, as an Internet standard language code, such
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<DT>Content-Length:
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<DD>The length of the file, in bytes. If this header is not present, then
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerthe actual length of the file is used.
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<DT>Content-Type:
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<DD>The MIME media type of the document, with optional parameters.
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerparameters are separated from the media type and from one another by
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlersemi-colons. Parameter syntax is name=value; allowed parameters are:
b980eb7f577389245ccf42ab7fa9e19801fecbd2Krzysztof Kosiński<DD>the value is an integer, which specifies the version of the media type.
b980eb7f577389245ccf42ab7fa9e19801fecbd2Krzysztof KosińskiFor <CODE>text/html</CODE> this defaults to 2, otherwise 0.
b980eb7f577389245ccf42ab7fa9e19801fecbd2Krzysztof Kosiński<DD>the value is a floating-point number with value between 0. and 1.
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerIt indications the 'quality' of this variant.
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<BLOCKQUOTE><CODE>Content-Type: image/jpeg; qs=0.8</CODE></BLOCKQUOTE>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<DD>The path to the file containing this variant, relative to the map file.
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerA MultiViews search is enabled by the MultiViews
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerIf the server receives a request for <CODE>/some/dir/foo</CODE> and
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<CODE>/some/dir/foo</CODE> does <EM>not</EM> exist, then the server reads the
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerdirectory looking for all files named <CODE>foo.*</CODE>, and effectively
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerfakes up a type map which names all those files, assigning them the same media
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlertypes and content-encodings it would have if the client had asked for
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerone of them by name. It then chooses the best match to the client's
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerrequirements, and returns that document.<P>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<LI><A HREF="#cachenegotiateddocs">CacheNegotiatedDocs</A>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<LI><A HREF="#languagepriority">LanguagePriority</A>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<H2><A NAME="cachenegotiateddocs">CacheNegotiatedDocs</A></H2>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler><STRONG>Syntax:</STRONG></A> CacheNegotiatedDocs<BR>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler><STRONG>Module:</STRONG></A> mod_negotiation<BR>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler HREF="directive-dict.html#Compatibility"
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler><STRONG>Compatibility:</STRONG></A> CacheNegotiatedDocs is only available
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerin Apache 1.1 and later.<P>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<P>If set, this directive allows content-negotiated documents to be
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlercached by proxy servers. This could mean that clients behind those
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerproxys could retrieve versions of the documents that are not the best
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlermatch for their abilities, but it will make caching more
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerThis directive only applies to requests which come from HTTP/1.0 browsers.
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerHTTP/1.1 provides much better control over the caching of negotiated
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerdocuments, and this directive has no effect in responses to
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<H2><A NAME="languagepriority">LanguagePriority</A></H2>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<!--%plaintext <?INDEX {\tt LanguagePriority} directive> -->
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler><STRONG>Syntax:</STRONG></A> LanguagePriority <EM>mime-lang mime-lang...</EM><BR>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerThe LanguagePriority sets the precedence of language variants for the case
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerwhere the client does not express a preference, when handling a
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerMultiViews request. The list of <EM>mime-lang</EM> are in order of decreasing
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerpreference. Example:
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<BLOCKQUOTE><CODE>LanguagePriority en fr de</CODE></BLOCKQUOTE>
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerFor a request for <CODE>foo.html</CODE>, where <CODE>foo.html.fr</CODE>
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlerand <CODE>foo.html.de</CODE> both existed, but the browser did not express
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlera language preference, then <CODE>foo.html.fr</CODE> would be returned.<P>
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerNote that this directive only has an effect if a 'best' language
f6df6236fcf18524e049bba12b69704af32eff90Josh Andlercannot be determined by other any other means. Correctly implemented
f6df6236fcf18524e049bba12b69704af32eff90Josh AndlerHTTP/1.1 requests will mean this directive has no effect.
f6df6236fcf18524e049bba12b69704af32eff90Josh Andler<!--#include virtual="footer.html" -->