home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _7cb32de782a1ab15a2da7d5e0f2cc557 < prev    next >
Text File  |  2000-03-23  |  10KB  |  247 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>choose - choose a variant of a document to serve</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> choose - choose a variant of a document to serve</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <LI><A HREF="#variants">VARIANTS</A></LI>
  26.     <LI><A HREF="#accept headers">ACCEPT HEADERS</A></LI>
  27.     <LI><A HREF="#copyright">COPYRIGHT</A></LI>
  28.     <LI><A HREF="#author">AUTHOR</A></LI>
  29. </UL>
  30. <!-- INDEX END -->
  31.  
  32. <HR>
  33. <P>
  34. <H1><A NAME="name">NAME</A></H1>
  35. <P>choose - choose a variant of a document to serve (HTTP content negotiation)</P>
  36. <P>
  37. <HR>
  38. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  39. <UL>
  40. <LI>Linux</LI>
  41. <LI>Solaris</LI>
  42. <LI>Windows</LI>
  43. </UL>
  44. <HR>
  45. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  46. <PRE>
  47.  use HTTP::Negotiate;</PRE>
  48. <PRE>
  49.  #  ID       QS     Content-Type   Encoding Char-Set        Lang   Size
  50.  $variants =
  51.   [['var1',  1.000, 'text/html',   undef,   'iso-8859-1',   'en',   3000],
  52.    ['var2',  0.950, 'text/plain',  'gzip',  'us-ascii',     'no',    400],
  53.    ['var3',  0.3,   'image/gif',   undef,   undef,          undef, 43555],
  54.   ];</PRE>
  55. <PRE>
  56.  @prefered = choose($variants, $request_headers);
  57.  $the_one  = choose($variants);</PRE>
  58. <P>
  59. <HR>
  60. <H1><A NAME="description">DESCRIPTION</A></H1>
  61. <P>This module provides a complete implementation of the HTTP content
  62. negotiation algorithm specified in <EM>draft-ietf-http-v11-spec-00.ps</EM>
  63. chapter 12.  Content negotiation allows for the selection of a
  64. preferred content representation based upon attributes of the
  65. negotiable variants and the value of the various Accept* header fields
  66. in the request.</P>
  67. <P>The variants are ordered by preference by calling the function
  68. choose().</P>
  69. <P>The first parameter is reference to an array of the variants to
  70. choose among.
  71. Each element in this array is an array with the values [$id, $qs,
  72. $content_type, $content_encoding, $charset, $content_language,
  73. $content_length] whose meanings are described
  74. below. The $content_encoding and $content_language can be either a
  75. single scalar value or an array reference if there are several values.</P>
  76. <P>The second optional parameter is either a HTTP::Headers or a HTTP::Request
  77. object which is searched for ``Accept*'' headers.  If this
  78. parameter is missing, then the accept specification is initialized
  79. from the CGI environment variables HTTP_ACCEPT, HTTP_ACCEPT_CHARSET,
  80. HTTP_ACCEPT_ENCODING and HTTP_ACCEPT_LANGUAGE.</P>
  81. <P>In an array context, <CODE>choose()</CODE> returns a list of variant
  82. identifier/calculated quality pairs.  The values are sorted by
  83. quality, highest quality first.  If the calculated quality is the same
  84. for two variants, then they are sorted by size (smallest first). <EM>E.g.</EM>:</P>
  85. <PRE>
  86.   (['var1' => 1], ['var2', 0.3], ['var3' => 0]);</PRE>
  87. <P>Note that also zero quality variants are included in the return list
  88. even if these should never be served to the client.</P>
  89. <P>In a scalar context, it returns the identifier of the variant with the
  90. highest score or <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> if none have non-zero quality.</P>
  91. <P>If the $HTTP::Negotiate::DEBUG variable is set to TRUE, then a lot of
  92. noise is generated on STDOUT during evaluation of choose().</P>
  93. <P>
  94. <HR>
  95. <H1><A NAME="variants">VARIANTS</A></H1>
  96. <P>A variant is described by a list of the following values.  If the
  97. attribute does not make sense or is unknown for a variant, then use
  98. <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> instead.</P>
  99. <DL>
  100. <DT><STRONG><A NAME="item_identifier">identifier</A></STRONG><BR>
  101. <DD>
  102. This is a string that you use as the name for the variant.  This
  103. identifier for the preferred variants returned by choose().
  104. <P></P>
  105. <DT><STRONG><A NAME="item_qs">qs</A></STRONG><BR>
  106. <DD>
  107. This is a number between 0.000 and 1.000 that describes the ``source
  108. quality''.  This is what <EM>draft-ietf-http-v11-spec-00.ps</EM> says about this
  109. value:
  110. <P>Source quality is measured by the content provider as representing the
  111. amount of degradation from the original source.  For example, a
  112. picture in JPEG form would have a lower qs when translated to the XBM
  113. format, and much lower qs when translated to an ASCII-art
  114. representation.  Note, however, that this is a function of the source
  115. - an original piece of ASCII-art may degrade in quality if it is
  116. captured in JPEG form.  The qs values should be assigned to each
  117. variant by the content provider; if no qs value has been assigned, the
  118. default is generally ``qs=1''.</P>
  119. <P></P>
  120. <DT><STRONG><A NAME="item_content%2Dtype">content-type</A></STRONG><BR>
  121. <DD>
  122. This is the media type of the variant.  The media type does not
  123. include a charset attribute, but might contain other parameters.
  124. Examples are:
  125. <PRE>
  126.   text/html
  127.   text/html;version=2.0
  128.   text/plain
  129.   image/gif
  130.   image/jpg</PRE>
  131. <P></P>
  132. <DT><STRONG><A NAME="item_content%2Dencoding">content-encoding</A></STRONG><BR>
  133. <DD>
  134. This is one or more content encodings that has been applied to the
  135. variant.  The content encoding is generally used as a modifier to the
  136. content media type.  The most common content encodings are:
  137. <PRE>
  138.   gzip
  139.   compress</PRE>
  140. <P></P>
  141. <DT><STRONG><A NAME="item_content%2Dcharset">content-charset</A></STRONG><BR>
  142. <DD>
  143. This is the character set used when the variant contains text.
  144. The charset value should generally be <A HREF="../../../lib/Pod/perlfunc.html#item_undef"><CODE>undef</CODE></A> or one of these:
  145. <PRE>
  146.   us-ascii
  147.   iso-8859-1 ... iso-8859-9
  148.   iso-2022-jp
  149.   iso-2022-jp-2
  150.   iso-2022-kr
  151.   unicode-1-1
  152.   unicode-1-1-utf-7
  153.   unicode-1-1-utf-8</PRE>
  154. <P></P>
  155. <DT><STRONG><A NAME="item_content%2Dlanguage">content-language</A></STRONG><BR>
  156. <DD>
  157. This describes one or more languages that are used in the variant.
  158. Language is described like this in <EM>draft-ietf-http-v11-spec-00.ps</EM>: A
  159. language is in this context a natural language spoken, written, or
  160. otherwise conveyed by human beings for communication of information to
  161. other human beings.  Computer languages are explicitly excluded.
  162. <P>The language tags are defined by RFC-1766.  Examples
  163. are:</P>
  164. <PRE>
  165.   no               Norwegian
  166.   en               International English
  167.   en-US            US English
  168.   en-cockney</PRE>
  169. <P></P>
  170. <DT><STRONG><A NAME="item_content%2Dlength">content-length</A></STRONG><BR>
  171. <DD>
  172. This is the number of bytes used to represent the content.
  173. <P></P></DL>
  174. <P>
  175. <HR>
  176. <H1><A NAME="accept headers">ACCEPT HEADERS</A></H1>
  177. <P>The following Accept* headers can be used for describing content
  178. preferences in a request (This description is an edited extract from
  179. <EM>draft-ietf-http-v11-spec-00.ps</EM>):</P>
  180. <DL>
  181. <DT><STRONG><A NAME="item_Accept">Accept</A></STRONG><BR>
  182. <DD>
  183. This header can be used to indicate a list of media ranges which are
  184. acceptable as a reponse to the request.  The ``*'' character is used to
  185. group media types into ranges, with ``*/*'' indicating all media types
  186. and ``type/*'' indicating all subtypes of that type.
  187. <P>The parameter q is used to indicate the quality factor, which
  188. represents the user's preference for that range of media types.  The
  189. parameter mbx gives the maximum acceptable size of the response
  190. content. The default values are: q=1 and mbx=infinity. If no Accept
  191. header is present, then the client accepts all media types with q=1.</P>
  192. <P>For example:</P>
  193. <PRE>
  194.   Accept: audio/*;q=0.2;mbx=200000, audio/basic</PRE>
  195. <P>would mean: ``I prefer audio/basic (of any size), but send me any audio
  196. type if it is the best available after an 80% mark-down in quality and
  197. its size is less than 200000 bytes''</P>
  198. <P></P>
  199. <DT><STRONG><A NAME="item_Accept%2DCharset">Accept-Charset</A></STRONG><BR>
  200. <DD>
  201. Used to indicate what character sets are acceptable for the response.
  202. The ``us-ascii'' character set is assumed to be acceptable for all user
  203. agents.  If no Accept-Charset field is given, the default is that any
  204. charset is acceptable.  Example:
  205. <PRE>
  206.   Accept-Charset: iso-8859-1, unicode-1-1</PRE>
  207. <P></P>
  208. <DT><STRONG><A NAME="item_Accept%2DEncoding">Accept-Encoding</A></STRONG><BR>
  209. <DD>
  210. Restricts the Content-Encoding values which are acceptable in the
  211. response.  If no Accept-Encoding field is present, the server may
  212. assume that the client will accept any content encoding.  An empty
  213. Accept-Encoding means that no content encoding is acceptable.  Example:
  214. <PRE>
  215.   Accept-Encoding: compress, gzip</PRE>
  216. <P></P>
  217. <DT><STRONG><A NAME="item_Accept%2DLanguage">Accept-Language</A></STRONG><BR>
  218. <DD>
  219. This field is similar to Accept, but restricts the set of natural
  220. languages that are preferred in a response.  Each language may be
  221. given an associated quality value which represents an estimate of the
  222. user's comprehension of that language.  For example:
  223. <PRE>
  224.   Accept-Language: no, en-gb;q=0.8, de;q=0.55</PRE>
  225. <P>would mean: ``I prefer Norwegian, but will accept British English (with
  226. 80% comprehension) or German (with 55% comprehension).</P>
  227. <P></P></DL>
  228. <P>
  229. <HR>
  230. <H1><A NAME="copyright">COPYRIGHT</A></H1>
  231. <P>Copyright 1996, Gisle Aas.</P>
  232. <P>This library is free software; you can redistribute it and/or
  233. modify it under the same terms as Perl itself.</P>
  234. <P>
  235. <HR>
  236. <H1><A NAME="author">AUTHOR</A></H1>
  237. <P>Gisle Aas <<A HREF="mailto:aas@sn.no">aas@sn.no</A>></P>
  238. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  239. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  240. <STRONG><P CLASS=block> choose - choose a variant of a document to serve</P></STRONG>
  241. </TD></TR>
  242. </TABLE>
  243.  
  244. </BODY>
  245.  
  246. </HTML>
  247.