CURLOPT_HEADEROPT: added

Modified the logic so that CURLOPT_HEADEROPT now controls if PROXYHEADER
is actually used or not.

1 files changed, 36 insertions, 24 deletions

diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index bda293576..40c5a01c7 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -1515,17 +1515,20 @@ set the User-Agent: header in the http request sent to the remote server. This
 can be used to fool servers or scripts. You can also set any custom header
 with \fICURLOPT_HTTPHEADER\fP.
 .IP CURLOPT_HTTPHEADER
-Pass a pointer to a linked list of HTTP headers to pass to the server in your
-HTTP request. The linked list should be a fully valid list of \fBstruct
-curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to
-create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire
-list. If you add a header that is otherwise generated and used by libcurl
-internally, your added one will be used instead. If you add a header with no
-content as in 'Accept:' (no data on the right side of the colon), the
-internally used header will get disabled. Thus, using this option you can add
-new headers, replace internal headers and remove internal headers. To add a
-header with no content (nothing to the right side of the colon), use the
-form 'MyHeader;' (note the ending semicolon).
+Pass a pointer to a linked list of HTTP headers to pass to the server and/or
+proxy in your HTTP request. The same list is used for both host and proxy
+requests!
+
+The linked list should be a fully valid list of \fBstruct curl_slist\fP
+structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list
+and \fIcurl_slist_free_all(3)\fP to clean up an entire list. If you add a
+header that is otherwise generated and used by libcurl internally, your added
+one will be used instead. If you add a header with no content as in 'Accept:'
+(no data on the right side of the colon), the internally used header will get
+disabled. With this option you can add new headers, replace internal headers
+and remove internal headers. To add a header with no content (nothing to the
+right side of the colon), use the form 'MyHeader;' (note the ending
+semicolon).
 
 The headers included in the linked list must not be CRLF-terminated, because
 curl adds CRLF after each header item. Failure to comply with this will result
@@ -1542,26 +1545,35 @@ Pass a NULL to this to reset back to no custom headers.
 The most commonly replaced headers have "shortcuts" in the options
 \fICURLOPT_COOKIE\fP, \fICURLOPT_USERAGENT\fP and \fICURLOPT_REFERER\fP.
 
-Starting in 7.36.0, libcurl offers an alternative option that sets or replaces
-headers only for requests that are sent to a proxy:
-\fICURLOPT_PROXYHEADER\fP. If \fICURLOPT_PROXYHEADER\fP is not used at all by
-an application, the \fICURLOPT_HTTPHEADER headers\fP will be used for proxy
-requests as well!
+There's an alternative option that sets or replaces headers only for requests
+that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER\fP. Use
+\fICURLOPT_HEADEROPT\fP to control the behavior.
+.IP CURLOPT_HEADEROPT
+Pass a long that is a bitmask of options of how to deal with headers. The
+available options are:
+
+CURLHEADER_UNIFIED - keep working as before. This means CURLOPT_HTTPHEADER
+headers will be used in requests both to servers and in CONNECT requests. With
+this option enabled, \fICURLOPT_PROXYHEADER\fP will not have any effect.
+
+CURLHEADER_SEPARATE - makes \fICURLOPT_HTTPHEADER\fP headers only get sent to
+a host and not to a proxy if CONNECT is being used. It has to be set to make
+\fICURLOPT_PROXYHEADER\fP get used.
+
+This behavior is set per request and an application can alter it between
+different invokes if desired.
+
+(Added in 7.36.0)
 .IP CURLOPT_PROXYHEADER
 Pass a pointer to a linked list of HTTP headers to pass in your HTTP request
 sent to a proxy. The rules for this list is identical to the
 \fICURLOPT_HTTPHEADER\fP option's.
 
-The headers set with this option is only ever used in requests sent to a
-proxy.
-
-As a special quirk to stay backwards compatible with the libcurl versions
-released before this option existed, all headers set with
-\fICURLOPT_HTTPHEADER\fP will also be used for proxies unless you set one or
-more headers (or even just NULL) with \fICURLOPT_PROXYHEADER\fP.
+The headers set with this option is only ever used in requests sent to a proxy
+- when there's also a request sent to a host.
 
 The first line in a request (containing the method, usually a GET or POST) is
-not a header and cannot be replaced using this option. Only the lines
+NOT a header and cannot be replaced using this option. Only the lines
 following the request-line are headers. Adding this method line in this list
 of headers will only cause your request to send an invalid header.