diff options
Diffstat (limited to 'docs/libcurl/opts/GNURLOPT_HEADERFUNCTION.3')
| -rw-r--r-- | docs/libcurl/opts/GNURLOPT_HEADERFUNCTION.3 | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/docs/libcurl/opts/GNURLOPT_HEADERFUNCTION.3 b/docs/libcurl/opts/GNURLOPT_HEADERFUNCTION.3 new file mode 100644 index 000000000..48bdbdaaf --- /dev/null +++ b/docs/libcurl/opts/GNURLOPT_HEADERFUNCTION.3 @@ -0,0 +1,114 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH GNURLOPT_HEADERFUNCTION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" +.SH NAME +CURLOPT_HEADERFUNCTION \- callback that receives header data +.SH SYNOPSIS +#include <gnurl/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); +.SH DESCRIPTION +Pass a pointer to your callback function, which should match the prototype +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 \fIbuffer\fP is \fIsize\fP +multiplied with \fInitems\fP. Do not assume that the header line is zero +terminated! + +The pointer named \fIuserdata\fP is the one you set with the +\fICURLOPT_HEADERDATA(3)\fP option. + +This callback function must return the number 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 library. This will cause the transfer to get aborted and the +libcurl function in progress will return \fICURLE_WRITE_ERROR\fP. + +A complete HTTP header that is passed to this function can be up to +\fICURL_MAX_HTTP_HEADER\fP (100K) bytes. + +If this option is not set, or if it is set to NULL, but +\fICURLOPT_HEADERDATA(3)\fP is set to anything but NULL, the function used to +accept response data will be used instead. That is, it will be the function +specified with \fICURLOPT_WRITEFUNCTION(3)\fP, 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 headers of +all responses received after initiating a request and not just the final +response. This includes all responses which occur during authentication +negotiation. If you need to operate on only the headers from the final +response, you will need to collect headers in the callback yourself and use +HTTP status lines, for example, to delimit response boundaries. + +When a server sends a chunked encoded transfer, it may contain a trailer. That +trailer is identical to an 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. +.SH LIMITATIONS +libcurl does not unfold HTTP "folded headers" (deprecated since RFC 7230). A +folded header is a header that continues on a subsequent line and starts with +a whitespace. Such folds will be passed to the header callback as a separate +one, although strictly it is just a continuation of the previous line. +.SH DEFAULT +Nothing. +.SH PROTOCOLS +Used for all protocols with headers or meta-data concept: HTTP, FTP, POP3, +IMAP, SMTP and more. +.SH EXAMPLE +.nf +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); +} +.fi +.SH AVAILABILITY +Always +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_HEADERDATA "(3), " CURLOPT_WRITEFUNCTION "(3), " |