| 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_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 CURLOPT_ENCODING |
| 42 |
that will work (besides "identity," which does nothing) are "deflate" and |
| 43 |
"gzip" If a response is encoded using the "compress" or methods, libcurl will |
| 44 |
return an error indicating that the response could not be decoded. If |
| 45 |
<string> is NULL no Accept-Encoding header is generated. If <string> is a |
| 46 |
zero-length string, then an Accept-Encoding header containing all supported |
| 47 |
encodings will be generated. |
| 48 |
|
| 49 |
The CURLOPT_ENCODING must be set to any non-NULL value for content to be |
| 50 |
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 deflate. |
| 58 |
|
| 59 |
James Gallagher <[email protected]> |
| 60 |
Dan Fandrich <[email protected]> |