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