mirror of
https://github.com/curl/curl.git
synced 2026-08-25 19:43:33 +03:00
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
This commit is contained in:
Max Dymond
Daniel Stenberg
parent
06981ba7f6
commit
a517378de5
21 changed files with 602 additions and 4 deletions
|
|
@ -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
|
||||
|
|
|
|||
61
docs/libcurl/opts/CURLOPT_PREREQDATA.3
Normal file
61
docs/libcurl/opts/CURLOPT_PREREQDATA.3
Normal file
|
|
@ -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) "
|
||||
104
docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3
Normal file
104
docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3
Normal file
|
|
@ -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) "
|
||||
|
|
@ -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 \
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue