MAN page from RedHat Other LWP.pm-5.48-2.i386.rpm

lib::HTTP::Negotiate

Section: User Contributed Perl Documentation (3)
Updated: libwww-perl-5.48
Index

NAME

choose - choose a variant of a document to serve (HTTP content negotiation)

SYNOPSIS

 use HTTP::Negotiate;

 #  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],  ];

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

DESCRIPTION

This module provides a complete implementation of the HTTP contentnegotiation algorithm specified in draft-ietf-http-v11-spec-00.pschapter 12. Content negotiation allows for the selection of apreferred content representation based upon attributes of thenegotiable variants and the value of the various Accept* header fieldsin the request.

The variants are ordered by preference by calling the functionchoose().

The first parameter is reference to an array of the variants tochoose 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 describedbelow. The $content_encoding and $content_language can be either asingle scalar value or an array reference if there are several values.

The second optional parameter is either a HTTP::Headers or a HTTP::Requestobject which is searched for ``Accept*'' headers. If thisparameter is missing, then the accept specification is initializedfrom 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 variantidentifier/calculated quality pairs. The values are sorted byquality, highest quality first. If the calculated quality is the samefor two variants, then they are sorted by size (smallest first). E.g.:

  (['var1' => 1], ['var2', 0.3], ['var3' => 0]);

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

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

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

VARIANTS

A variant is described by a list of the following values. If theattribute does not make sense or is unknown for a variant, then useundef instead.

identifier

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

qs

This is a number between 0.000 and 1.000 that describes the ``sourcequality''. This is what draft-ietf-http-v11-spec-00.ps says about thisvalue:

Source quality is measured by the content provider as representing theamount of degradation from the original source. For example, apicture in JPEG form would have a lower qs when translated to the XBMformat, and much lower qs when translated to an ASCII-artrepresentation. Note, however, that this is a function of the source- an original piece of ASCII-art may degrade in quality if it iscaptured in JPEG form. The qs values should be assigned to eachvariant by the content provider; if no qs value has been assigned, thedefault is generally ``qs=1''.

content-type

This is the media type of the variant. The media type does notinclude 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 thevariant. The content encoding is generally used as a modifier to thecontent 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: Alanguage is in this context a natural language spoken, written, orotherwise conveyed by human beings for communication of information toother human beings. Computer languages are explicitly excluded.

The language tags are defined by RFC-1766. Examplesare:

  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 contentpreferences in a request (This description is an edited extract fromdraft-ietf-http-v11-spec-00.ps):

Accept

This header can be used to indicate a list of media ranges which areacceptable as a reponse to the request. The ``*'' character is used togroup media types into ranges, with ``*/*'' indicating all media typesand ``type/*'' indicating all subtypes of that type.

The parameter q is used to indicate the quality factor, whichrepresents the user's preference for that range of media types. Theparameter mbx gives the maximum acceptable size of the responsecontent. The default values are: q=1 and mbx=infinity. If no Acceptheader 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 audiotype if it is the best available after an 80% mark-down in quality andits 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 useragents. If no Accept-Charset field is given, the default is that anycharset is acceptable. Example:

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

Accept-Encoding

Restricts the Content-Encoding values which are acceptable in theresponse. If no Accept-Encoding field is present, the server mayassume that the client will accept any content encoding. An emptyAccept-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 naturallanguages that are preferred in a response. Each language may begiven an associated quality value which represents an estimate of theuser'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 (with80% comprehension) or German (with 55% comprehension).

COPYRIGHT

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

AUTHOR

Gisle Aas <aasAATTsn.no>

This document was created byman2html,using the manual pages.