1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_easy_header 5Section: 3 6Source: libcurl 7See-also: 8 - CURLINFO_CONTENT_TYPE (3) 9 - CURLOPT_HEADERFUNCTION (3) 10 - curl_easy_nextheader (3) 11 - curl_easy_perform (3) 12 - libcurl-errors (3) 13Protocol: 14 - HTTP 15Added-in: 7.83.0 16--- 17 18# NAME 19 20curl_easy_header - get an HTTP header 21 22# SYNOPSIS 23 24~~~c 25#include <curl/curl.h> 26 27CURLHcode curl_easy_header(CURL *easy, 28 const char *name, 29 size_t index, 30 unsigned int origin, 31 int request, 32 struct curl_header **hout); 33~~~ 34 35# DESCRIPTION 36 37curl_easy_header(3) returns a pointer to a "curl_header" struct in **hout** 38with data for the HTTP response header *name*. The case insensitive 39null-terminated header name should be specified without colon. 40 41*index* 0 means asking for the first instance of the header. If the returned 42header struct has **amount** set larger than 1, it means there are more 43instances of the same header name available to get. Asking for a too big index 44makes **CURLHE_BADINDEX** get returned. 45 46The *origin* argument is for specifying which headers to receive, as a single 47HTTP transfer might provide headers from several different places and they may 48then have different importance to the user and headers using the same name 49might be used. The *origin* is a bitmask for what header sources you want. See 50the descriptions below. 51 52The *request* argument tells libcurl from which request you want headers 53from. A single transfer might consist of a series of HTTP requests and this 54argument lets you specify which particular individual request you want the 55headers from. 0 being the first request and then the number increases for 56further redirects or when multi-state authentication is used. Passing in -1 is 57a shortcut to "the last" request in the series, independently of the actual 58amount of requests used. 59 60libcurl stores and provides the actually used "correct" headers. If for 61example two headers with the same name arrive and the latter overrides the 62former, then only the latter is provided. If the first header survives the 63second, then only the first one is provided. An application using this API 64does not have to bother about multiple headers used wrongly. 65 66The memory for the returned struct is associated with the easy handle and 67subsequent calls to curl_easy_header(3) clobber the struct used in the 68previous calls for the same easy handle. The application needs to copy the data if 69it wants to keep it around. The memory used for the struct gets freed with 70calling curl_easy_cleanup(3) of the easy handle. 71 72The first line in an HTTP response is called the status line. It is not 73considered a header by this function. Headers are the "name: value" lines 74following the status. 75 76This function can be used before (all) headers have been received and is fine 77to call from within libcurl callbacks. It returns the state of the headers at 78the time it is called. 79 80# The header struct 81 82~~~c 83struct curl_header { 84 char *name; 85 char *value; 86 size_t amount; 87 size_t index; 88 unsigned int origin; 89 void *anchor; 90}; 91~~~ 92 93The data **name** field points to, is the same as the requested name, but 94might have a different case. 95 96The data **value** field points to, comes exactly as delivered over the 97network but with leading and trailing whitespace and newlines stripped 98off. The `value` data is null-terminated. For legacy HTTP/1 "folded headers", 99this API provides the full single value in an unfolded manner with a single 100whitespace between the lines. 101 102**amount** is how many headers using this name that exist, within the origin 103and request scope asked for. 104 105**index** is the zero based entry number of this particular header, which in 106case this header was used more than once in the requested scope can be larger 107than 0 but is always less than **amount**. 108 109The **origin** field in the "curl_header" struct has one of the origin bits 110set, indicating where from the header originates. At the time of this writing, 111there are 5 bits with defined use. The undocumented 27 remaining bits are 112reserved for future use and must not be assumed to have any particular value. 113 114**anchor** is a private handle used by libcurl internals. Do not modify. 115 116# ORIGINS 117 118## CURLH_HEADER 119 120The header arrived as a header from the server. 121 122## CURLH_TRAILER 123 124The header arrived as a trailer. A header that arrives after the body. 125 126## CURLH_CONNECT 127 128The header arrived in a CONNECT response. A CONNECT request is being done to 129setup a transfer "through" an HTTP(S) proxy. 130 131## CURLH_1XX 132 133The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate" 134response that might happen before the "real" response. 135 136## CURLH_PSEUDO 137 138The header is an HTTP/2 or HTTP/3 pseudo header 139 140# %PROTOCOLS% 141 142# EXAMPLE 143 144~~~c 145int main(void) 146{ 147 struct curl_header *type; 148 CURL *curl = curl_easy_init(); 149 if(curl) { 150 CURLHcode h; 151 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); 152 curl_easy_perform(curl); 153 h = curl_easy_header(curl, "Content-Type", 0, CURLH_HEADER, -1, &type); 154 curl_easy_cleanup(curl); 155 } 156} 157~~~ 158 159# %AVAILABILITY% 160 161# RETURN VALUE 162 163This function returns a CURLHcode indicating success or error. 164
