aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl
diff options
context:
space:
mode:
authorDaniel Stenberg <daniel@haxx.se>2014-02-04 23:37:29 +0100
committerDaniel Stenberg <daniel@haxx.se>2014-04-04 17:03:43 +0200
commitef6be35bae1fe501fecd9a2a21eb5d03ddff4243 (patch)
treebb92bc620a0d852ed0084c353780763ee3fa73a2 /docs/libcurl
parentac887eedbc17a0d78b11ff467858c76a5127d1f4 (diff)
CURLOPT_HEADEROPT: added
Modified the logic so that CURLOPT_HEADEROPT now controls if PROXYHEADER is actually used or not.
Diffstat (limited to 'docs/libcurl')
-rw-r--r--docs/libcurl/curl_easy_setopt.360
-rw-r--r--docs/libcurl/symbols-in-versions1
2 files changed, 37 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.
diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions
index 925e47923..ecd38b52b 100644
--- a/docs/libcurl/symbols-in-versions
+++ b/docs/libcurl/symbols-in-versions
@@ -370,6 +370,7 @@ CURLOPT_GSSAPI_DELEGATION 7.22.0
CURLOPT_HEADER 7.1
CURLOPT_HEADERDATA 7.10
CURLOPT_HEADERFUNCTION 7.7.2
+CURLOPT_HEADEROPT 7.36.0
CURLOPT_HTTP200ALIASES 7.10.3
CURLOPT_HTTPAUTH 7.10.6
CURLOPT_HTTPGET 7.8.1