Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
CURLOPT_HEADERFUNCTION(3)  curl_easy_setopt options  CURLOPT_HEADERFUNCTION(3)

NAME
       CURLOPT_HEADERFUNCTION -	callback that receives header data

SYNOPSIS
       #include	<curl/curl.h>

       size_t header_callback(char *buffer,
			      size_t size,
			      size_t nitems,
			      void *userdata);

       CURLcode	   curl_easy_setopt(CURL    *handle,   CURLOPT_HEADERFUNCTION,
       header_callback);

DESCRIPTION
       Pass a pointer to your callback function, which should match the	proto-
       type shown above.

       This  function gets called by libcurl as	soon as	it has received	header
       data. The header	callback will be called	once for each header and  only
       complete	header lines are passed	on to the callback. Parsing headers is
       very easy using this. The size of the data pointed to by	buffer is size
       multiplied  with	nmemb. Do not assume that the header line is zero ter-
       minated!	The pointer named userdata is the one you set  with  the  CUR-
       LOPT_HEADERDATA(3)  option. This	callback function must return the num-
       ber of bytes actually taken care	of. If that amount  differs  from  the
       amount  passed  in  to  your function, it'll signal an error to the li-
       brary. This will	cause the transfer to  get  aborted  and  the  libcurl
       function	in progress will return	CURLE_WRITE_ERROR.

       A  complete  HTTP  header  that is passed to this function can be up to
       CURL_MAX_HTTP_HEADER (100K) bytes.

       If this option is not set, or if	it is set to NULL, but CURLOPT_HEADER-
       DATA(3)	is  set	 to anything but NULL, the function used to accept re-
       sponse data will	be used	instead. That is,  it  will  be	 the  function
       specified  with	CURLOPT_WRITEFUNCTION(3), or if	it is not specified or
       NULL - the default, stream-writing function.

       It's important to note that the callback	will be	invoked	for the	 head-
       ers  of	all responses received after initiating	a request and not just
       the final response. This	includes all responses which occur during  au-
       thentication  negotiation.  If  you need	to operate on only the headers
       from the	final response,	you will need to collect headers in the	 call-
       back  yourself  and  use	HTTP status lines, for example,	to delimit re-
       sponse boundaries.

       When a server sends a  chunked  encoded	transfer,  it  may  contain  a
       trailer.	 That  trailer	is  identical  to  a HTTP header and if	such a
       trailer is received it is passed	to the application using this callback
       as well.	There are several ways to detect it being a trailer and	not an
       ordinary	header:	1) it comes after the response-body. 2)	it comes after
       the  final  header  line	(CR LF)	3) a Trailer: header among the regular
       response-headers	mention	what header(s) to expect in the	trailer.

       For non-HTTP protocols like FTP,	POP3, IMAP and SMTP this function will
       get  called  with  the  server  responses  to the commands that libcurl
       sends.

DEFAULT
       Nothing.

PROTOCOLS
       Used for	all protocols with headers or meta-data	 concept:  HTTP,  FTP,
       POP3, IMAP, SMTP	and more.

EXAMPLE
       static size_t header_callback(char *buffer, size_t size,
				     size_t nitems, void *userdata)
       {
	 /* received header is nitems *	size long in 'buffer' NOT ZERO TERMINATED */
	 /* 'userdata' is set with CURLOPT_HEADERDATA */
	 return	nitems * size;
       }

       CURL *curl = curl_easy_init();
       if(curl)	{
	 curl_easy_setopt(curl,	CURLOPT_URL, "http://example.com");

	 curl_easy_setopt(curl,	CURLOPT_HEADERFUNCTION,	header_callback);

	 curl_easy_perform(curl);
       }

AVAILABILITY
       Always

RETURN VALUE
       Returns CURLE_OK

SEE ALSO
       CURLOPT_HEADERDATA(3), CURLOPT_WRITEFUNCTION(3),

libcurl	5.5.5		       February	03, 2016     CURLOPT_HEADERFUNCTION(3)

NAME | SYNOPSIS | DESCRIPTION | DEFAULT | PROTOCOLS | EXAMPLE | AVAILABILITY | RETURN VALUE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=CURLOPT_HEADERFUNCTION&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help