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.
55
56This function is passed the following arguments:
57
58## `conn_primary_ip`
59
60A null-terminated pointer to a C string containing the primary IP of the
61remote server established with this connection. For FTP, this is the IP for
62the control connection. IPv6 addresses are represented without surrounding
63brackets.
64
65## `conn_local_ip`
66
67A null-terminated pointer to a C string containing the originating IP for this
68connection. IPv6 addresses are represented without surrounding brackets.
69
70## `conn_primary_port`
71
72The primary port number on the remote server established with this connection.
73For FTP, this is the port for the control connection. This can be a TCP or a
74UDP port number depending on the protocol.
75
76## `conn_local_port`
77
78The originating port number for this connection. This can be a TCP or a UDP
79port number depending on the protocol.
80
81## `clientp`
82
83The pointer you set with CURLOPT_PREREQDATA(3).
84
85# DEFAULT
86
87NULL
88
89# %PROTOCOLS%
90
91# EXAMPLE
92
93~~~c
94struct priv {
95  void *custom;
96};
97
98static int prereq_callback(void *clientp,
99                           char *conn_primary_ip,
100                           char *conn_local_ip,
101                           int conn_primary_port,
102                           int conn_local_port)
103{
104  printf("Connection made to %s:%d\n", conn_primary_ip, conn_primary_port);
105  return CURL_PREREQFUNC_OK;
106}
107
108int main(void)
109{
110  struct priv prereq_data;
111  CURL *curl = curl_easy_init();
112  if(curl) {
113    curl_easy_setopt(curl, CURLOPT_PREREQFUNCTION, prereq_callback);
114    curl_easy_setopt(curl, CURLOPT_PREREQDATA, &prereq_data);
115    curl_easy_perform(curl);
116  }
117}
118~~~
119
120# %AVAILABILITY%
121
122# RETURN VALUE
123
124Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
125