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