mod_negotiation.html revision 1974a700e8a7afa11e008101503b014213aa9c17
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<HTML>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<HEAD>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<TITLE>Apache module mod_negotiation</TITLE>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass</HEAD>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<BODY
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass BGCOLOR="#FFFFFF"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass TEXT="#000000"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass LINK="#0000FF"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass VLINK="#000080"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass ALINK="#FF0000"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<!--#include virtual="header.html" -->
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<H1 ALIGN="CENTER">Module mod_negotiation</H1>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<p>This module provides for <A
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassHREF="/content-negotiation.html">content negotiation</A>.</p>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<P><A
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassHREF="module-dict.html#Status"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassREL="Help"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass><STRONG>Status:</STRONG></A> Base
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<BR>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<A
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassHREF="module-dict.html#SourceFile"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassREL="Help"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass><STRONG>Source File:</STRONG></A> mod_negotiation.c
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<BR>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<A
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassHREF="module-dict.html#ModuleIdentifier"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassREL="Help"
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass><STRONG>Module Identifier:</STRONG></A> negotiation_module
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass</P>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<H2>Summary</H2>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassContent negotiation, or more accurately content selection, is the
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassselection of the document that best matches the clients
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glasscapabilities, from one of several available documents.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassThere are two implementations of this.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<UL>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<LI> A type map (a file with the handler <CODE>type-map</CODE>)
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glasswhich explicitly lists the files containing the variants.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<LI> A MultiViews search (enabled by the MultiViews
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<A HREF="core.html#options">Option</A>, where the server does an implicit
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassfilename pattern match, and choose from amongst the results.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass</UL>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<H2>Directives</H2>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<UL>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<LI><A HREF="#cachenegotiateddocs">CacheNegotiatedDocs</A>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<LI><A HREF="#languagepriority">LanguagePriority</A>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass</UL>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<STRONG>See also</STRONG>:
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<A HREF="/mod_mime.html#defaultlanguage">DefaultLanguage</A>,
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<A HREF="/mod_mime.html#addencoding">AddEncoding</A>,
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<A HREF="/mod_mime.html#addlanguage">AddLanguage</A>,
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<A HREF="/mod_mime.html#addtype">AddType</A>, and
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<A HREF="core.html#options">Option</A>.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<H2>Type maps</H2>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassA type map has the same format as RFC822 mail headers. It contains document
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassdescriptions separated by blank lines, with lines beginning with a hash
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glasscharacter ('#') treated as comments. A document description consists of
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassseveral header records; records may be continued on multiple lines if the
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glasscontinuation lines start with spaces. The leading space will be deleted
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassand the lines concatenated. A header record consists of a keyword
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassname, which always ends in a colon, followed by a value. Whitespace is allowed
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassbetween the header name and value, and between the tokens of value.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassThe headers allowed are:
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DL>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DT>Content-Encoding:
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DD>The encoding of the file. Apache only recognizes encodings that are
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassdefined by an <A HREF="mod_mime.html#addencoding">AddEncoding</A> directive.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassThis normally includes the encodings <CODE>x-compress</CODE> for compress'd
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassfiles, and <CODE>x-gzip</CODE> for gzip'd files. The <CODE>x-</CODE> prefix
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassis ignored for encoding comparisons.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DT>Content-Language:
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DD>The language of the variant, as an Internet standard language tag
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass(RFC 1766). An example is <CODE>en</CODE>, meaning English.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DT>Content-Length:
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DD>The length of the file, in bytes. If this header is not present, then
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassthe actual length of the file is used.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DT>Content-Type:
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DD>The MIME media type of the document, with optional parameters.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassParameters are separated from the media type and from one another by a
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glasssemi-colon, with a syntax of <CODE>name=value</CODE>. Common parameters
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glassinclude:
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DL>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DT>level
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DD>an integer specifying the version of the media type.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassFor <CODE>text/html</CODE> this defaults to 2, otherwise 0.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DT>qs
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DD>a floating-point number with a value in the range 0.0 to 1.0,
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass indicating the relative 'quality' of this variant
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass compared to the other available variants, independent of the client's
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass capabilities. For example, a jpeg file is usually of higher source
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass quality than an ascii file if it is attempting to represent a
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass photograph. However, if the resource being represented is ascii art,
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass then an ascii file would have a higher source quality than a jpeg file.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass All qs values are therefore specific to a given resource.
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass</DL>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav GlassExample:
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<BLOCKQUOTE><CODE>Content-Type: image/jpeg; qs=0.8</CODE></BLOCKQUOTE>
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DT>URI:
c72174b1e1e45cb0dd5a7380cae710fb25da05d4Dav Glass<DD>The path to the file containing this variant, relative to the map file.
</DL>
<H2>MultiViews</H2>
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>
<HR>
<H2><A NAME="cachenegotiateddocs">CacheNegotiatedDocs</A> directive</H2>
<A
HREF="directive-dict.html#Syntax"
REL="Help"
><STRONG>Syntax:</STRONG></A> CacheNegotiatedDocs <EM>boolean</EM><BR>
<A
HREF="directive-dict.html#Default"
REL="Help"
><STRONG>Default:</STRONG></A> <CODE>CacheNegotiatedDocs off</CODE><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. The syntax changed in version 2.0.<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.
<P>Prior to version 2.0, CacheNegotiatedDocs did not take an argument;
it was turned on by the presence of the directive by itself.
<H2><A NAME="languagepriority">LanguagePriority</A> directive</H2>
<!--%plaintext &lt;?INDEX {\tt LanguagePriority} directive&gt; -->
<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>