aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl/opts
diff options
context:
space:
mode:
authorDesmond O. Chang <dochang@gmail.com>2016-04-28 17:33:25 +0800
committerJay Satiro <raysatiro@yahoo.com>2017-03-12 01:32:33 -0500
commitd2bcf1e3e247d116dc96bd3ea32056e3f089449c (patch)
treeda6eb7bec914ef3a31883aa0ddb30ce33c5dde5e /docs/libcurl/opts
parentec1d0ed1c14d1b2ed06d8914c19b3df2da575005 (diff)
url: add option CURLOPT_SUPPRESS_CONNECT_HEADERS
- Add new option CURLOPT_SUPPRESS_CONNECT_HEADERS to allow suppressing proxy CONNECT response headers from the user callback functions CURLOPT_HEADERFUNCTION and CURLOPT_WRITEFUNCTION. - Add new tool option --suppress-connect-headers to expose CURLOPT_SUPPRESS_CONNECT_HEADERS and allow suppressing proxy CONNECT response headers from --dump-header and --include. Assisted-by: Jay Satiro Assisted-by: CarloCannas@users.noreply.github.com Closes https://github.com/curl/curl/pull/783
Diffstat (limited to 'docs/libcurl/opts')
-rw-r--r--docs/libcurl/opts/CURLINFO_HEADER_SIZE.33
-rw-r--r--docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.33
-rw-r--r--docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.395
-rw-r--r--docs/libcurl/opts/Makefile.am1
4 files changed, 102 insertions, 0 deletions
diff --git a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3
index b4b9b578f..b687c80b9 100644
--- a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3
+++ b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3
@@ -30,6 +30,9 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_HEADER_SIZE, long *sizep);
.SH DESCRIPTION
Pass a pointer to a long to receive the total size of all the headers
received. Measured in number of bytes.
+
+The total includes the size of any received headers suppressed by
+\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP.
.SH PROTOCOLS
All
.SH EXAMPLE
diff --git a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3
index 6b48a0527..bdd04dfff 100644
--- a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3
+++ b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3
@@ -40,6 +40,9 @@ it allows CONNECT requests to and often only port 80 and 443 are allowed.
When using this, it only makes sense to use \fICURLOPT_PROXYTYPE(3)\fP set to
a HTTP proxy.
+
+To suppress proxy CONNECT response headers from user callbacks use
+\fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP.
.SH DEFAULT
0
.SH PROTOCOLS
diff --git a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3
new file mode 100644
index 000000000..8cfec7a8f
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3
@@ -0,0 +1,95 @@
+.\" **************************************************************************
+.\" * _ _ ____ _
+.\" * Project ___| | | | _ \| |
+.\" * / __| | | | |_) | |
+.\" * | (__| |_| | _ <| |___
+.\" * \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2017, 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 CURLOPT_SUPPRESS_CONNECT_HEADERS 3 "13 February 2017" "libcurl 7.54.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_SUPPRESS_CONNECT_HEADERS \- Suppress proxy CONNECT response headers from user callbacks
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SUPPRESS_CONNECT_HEADERS, long onoff);
+.fi
+.SH DESCRIPTION
+When \fICURLOPT_HTTPPROXYTUNNEL(3)\fP is used and a CONNECT request is made,
+suppress proxy CONNECT response headers from the user callback functions
+\fICURLOPT_HEADERFUNCTION(3)\fP and \fICURLOPT_WRITEFUNCTION(3)\fP.
+
+Proxy CONNECT response headers can complicate header processing since it's
+essentially a separate set of headers. You can enable this option to suppress
+those headers.
+
+For example let's assume an HTTPS URL is to be retrieved via CONNECT. On
+success there would normally be two sets of headers, and each header line sent
+to the header function and/or the write function. The data given to the
+callbacks would look like this:
+
+.nf
+HTTP/1.1 200 Connection established
+{headers}...
+
+HTTP/1.1 200 OK
+Content-Type: application/json
+{headers}...
+
+{body}...
+.fi
+
+However by enabling this option the CONNECT response headers are suppressed, so
+the data given to the callbacks would look like this:
+
+.nf
+HTTP/1.1 200 OK
+Content-Type: application/json
+{headers}...
+
+{body}...
+.fi
+
+.SH DEFAULT
+0
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
+
+ curl_easy_setopt(curl, CURLOPT_HEADER, 1L);
+ curl_easy_setopt(curl, CURLOPT_PROXY, "http://foo:3128");
+ curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L);
+ curl_easy_setopt(curl, CURLOPT_SUPPRESS_CONNECT_HEADERS, 1L);
+
+ curl_easy_perform(curl);
+
+ /* always cleanup */
+ curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.54.0
+.SH RETURN VALUE
+CURLE_OK or an error such as CURLE_UNKNOWN_OPTION.
+.SH "SEE ALSO"
+.BR CURLOPT_HEADER "(3), " CURLOPT_PROXY "(3), "
+.BR CURLOPT_HTTPPROXYTUNNEL "(3), "
diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am
index 5829a144f..26bb2eeb9 100644
--- a/docs/libcurl/opts/Makefile.am
+++ b/docs/libcurl/opts/Makefile.am
@@ -300,6 +300,7 @@ man_MANS = \
CURLOPT_STREAM_DEPENDS.3 \
CURLOPT_STREAM_DEPENDS_E.3 \
CURLOPT_STREAM_WEIGHT.3 \
+ CURLOPT_SUPPRESS_CONNECT_HEADERS.3 \
CURLOPT_TCP_FASTOPEN.3 \
CURLOPT_TCP_KEEPALIVE.3 \
CURLOPT_TCP_KEEPIDLE.3 \