CURLOPT_ACCEPT_ENCODING.md (3683B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: CURLOPT_ACCEPT_ENCODING 5 Section: 3 6 Source: libcurl 7 See-also: 8 - CURLOPT_HTTPHEADER (3) 9 - CURLOPT_HTTP_CONTENT_DECODING (3) 10 - CURLOPT_TRANSFER_ENCODING (3) 11 Protocol: 12 - HTTP 13 Added-in: 7.21.6 14 --- 15 16 # NAME 17 18 CURLOPT_ACCEPT_ENCODING - automatic decompression of HTTP downloads 19 20 # SYNOPSIS 21 22 ~~~c 23 #include <curl/curl.h> 24 25 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ACCEPT_ENCODING, char *enc); 26 ~~~ 27 28 # DESCRIPTION 29 30 Pass a char pointer argument specifying what encoding you would like. 31 32 Sets the contents of the Accept-Encoding: header sent in an HTTP request, and 33 enables decoding of a response when a Content-Encoding: header is received. 34 35 libcurl potentially supports several different compressed encodings depending 36 on what support that has been built-in. 37 38 To aid applications not having to bother about what specific algorithms this 39 particular libcurl build supports, libcurl allows a zero-length string to be 40 set ("") to ask for an Accept-Encoding: header to be used that contains all 41 built-in supported encodings. 42 43 Alternatively, you can specify exactly the encoding or list of encodings you 44 want in the response. The following encodings are supported: *identity*, 45 meaning non-compressed, *deflate* which requests the server to compress its 46 response using the zlib algorithm, *gzip* which requests the gzip algorithm, 47 (since curl 7.57.0) *br* which is brotli and (since curl 7.72.0) *zstd* which 48 is zstd. Provide them in the string as a comma-separated list of accepted 49 encodings, like: **"br, gzip, deflate"**. 50 51 Set CURLOPT_ACCEPT_ENCODING(3) to NULL to explicitly disable it, which makes 52 libcurl not send an Accept-Encoding: header and not decompress received 53 contents automatically. 54 55 You can also opt to just include the Accept-Encoding: header in your request 56 with CURLOPT_HTTPHEADER(3) but then there is no automatic decompressing when 57 receiving data. 58 59 This is a request, not an order; the server may or may not do it. This option 60 must be set (to any non-NULL value) or else any unsolicited encoding done by 61 the server is ignored. 62 63 Servers might respond with Content-Encoding even without getting a 64 Accept-Encoding: in the request. Servers might respond with a different 65 Content-Encoding than what was asked for in the request. 66 67 The Content-Length: servers send for a compressed response is supposed to 68 indicate the length of the compressed content so when auto decoding is enabled 69 it may not match the sum of bytes reported by the write callbacks (although, 70 sending the length of the non-compressed content is a common server mistake). 71 72 The application does not have to keep the string around after setting this 73 option. 74 75 Using this option multiple times makes the last set string override the 76 previous ones. 77 78 # HISTORY 79 80 This option was called CURLOPT_ENCODING before 7.21.6 81 82 # NOTES 83 84 The specific libcurl you are using must have been built with zlib to be able to 85 decompress gzip and deflate responses, with the brotli library to 86 decompress brotli responses and with the zstd library to decompress zstd 87 responses. 88 89 # DEFAULT 90 91 NULL 92 93 # %PROTOCOLS% 94 95 # EXAMPLE 96 97 ~~~c 98 int main(void) 99 { 100 CURL *curl = curl_easy_init(); 101 if(curl) { 102 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 103 104 /* enable all supported built-in compressions */ 105 curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, ""); 106 107 /* Perform the request */ 108 curl_easy_perform(curl); 109 } 110 } 111 ~~~ 112 113 # %AVAILABILITY% 114 115 # RETURN VALUE 116 117 curl_easy_setopt(3) returns a CURLcode indicating success or error. 118 119 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see 120 libcurl-errors(3).