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     ! 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), "