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