Commit 23713645 authored by Francisco Sedano's avatar Francisco Sedano Committed by Jay Satiro
Browse files

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
parent dd027c80

docs/libcurl/curl_easy_setopt.3

+4 −0
Original line number Diff line number Diff line
@@ -139,6 +139,10 @@ Callback for wildcard matching. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP 
Data pointer to pass to the wildcard matching callback. See \fICURLOPT_FNMATCH_DATA(3)\fP

.IP CURLOPT_SUPPRESS_CONNECT_HEADERS

Suppress proxy CONNECT response headers from user callbacks. See \fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP

.IP CURLOPT_RESOLVER_START_FUNCTION

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

.SH ERROR OPTIONS

.IP CURLOPT_ERRORBUFFER

Error message buffer. See \fICURLOPT_ERRORBUFFER(3)\fP

docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3

0 → 100644
+63 −0
Original line number Diff line number Diff line 
.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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) "

docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3

0 → 100644
+83 −0
Original line number Diff line number Diff line 
.\" **************************************************************************

.\" *                                  _   _ ____  _

.\" *  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) "

docs/libcurl/opts/Makefile.inc

+2 −0
Original line number Diff line number Diff line
@@ -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                    \

docs/libcurl/symbols-in-versions

+2 −0
Original line number Diff line number Diff line
@@ -597,6 +597,8 @@ CURLOPT_TLSAUTH_TYPE 7.21.4 
CURLOPT_TLSAUTH_USERNAME        7.21.4

CURLOPT_TRANSFERTEXT            7.1.1

CURLOPT_TRANSFER_ENCODING       7.21.6

CURLOPT_RESOLVER_START_FUNCTION 7.59.0

CURLOPT_RESOLVER_START_DATA     7.59.0

CURLOPT_UNIX_SOCKET_PATH        7.40.0

CURLOPT_UNRESTRICTED_AUTH       7.10.4

CURLOPT_UPLOAD                  7.1