url: Add option CURLOPT_RESOLVER_START_FUNCTION

- Add new option CURLOPT_RESOLVER_START_FUNCTION to set a callback that
  will be called every time before a new resolve request is started
  (ie before a host is resolved) with a pointer to backend-specific
  resolver data. Currently this is only useful for ares.

- Add new option CURLOPT_RESOLVER_START_DATA to set a user pointer to
  pass to the resolver start callback.

Closes https://github.com/curl/curl/pull/2311

3 files changed, 148 insertions, 0 deletions

diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3
new file mode 100644
index 000000000..4d8f8793e
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3
@@ -0,0 +1,63 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2018, 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_RESOLVER_START_DATA 3 "14 Feb 2018" "libcurl 7.59.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_RESOLVER_START_DATA \- custom pointer passed to the resolver start callback
+.SH SYNOPSIS
+#include <curl/curl.h>
+
+CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVER_START_DATA, void *pointer);
+.SH DESCRIPTION
+Pass a \fIpointer\fP that will be untouched by libcurl and passed as the third
+argument in the resolver start callback set with
+\fICURLOPT_RESOLVER_START_FUNCTION(3)\fP.
+.SH DEFAULT
+NULL
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+static int resolver_start_cb(void *resolver_state, void *reserved,
+                             void *userdata)
+{
+  (void)reserved;
+  printf("Received resolver_state=%p userdata=%p\\n",
+         resolver_state, userdata);
+  return 0;
+}
+
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, resolver_start_cb);
+  curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl);
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+  curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.59.0
+.SH RETURN VALUE
+Returns CURLE_OK
+.SH "SEE ALSO"
+.BR CURLOPT_RESOLVER_START_FUNCTION "(3) "
diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3
new file mode 100644
index 000000000..fd11910ce
--- /dev/null
+++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3
@@ -0,0 +1,83 @@
+.\" **************************************************************************
+.\" *                                  _   _ ____  _
+.\" *  Project                     ___| | | |  _ \| |
+.\" *                             / __| | | | |_) | |
+.\" *                            | (__| |_| |  _ <| |___
+.\" *                             \___|\___/|_| \_\_____|
+.\" *
+.\" * Copyright (C) 1998 - 2018, 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_RESOLVER_START_FUNCTION 3 "14 Feb 2018" "libcurl 7.59.0" "curl_easy_setopt options"
+.SH NAME
+CURLOPT_RESOLVER_START_FUNCTION \- set callback to be called before a new resolve request is started
+.SH SYNOPSIS
+.nf
+#include <curl/curl.h>
+
+int resolver_start_cb(void *resolver_state, void *reserved, void *userdata);
+
+CURLcode curl_easy_setopt(CURL *handle,
+                          CURLOPT_RESOLVER_START_FUNCTION,
+                          resolver_start_cb);
+.SH DESCRIPTION
+Pass a pointer to your callback function, which should match the prototype
+shown above.
+
+This callback function gets called by libcurl every time before a new resolve
+request is started.
+
+\fIresolver_state\fP points to a backend-specific resolver state. Currently
+only the ares resolver backend has a resolver state. It can be used to set up
+any desired option on the ares channel before it's used, for example setting up
+socket callback options.
+
+\fIreserved\fP is reserved.
+
+\fIuserdata\fP is the user pointer set with the
+\fICURLOPT_RESOLVER_START_DATA(3)\fP option.
+
+The callback must return 0 on success. Returning a non-zero value will cause
+the resolve to fail.
+.SH DEFAULT
+NULL (No callback)
+.SH PROTOCOLS
+All
+.SH EXAMPLE
+.nf
+static int resolver_start_cb(void *resolver_state, void *reserved,
+                             void *userdata)
+{
+  (void)reserved;
+  printf("Received resolver_state=%p userdata=%p\\n",
+         resolver_state, userdata);
+  return 0;
+}
+
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, resolver_start_cb);
+  curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl);
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+  curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
+.SH AVAILABILITY
+Added in 7.59.0
+.SH RETURN VALUE
+Returns CURLE_OK
+.SH "SEE ALSO"
+.BR CURLOPT_RESOLVER_START_DATA "(3) "
diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc
index 0cebc46d4..2aa1acf33 100644
--- a/docs/libcurl/opts/Makefile.inc
+++ b/docs/libcurl/opts/Makefile.inc
@@ -242,6 +242,8 @@ man_MANS =                                      \
   CURLOPT_REFERER.3                             \
   CURLOPT_REQUEST_TARGET.3                      \
   CURLOPT_RESOLVE.3                             \
+  CURLOPT_RESOLVER_START_DATA.3                 \
+  CURLOPT_RESOLVER_START_FUNCTION.3             \
   CURLOPT_RESUME_FROM.3                         \
   CURLOPT_RESUME_FROM_LARGE.3                   \
   CURLOPT_RTSP_CLIENT_CSEQ.3                    \