1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_PREREQFUNCTION 5Section: 3 6Source: libcurl 7See-also: 8 - CURLINFO_PRIMARY_IP (3) 9 - CURLINFO_PRIMARY_PORT (3) 10 - CURLOPT_PREREQDATA (3) 11Protocol: 12 - All 13--- 14 15# NAME 16 17CURLOPT_PREREQFUNCTION - user callback called when a connection has been 18established, but before a request has been made. 19 20# SYNOPSIS 21 22~~~c 23#include <curl/curl.h> 24 25/* These are the return codes for the pre-request callback. */ 26#define CURL_PREREQFUNC_OK 0 27#define CURL_PREREQFUNC_ABORT 1 /* fail the entire transfer */ 28 29int prereq_callback(void *clientp, 30 char *conn_primary_ip, 31 char *conn_local_ip, 32 int conn_primary_port, 33 int conn_local_port); 34 35CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback); 36~~~ 37 38# DESCRIPTION 39 40Pass a pointer to your callback function, which should match the prototype 41shown above. 42 43This function gets called by libcurl after a connection has been established 44or a connection has been reused (including any SSL handshaking), but before any 45request is actually made on the connection. For example, for HTTP, this 46callback is called once a connection has been established to the server, but 47before a GET/HEAD/POST/etc request has been sent. 48 49This function may be called multiple times if redirections are enabled and are 50being followed (see CURLOPT_FOLLOWLOCATION(3)). 51 52The callback function must return *CURL_PREREQFUNC_OK* on success, or 53*CURL_PREREQFUNC_ABORT* to cause the transfer to fail. 54 55This function is passed the following arguments: 56 57## `conn_primary_ip` 58 59A null-terminated pointer to a C string containing the primary IP of the 60remote server established with this connection. For FTP, this is the IP for 61the control connection. IPv6 addresses are represented without surrounding 62brackets. 63 64## `conn_local_ip` 65 66A null-terminated pointer to a C string containing the originating IP for this 67connection. IPv6 addresses are represented without surrounding brackets. 68 69## `conn_primary_port` 70 71The primary port number on the remote server established with this connection. 72For FTP, this is the port for the control connection. This can be a TCP or a 73UDP port number depending on the protocol. 74 75## `conn_local_port` 76 77The originating port number for this connection. This can be a TCP or a UDP 78port number depending on the protocol. 79 80## `clientp` 81 82The pointer you set with CURLOPT_PREREQDATA(3). 83 84# DEFAULT 85 86By default, this is NULL and unused. 87 88# EXAMPLE 89 90~~~c 91struct priv { 92 void *custom; 93}; 94 95static int prereq_callback(void *clientp, 96 char *conn_primary_ip, 97 char *conn_local_ip, 98 int conn_primary_port, 99 int conn_local_port) 100{ 101 printf("Connection made to %s:%d\n", conn_primary_ip, conn_primary_port); 102 return CURL_PREREQFUNC_OK; 103} 104 105int main(void) 106{ 107 struct priv prereq_data; 108 CURL *curl = curl_easy_init(); 109 if(curl) { 110 curl_easy_setopt(curl, CURLOPT_PREREQFUNCTION, prereq_callback); 111 curl_easy_setopt(curl, CURLOPT_PREREQDATA, &prereq_data); 112 curl_easy_perform(curl); 113 } 114} 115~~~ 116 117# AVAILABILITY 118 119Added in 7.80.0 120 121# RETURN VALUE 122 123Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. 124