Return to CURLOPT_HEADERFUNCTION.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts

Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3, revision 1.1.1.1

1.1       misho       1: .\" **************************************************************************
                      2: .\" *                                  _   _ ____  _
                      3: .\" *  Project                     ___| | | |  _ \| |
                      4: .\" *                             / __| | | | |_) | |
                      5: .\" *                            | (__| |_| |  _ <| |___
                      6: .\" *                             \___|\___/|_| \_\_____|
                      7: .\" *
                      8: .\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al.
                      9: .\" *
                     10: .\" * This software is licensed as described in the file COPYING, which
                     11: .\" * you should have received as part of this distribution. The terms
                     12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
                     13: .\" *
                     14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
                     15: .\" * copies of the Software, and permit persons to whom the Software is
                     16: .\" * furnished to do so, under the terms of the COPYING file.
                     17: .\" *
                     18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
                     19: .\" * KIND, either express or implied.
                     20: .\" *
                     21: .\" **************************************************************************
                     22: .\"
                     23: .TH CURLOPT_HEADERFUNCTION 3 "December 26, 2019" "libcurl 7.70.0" "curl_easy_setopt options"
                     24: 
                     25: .SH NAME
                     26: CURLOPT_HEADERFUNCTION \- callback that receives header data
                     27: .SH SYNOPSIS
                     28: #include <curl/curl.h>
                     29: 
                     30: size_t header_callback(char *buffer,
                     31:                        size_t size,
                     32:                        size_t nitems,
                     33:                        void *userdata);
                     34: 
                     35: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION, header_callback);
                     36: .SH DESCRIPTION
                     37: Pass a pointer to your callback function, which should match the prototype
                     38: shown above.
                     39: 
                     40: This function gets called by libcurl as soon as it has received header
                     41: data. The header callback will be called once for each header and only
                     42: complete header lines are passed on to the callback. Parsing headers is very
                     43: easy using this. \fIbuffer\fP points to the delivered data, and the size of
                     44: that data is \fInitems\fP; \fIsize\fP is always 1. Do not assume that the
                     45: header line is zero terminated!
                     46: 
                     47: The pointer named \fIuserdata\fP is the one you set with the
                     48: \fICURLOPT_HEADERDATA(3)\fP option.
                     49: 
                     50: This callback function must return the number of bytes actually taken care of.
                     51: If that amount differs from the amount passed in to your function, it'll signal
                     52: an error to the library. This will cause the transfer to get aborted and the
                     53: libcurl function in progress will return \fICURLE_WRITE_ERROR\fP.
                     54: 
                     55: A complete HTTP header that is passed to this function can be up to
                     56: \fICURL_MAX_HTTP_HEADER\fP (100K) bytes and includes the final line terminator.
                     57: 
                     58: If this option is not set, or if it is set to NULL, but
                     59: \fICURLOPT_HEADERDATA(3)\fP is set to anything but NULL, the function used to
                     60: accept response data will be used instead. That is, it will be the function
                     61: specified with \fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or
                     62: NULL - the default, stream-writing function.
                     63: 
                     64: It's important to note that the callback will be invoked for the headers of
                     65: all responses received after initiating a request and not just the final
                     66: response. This includes all responses which occur during authentication
                     67: negotiation. If you need to operate on only the headers from the final
                     68: response, you will need to collect headers in the callback yourself and use
                     69: HTTP status lines, for example, to delimit response boundaries.
                     70: 
                     71: For an HTTP transfer, the status line and the blank line preceding the response
                     72: body are both included as headers and passed to this function.
                     73: 
                     74: When a server sends a chunked encoded transfer, it may contain a trailer. That
                     75: trailer is identical to an HTTP header and if such a trailer is received it is
                     76: passed to the application using this callback as well. There are several ways
                     77: to detect it being a trailer and not an ordinary header: 1) it comes after the
                     78: response-body. 2) it comes after the final header line (CR LF) 3) a Trailer:
                     79: header among the regular response-headers mention what header(s) to expect in
                     80: the trailer.
                     81: 
                     82: For non-HTTP protocols like FTP, POP3, IMAP and SMTP this function will get
                     83: called with the server responses to the commands that libcurl sends.
                     84: .SH LIMITATIONS
                     85: libcurl does not unfold HTTP "folded headers" (deprecated since RFC 7230). A
                     86: folded header is a header that continues on a subsequent line and starts with
                     87: a whitespace. Such folds will be passed to the header callback as a separate
                     88: one, although strictly it is just a continuation of the previous line.
                     89: .SH DEFAULT
                     90: Nothing.
                     91: .SH PROTOCOLS
                     92: Used for all protocols with headers or meta-data concept: HTTP, FTP, POP3,
                     93: IMAP, SMTP and more.
                     94: .SH EXAMPLE
                     95: .nf
                     96: static size_t header_callback(char *buffer, size_t size,
                     97:                               size_t nitems, void *userdata)
                     98: {
                     99:   /* received header is nitems * size long in 'buffer' NOT ZERO TERMINATED */
                    100:   /* 'userdata' is set with CURLOPT_HEADERDATA */
                    101:   return nitems * size;
                    102: }
                    103: 
                    104: CURL *curl = curl_easy_init();
                    105: if(curl) {
                    106:   curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
                    107: 
                    108:   curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback);
                    109: 
                    110:   curl_easy_perform(curl);
                    111: }
                    112: .fi
                    113: .SH AVAILABILITY
                    114: Always
                    115: .SH RETURN VALUE
                    116: Returns CURLE_OK
                    117: .SH "SEE ALSO"
                    118: .BR CURLOPT_HEADERDATA "(3), " CURLOPT_WRITEFUNCTION "(3), "