CURLOPT_PREREQFUNCTION: add new callback

Triggered before a request is made but after a connection is set up

Changes:

- callback: Update docs and callback for pre-request callback
- Add documentation for CURLOPT_PREREQDATA and CURLOPT_PREREQFUNCTION,
- Add redirect test and callback failure test
- Note that the function may be called multiple times on a redirection
- Disable new 2086 test due to Windows weirdness

Closes #7477

5 files changed, 175 insertions, 0 deletions

diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index 592692b94..b1abf43e3 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -144,6 +144,10 @@ Suppress proxy CONNECT response headers from user callbacks. See \fICURLOPT_SUPP
 Callback to be called before a new resolve request is started. See \fICURLOPT_RESOLVER_START_FUNCTION(3)\fP
 .IP CURLOPT_RESOLVER_START_DATA
 Data pointer to pass to resolver start callback. See \fICURLOPT_RESOLVER_START_DATA(3)\fP
+.IP CURLOPT_PREREQFUNCTION
+Callback to be called after a connection is established but before a request is made on that connection. See \fICURLOPT_PREREQFUNCTION(3)\fP
+.IP CURLOPT_PREREQDATA
+Data pointer to pass to the CURLOPT_PREREQFUNCTION callback. See \fICURLOPT_PREREQDATA(3)\fP
 .SH ERROR OPTIONS
 .IP CURLOPT_ERRORBUFFER
 Error message buffer. See \fICURLOPT_ERRORBUFFER(3)\fP
diff --git a/docs/libcurl/opts/CURLOPT_PREREQDATA.3 b/docs/libcurl/opts/CURLOPT_PREREQDATA.3
new file mode 100644
index 000000000..07497a83b
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_PREREQDATA.3
@@ -0,0 +1,61 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 2021, Max Dymond, <max.dymond@microsoft.com>, 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.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_PREREQDATA 3 "2 Aug 2021" "libcurl 7.80.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_PREREQDATA \- custom pointer passed to the pre-request callback
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, void *pointer);
+.SH DESCRIPTION
+Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first
+argument in the pre-request callback set with
+\fICURLOPT_PREREQFUNCTION(3)\fP.
+.SH DEFAULT
+NULL
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+static int prereq_callback(void *clientp,
+                           char *conn_primary_ip,
+                           char *conn_local_ip,
+                           int conn_primary_port,
+                           int conn_local_port)
+{
+  printf("Connection made to %s:%s\n", conn_primary_ip, conn_primary_port);
+  return CURL_PREREQFUNC_OK;
+}
+
+{
+  struct data prereq_data;
+  curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback);
+  curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, &prereq_data);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.80.0
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLOPT_PREREQFUNCTION "(3) "
diff --git a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3
new file mode 100644
index 000000000..dcc782f9d
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3
@@ -0,0 +1,104 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 2021, Max Dymond, <max.dymond@microsoft.com>, 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.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_PREREQFUNCTION 3 "2 Aug 2021" "libcurl 7.80.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_PREREQFUNCTION \- user callback called when a connection has been
+established, but before a request has been made.
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+/* These are the return codes for the pre-request callback. */
+#define CURL_PREREQFUNC_OK 0
+#define CURL_PREREQFUNC_ABORT 1 /* fail the entire transfer */
+
+int prereq_callback(void *clientp,
+                    char *conn_primary_ip,
+                    char *conn_local_ip,
+                    int conn_primary_port,
+                    int conn_local_port);
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback);
+.SH DESCRIPTION
+Pass a pointer to your callback function, which should match the prototype
+shown above.
+
+This function gets called by libcurl after a connection has been established
+or a connection has been reused (including any SSL handshaking), but before any
+request is actually made on the connection. For example, for HTTP, this
+callback is called once a connection has been established to the server, but
+before a GET/HEAD/POST/etc request has been sent.
+
+This function may be called multiple times if redirections are enabled and are
+being followed (see \fICURLOPT_FOLLOWLOCATION(3)\fP).
+
+This function is passed the following information:
+.IP conn_primary_ip
+A nul-terminated pointer to a C string containing the primary IP of the remote
+server established with this connection. For FTP, this is the IP for the control
+connection. IPv6 addresses are represented without surrounding brackets.
+.IP conn_local_ip
+A nul-terminated pointer to a C string containing the originating IP for this
+connection. IPv6 addresses are represented without surrounding brackets.
+.IP conn_primary_port
+The primary port number on the remote server established with this connection.
+For FTP, this is the port for the control connection. This can be a TCP or a
+UDP port number dependending on the protocol.
+.IP conn_local_port
+The originating port number for this connection. This can be a TCP or a UDP port
+number dependending on the protocol.
+.RE
+
+\fIclientp\fP is the pointer you set with \fICURLOPT_PREREQDATA(3)\fP.
+
+The callback function must return \fICURL_PREREQFUNC_OK\fP on success, or
+\fICURL_PREREQFUNC_ABORT\fP to cause the transfer to fail.
+
+.SH DEFAULT
+By default, this is NULL and unused.
+.SH PROTOCOLS
+ALL
+.SH EXAMPLE
+.nf
+static int prereq_callback(void *clientp,
+                           char *conn_primary_ip,
+                           char *conn_local_ip,
+                           int conn_primary_port,
+                           int conn_local_port)
+{
+  printf("Connection made to %s:%s\n", conn_primary_ip, conn_primary_port);
+  return CURL_PREREQFUNC_OK;
+}
+
+{
+  struct data prereq_data;
+  curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback);
+  curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, &prereq_data);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.80.0
+.SH RETURN VALUE
+Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
+.SH "SEE ALSO"
+.BR CURLOPT_PREREQDATA "(3) "
diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc
index 4ef5ddf43..7bac21024 100644
--- a/docs/libcurl/opts/Makefile.inc
+++ b/docs/libcurl/opts/Makefile.inc
@@ -254,6 +254,8 @@ man_MANS =                                      \
   CURLOPT_POSTQUOTE.3                           \
   CURLOPT_POSTREDIR.3                           \
   CURLOPT_PREQUOTE.3                            \
+  CURLOPT_PREREQDATA.3                          \
+  CURLOPT_PREREQFUNCTION.3                      \
   CURLOPT_PRE_PROXY.3                           \
   CURLOPT_PRIVATE.3                             \
   CURLOPT_PROGRESSDATA.3                        \
diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions
index 8be22d504..1dbcdbd3e 100644
--- a/docs/libcurl/symbols-in-versions
+++ b/docs/libcurl/symbols-in-versions
@@ -531,6 +531,8 @@ CURLOPT_POSTFIELDSIZE_LARGE     7.11.1
 CURLOPT_POSTQUOTE               7.1
 CURLOPT_POSTREDIR               7.19.1
 CURLOPT_PREQUOTE                7.9.5
+CURLOPT_PREREQDATA              7.80.0
+CURLOPT_PREREQFUNCTION          7.80.0
 CURLOPT_PRE_PROXY               7.52.0
 CURLOPT_PRIVATE                 7.10.3
 CURLOPT_PROGRESSDATA            7.1
@@ -964,6 +966,8 @@ CURL_POLL_INOUT                 7.14.0
 CURL_POLL_NONE                  7.14.0
 CURL_POLL_OUT                   7.14.0
 CURL_POLL_REMOVE                7.14.0
+CURL_PREREQFUNC_ABORT           7.79.0
+CURL_PREREQFUNC_OK              7.79.0
 CURL_PROGRESSFUNC_CONTINUE      7.68.0
 CURL_PROGRESS_BAR               7.1.1         -           7.4.1
 CURL_PROGRESS_STATS             7.1.1         -           7.4.1