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