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