curl_easy_header(3)

1curl_easy_header(3)                 libcurl                curl_easy_header(3)
2
3
4

NAME

6       curl_easy_header - get an HTTP header
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLHcode curl_easy_header(CURL *easy,
12                                  const char *name,
13                                  size_t index,
14                                  unsigned int origin,
15                                  int request,
16                                  struct curl_header **hout);
17

DESCRIPTION

19       curl_easy_header(3) returns a pointer to a "curl_header" struct in hout
20       with data for the HTTP response header name. The case insensitive null-
21       terminated header name should be specified without colon.
22
23       index  0  means asking for the first instance of the header. If the re‐
24       turned header struct has amount set larger than 1, it means  there  are
25       more  instances  of the same header name available to get. Asking for a
26       too big index makes CURLHE_BADINDEX get returned.
27
28       The origin argument is for specifying which headers to  receive,  as  a
29       single  HTTP  transfer  might  provide  headers  from several different
30       places and they may then have different  importance  to  the  user  and
31       headers  using the same name might be used. The origin is a bitmask for
32       what header sources you want. See the descriptions below.
33
34       The request argument tells libcurl from which request you want  headers
35       from.  A single transfer might consist of a series of HTTP requests and
36       this argument lets you specify which particular individual request  you
37       want  the  headers  from. 0 being the first request and then the number
38       increases for further redirects or when multi-state  authentication  is
39       used.  Passing in -1 is a shortcut to "the last" request in the series,
40       independently of the actual amount of requests used.
41
42       libcurl stores and provides the actually used "correct" headers. If for
43       example  two headers with the same name arrive and the latter overrides
44       the former, then only the latter will be provided. If the first  header
45       survives  the  second, then only the first one will be provided. An ap‐
46       plication using this API does not have to bother about multiple headers
47       used wrongly.
48
49       The  memory  for the returned struct is associated with the easy handle
50       and subsequent calls to curl_easy_header(3)  will  clobber  the  struct
51       used  in the previous calls for the same easy handle. Applications need
52       to copy the data if it wants to keep it around. The memory used for the
53       struct gets freed with calling curl_easy_cleanup(3) of the easy handle.
54
55       The first line in an HTTP response is called the status line. It is not
56       considered a header by this function. Headers  are  the  "name:  value"
57       lines following the status.
58
59       This  function  can be used before (all) headers have been received and
60       is fine to call from within libcurl callbacks. It  will  always  return
61       the state of the headers at the time it is called.
62

The header struct

64       struct curl_header {
65          char *name;
66          char *value;
67          size_t amount;
68          size_t index;
69          unsigned int origin;
70          void *anchor;
71       };
72
73       The  data  name field points to, will be the same as the requested name
74       but it might have a different case.
75
76       The data value field points to, comes exactly  as  delivered  over  the
77       network  but with leading and trailing whitespace and newlines stripped
78       off. The `value` data is null-terminated.  For  legacy  HTTP/1  "folded
79       headers", this API provides the full single value in an unfolded manner
80       with a single whitespace between the lines.
81
82       amount is how many headers using this name that exist, within the  ori‐
83       gin and request scope asked for.
84
85       index  is  the zero based entry number of this particular header, which
86       in case this header was used more than once in the requested scope  can
87       be larger than 0 but is always less than amount.
88
89       The origin field in the "curl_header" struct has one of the origin bits
90       set, indicating where from the header originates. At the time  of  this
91       writing, there are 5 bits with defined use. The undocumented 27 remain‐
92       ing bits are reserved for future use and must not be  assumed  to  have
93       any particular value.
94
95       anchor is a private handle used by libcurl internals. Do not modify.
96

ORIGINS

98       CURLH_HEADER
99              The header arrived as a header from the server.
100
101       CURLH_TRAILER
102              The header arrived as a trailer. A header that arrives after the
103              body.
104
105       CURLH_CONNECT
106              The header arrived in a CONNECT response. A CONNECT  request  is
107              being done to setup a transfer "through" an HTTP(S) proxy.
108
109       CURLH_1XX
110              The header arrived in an HTTP 1xx response. A 1xx response is an
111              "intermediate" response that might happen before the "real"  re‐
112              sponse.
113
114       CURLH_PSEUDO
115              The header is an HTTP/2 or HTTP/3 pseudo header
116

EXAMPLE

118       struct curl_header *type;
119       CURLHcode h =
120         curl_easy_header(easy, "Content-Type", 0, CURLH_HEADER, -1, &type);
121

AVAILABILITY

123       Added in 7.83.0. Officially supported since 7.84.0.
124

RETURN VALUE

126       This function returns a CURLHcode indicating success or error.
127