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