Headers API
libcurl offers an API for iterating over all received HTTP headers and forextracting the contents from specific ones.
When returning header content, libcurl trims leading and trailing whitespacebut does not modify or change content in any other way.
This API was made official and is provided for real starting in libcurl7.84.0.
Header origins
HTTP headers are key value pairs that are sent from the server in a fewdifferentorigins during a transfer. libcurl collects all headers andprovides easy access to them for applications.
HTTP headers can arrive as
- CURLH_HEADER - before regular response content.
- CURLH_TRAILER - fields arrivingafter the response content
- CURLH_CONNECT - response headers in the proxy
CONNECTrequest thatmight have been done before the actual server request - CURLH_1XX - headers in the potential 1xx HTTP responses that might havepreceded the following >= 2xx response code.
- CURLH_PSEUDO - HTTP/2 and HTTP/3 level headers that start with colon(
:)
Request number
A single HTTP transfer done with libcurl might consist of a series of HTTPrequests and therequest argument to the header API functions lets youspecify which particular individual request you want the headers from. 0 beingthe first request and then the number increases for further redirects or whenmulti-state authentication is used. Passing in-1 is a shortcut to the lastrequest in the series, independently of the actual amount of requests used.
Header folding
HTTP/1 headers supports a deprecated format calledfolding, which means thatthere is a continuation line after a header, making the line folded.
The headers API supports folded headers and returns such contents unfolded -where the different parts are separated by a single whitespace character.
When
The two header API function calls are perfectly possible to call at any timeduring a transfer, both from inside and outside of callbacks. It is howeverimportant to remember that the API only returns information about the state ofthe headers at the exact moment it is called, which might not be the finalstatus if you call it while the transfer is still in progress.