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