NAME
   HTTP::Negotiate - choose a variant to serve

SYNOPSIS
    use HTTP::Negotiate qw(choose);

    #  ID       QS     Content-Type   Encoding Char-Set        Lang   Size
    $variants =
     [['var1',  1.000, 'text/html',   undef,   'iso-8859-1',   'en',   3000],
      ['var2',  0.950, 'text/plain',  'gzip',  'us-ascii',     'no',    400],
      ['var3',  0.3,   'image/gif',   undef,   undef,          undef, 43555],
     ];

    @preferred = choose($variants, $request_headers);
    $the_one   = choose($variants);

DESCRIPTION
   This module provides a complete implementation of the HTTP content
   negotiation algorithm specified in draft-ietf-http-v11-spec-00.ps
   chapter 12. Content negotiation allows for the selection of a preferred
   content representation based upon attributes of the negotiable variants
   and the value of the various Accept* header fields in the request.

   The variants are ordered by preference by calling the function choose().

   The first parameter is reference to an array of the variants to choose
   among. Each element in this array is an array with the values [$id, $qs,
   $content_type, $content_encoding, $charset, $content_language,
   $content_length] whose meanings are described below. The
   $content_encoding and $content_language can be either a single scalar
   value or an array reference if there are several values.

   The second optional parameter is either a HTTP::Headers or a
   HTTP::Request object which is searched for "Accept*" headers. If this
   parameter is missing, then the accept specification is initialized from
   the CGI environment variables HTTP_ACCEPT, HTTP_ACCEPT_CHARSET,
   HTTP_ACCEPT_ENCODING and HTTP_ACCEPT_LANGUAGE.

   In an array context, choose() returns a list of [variant identifier,
   calculated quality, size] tuples. The values are sorted by quality,
   highest quality first. If the calculated quality is the same for two
   variants, then they are sorted by size (smallest first). *E.g.*:

     (['var1', 1, 2000], ['var2', 0.3, 512], ['var3', 0.3, 1024]);

   Note that also zero quality variants are included in the return list
   even if these should never be served to the client.

   In a scalar context, it returns the identifier of the variant with the
   highest score or `undef' if none have non-zero quality.

   If the $HTTP::Negotiate::DEBUG variable is set to TRUE, then a lot of
   noise is generated on STDOUT during evaluation of choose().

VARIANTS
   A variant is described by a list of the following values. If the
   attribute does not make sense or is unknown for a variant, then use
   `undef' instead.

   identifier
      This is a string that you use as the name for the variant. This
      identifier for the preferred variants returned by choose().

   qs This is a number between 0.000 and 1.000 that describes the "source
      quality". This is what draft-ietf-http-v11-spec-00.ps says about this
      value:

      Source quality is measured by the content provider as representing
      the amount of degradation from the original source. For example, a
      picture in JPEG form would have a lower qs when translated to the XBM
      format, and much lower qs when translated to an ASCII-art
      representation. Note, however, that this is a function of the source
      - an original piece of ASCII-art may degrade in quality if it is
      captured in JPEG form. The qs values should be assigned to each
      variant by the content provider; if no qs value has been assigned,
      the default is generally "qs=1".

   content-type
      This is the media type of the variant. The media type does not
      include a charset attribute, but might contain other parameters.
      Examples are:

        text/html
        text/html;version=2.0
        text/plain
        image/gif
        image/jpg

   content-encoding
      This is one or more content encodings that has been applied to the
      variant. The content encoding is generally used as a modifier to the
      content media type. The most common content encodings are:

        gzip
        compress

   content-charset
      This is the character set used when the variant contains text. The
      charset value should generally be `undef' or one of these:

        us-ascii
        iso-8859-1 ... iso-8859-9
        iso-2022-jp
        iso-2022-jp-2
        iso-2022-kr
        unicode-1-1
        unicode-1-1-utf-7
        unicode-1-1-utf-8

   content-language
      This describes one or more languages that are used in the variant.
      Language is described like this in draft-ietf-http-v11-spec-00.ps: A
      language is in this context a natural language spoken, written, or
      otherwise conveyed by human beings for communication of information
      to other human beings. Computer languages are explicitly excluded.

      The language tags are defined by RFC 3066. Examples are:

        no               Norwegian
        en               International English
        en-US            US English
        en-cockney

   content-length
      This is the number of bytes used to represent the content.

ACCEPT HEADERS
   The following Accept* headers can be used for describing content
   preferences in a request (This description is an edited extract from
   draft-ietf-http-v11-spec-00.ps):

   Accept
      This header can be used to indicate a list of media ranges which are
      acceptable as a response to the request. The "*" character is used to
      group media types into ranges, with "*/*" indicating all media types
      and "type/*" indicating all subtypes of that type.

      The parameter q is used to indicate the quality factor, which
      represents the user's preference for that range of media types. The
      parameter mbx gives the maximum acceptable size of the response
      content. The default values are: q=1 and mbx=infinity. If no Accept
      header is present, then the client accepts all media types with q=1.

      For example:

        Accept: audio/*;q=0.2;mbx=200000, audio/basic

      would mean: "I prefer audio/basic (of any size), but send me any
      audio type if it is the best available after an 80% mark-down in
      quality and its size is less than 200000 bytes"

   Accept-Charset
      Used to indicate what character sets are acceptable for the response.
      The "us-ascii" character set is assumed to be acceptable for all user
      agents. If no Accept-Charset field is given, the default is that any
      charset is acceptable. Example:

        Accept-Charset: iso-8859-1, unicode-1-1

   Accept-Encoding
      Restricts the Content-Encoding values which are acceptable in the
      response. If no Accept-Encoding field is present, the server may
      assume that the client will accept any content encoding. An empty
      Accept-Encoding means that no content encoding is acceptable.
      Example:

        Accept-Encoding: compress, gzip

   Accept-Language
      This field is similar to Accept, but restricts the set of natural
      languages that are preferred in a response. Each language may be
      given an associated quality value which represents an estimate of the
      user's comprehension of that language. For example:

        Accept-Language: no, en-gb;q=0.8, de;q=0.55

      would mean: "I prefer Norwegian, but will accept British English
      (with 80% comprehension) or German (with 55% comprehension).

COPYRIGHT
   Copyright 1996,2001 Gisle Aas.

   This library is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

AUTHOR
   Gisle Aas <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.