lib/README.encoding

   1
   2                     Content Encoding Support for libcurl
   3
   4 * About content encodings:
   5
   6 HTTP/1.1 [RFC 2616] specifies that a client may request that a server encode
   7 its response. This is usually used to compress a response using one of a set
   8 of commonly available compression techniques. These schemes are `deflate' (the
   9 zlib algorithm), `gzip' and `compress' [sec 3.5, RFC 2616]. A client requests
  10 that the sever perform an encoding by including an Accept-Encoding header in
  11 the request document. The value of the header should be one of the recognized
  12 tokens `deflate', ... (there's a way to register new schemes/tokens, see sec
  13 3.5 of the spec). A server MAY honor the client's encoding request. When a
  14 response is encoded, the server includes a Content-Encoding header in the
  15 response. The value of the Content-Encoding header indicates which scheme was
  16 used to encode the data.
  17
  18 A client may tell a server that it can understand several different encoding
  19 schemes. In this case the server may choose any one of those and use it to
  20 encode the response (indicating which one using the Content-Encoding header).
  21 It's also possible for a client to attach priorities to different schemes so
  22 that the server knows which it prefers. See sec 14.3 of RFC 2616 for more
  23 information on the Accept-Encoding header.
  24
  25 * Current support for content encoding:
  26
  27 Support for the 'deflate' and 'gzip' content encoding are supported by
  28 libcurl. Both regular and chunked transfers should work fine.  The library
  29 zlib is required for this feature. 'deflate' support was added by James
  30 Gallagher, and support for the 'gzip' encoding was added by Dan Fandrich.
  31
  32 * The libcurl interface:
  33
  34 To cause libcurl to request a content encoding use:
  35
  36     curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, <string>)
  37
  38 where <string> is the intended value of the Accept-Encoding header.
  39
  40 Currently, libcurl only understands how to process responses that use the
  41 "deflate" or "gzip" Content-Encoding, so the only values for
  42 CURLOPT_ACCEPT_ENCODING that will work (besides "identity," which does
  43 nothing) are "deflate" and "gzip" If a response is encoded using the
  44 "compress" or methods, libcurl will return an error indicating that the
  45 response could not be decoded.  If <string> is NULL no Accept-Encoding header
  46 is generated.  If <string> is a zero-length string, then an Accept-Encoding
  47 header containing all supported encodings will be generated.
  48
  49 The CURLOPT_ACCEPT_ENCODING must be set to any non-NULL value for content to
  50 be automatically decoded.  If it is not set and the server still sends encoded
  51 content (despite not having been asked), the data is returned in its raw form
  52 and the Content-Encoding type is not checked.
  53
  54 * The curl interface:
  55
  56 Use the --compressed option with curl to cause it to ask servers to compress
  57 responses using any format supported by curl.
  58
  59 James Gallagher <jgallagher@gso.uri.edu>
  60 Dan Fandrich <dan@coneharvesters.com>