xref: /curl/docs/libcurl/curl_easy_nextheader.md (revision 5a488251) 
1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: curl_easy_nextheader
5Section: 3
6Source: libcurl
7See-also:
8  - curl_easy_header (3)
9  - curl_easy_perform (3)
10Protocol:
11  - HTTP
12Added-in: 7.83.0
13---
14
15# NAME
16
17curl_easy_nextheader - get the next HTTP header
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24struct curl_header *curl_easy_nextheader(CURL *easy,
25                                         unsigned int origin,
26                                         int request,
27                                         struct curl_header *prev);
28~~~
29
30# DESCRIPTION
31
32This function lets an application iterate over all previously received HTTP
33headers.
34
35The *origin* argument is for specifying which headers to receive, as a single
36HTTP transfer might provide headers from several different places and they may
37then have different importance to the user and headers using the same name
38might be used. The *origin* is a bitmask for what header sources you want. See
39the curl_easy_header(3) man page for the origin descriptions.
40
41The *request* argument tells libcurl from which request you want headers
42from. A single transfer might consist of a series of HTTP requests and this
43argument lets you specify which particular individual request you want the
44headers from. 0 being the first request and then the number increases for
45further redirects or when multi-state authentication is used. Passing in -1 is
46a shortcut to "the last" request in the series, independently of the actual
47amount of requests used.
48
49It is suggested that you pass in the same **origin** and **request** when
50iterating over a range of headers as changing the value mid-loop might give
51you unexpected results.
52
53If *prev* is NULL, this function returns a pointer to the first header stored
54within the given scope (origin + request).
55
56If *prev* is a pointer to a previously returned header struct,
57curl_easy_nextheader(3) returns a pointer the next header stored within the
58given scope. This way, an application can iterate over all available headers.
59
60The memory for the struct this points to, is owned and managed by libcurl and
61is associated with the easy handle. Applications must copy the data if they
62want it to survive subsequent API calls or the life-time of the easy handle.
63
64# %PROTOCOLS%
65
66# EXAMPLE
67
68~~~c
69int main(void)
70{
71  struct curl_header *prev = NULL;
72  struct curl_header *h;
73
74  CURL *curl = curl_easy_init();
75  if(curl) {
76    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
77    curl_easy_perform(curl);
78
79    /* extract the normal headers from the first request */
80    while((h = curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) {
81      printf("%s: %s\n", h->name, h->value);
82      prev = h;
83    }
84
85    /* extract the normal headers + 1xx + trailers from the last request */
86    unsigned int origin = CURLH_HEADER| CURLH_1XX | CURLH_TRAILER;
87    while((h = curl_easy_nextheader(curl, origin, -1, prev))) {
88      printf("%s: %s\n", h->name, h->value);
89      prev = h;
90    }
91  }
92}
93~~~
94
95# %AVAILABILITY%
96
97# RETURN VALUE
98
99This function returns the next header, or NULL when there are no more
100(matching) headers or an error occurred.
101
102If this function returns NULL when *prev* was set to NULL, then there are no
103headers available within the scope to return.
104