1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_OPENSOCKETFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_CLOSESOCKETFUNCTION (3)
9  - CURLOPT_OPENSOCKETFUNCTION (3)
10  - CURLOPT_SOCKOPTFUNCTION (3)
11Protocol:
12  - All
13---
14
15# NAME
16
17CURLOPT_OPENSOCKETFUNCTION - callback for opening socket
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24typedef enum  {
25  CURLSOCKTYPE_IPCXN,  /* socket created for a specific IP connection */
26} curlsocktype;
27
28struct curl_sockaddr {
29  int family;
30  int socktype;
31  int protocol;
32  unsigned int addrlen;
33  struct sockaddr addr;
34};
35
36curl_socket_t opensocket_callback(void *clientp,
37                                  curlsocktype purpose,
38                                  struct curl_sockaddr *address);
39
40CURLcode curl_easy_setopt(CURL *handle, CURLOPT_OPENSOCKETFUNCTION, opensocket_callback);
41~~~
42
43# DESCRIPTION
44
45Pass a pointer to your callback function, which should match the prototype
46shown above.
47
48This callback function gets called by libcurl instead of the *socket(2)*
49call. The callback's *purpose* argument identifies the exact purpose for
50this particular socket. *CURLSOCKTYPE_IPCXN* is for IP based connections
51and is the only purpose currently used in libcurl. Future versions of libcurl
52may support more purposes.
53
54The *clientp* pointer contains whatever user-defined value set using the
55CURLOPT_OPENSOCKETDATA(3) function.
56
57The callback gets the resolved peer address as the *address* argument and
58is allowed to modify the address or refuse to connect completely. The callback
59function should return the newly created socket or *CURL_SOCKET_BAD* in
60case no connection could be established or another error was detected. Any
61additional *setsockopt(2)* calls can of course be done on the socket at
62the user's discretion. A *CURL_SOCKET_BAD* return value from the callback
63function signals an unrecoverable error to libcurl and it returns
64*CURLE_COULDNT_CONNECT* from the function that triggered this callback.
65This return code can be used for IP address block listing.
66
67If you want to pass in a socket with an already established connection, pass
68the socket back with this callback and then use
69CURLOPT_SOCKOPTFUNCTION(3) to signal that it already is connected.
70
71# DEFAULT
72
73The default behavior is the equivalent of this:
74~~~c
75   return socket(addr->family, addr->socktype, addr->protocol);
76~~~
77
78# EXAMPLE
79
80~~~c
81/* make libcurl use the already established socket 'sockfd' */
82
83static curl_socket_t opensocket(void *clientp,
84                                curlsocktype purpose,
85                                struct curl_sockaddr *address)
86{
87  curl_socket_t sockfd;
88  sockfd = *(curl_socket_t *)clientp;
89  /* the actual externally set socket is passed in via the OPENSOCKETDATA
90     option */
91  return sockfd;
92}
93
94static int sockopt_callback(void *clientp, curl_socket_t curlfd,
95                            curlsocktype purpose)
96{
97  /* This return code was added in libcurl 7.21.5 */
98  return CURL_SOCKOPT_ALREADY_CONNECTED;
99}
100
101int main(void)
102{
103  CURL *curl = curl_easy_init();
104  if(curl) {
105    CURLcode res;
106    extern int sockfd; /* the already connected one */
107    /* libcurl thinks that you connect to the host
108     * and port that you specify in the URL option. */
109    curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
110    /* call this function to get a socket */
111    curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
112    curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
113
114    /* call this function to set options for the socket */
115    curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
116
117    res = curl_easy_perform(curl);
118
119    curl_easy_cleanup(curl);
120  }
121}
122~~~
123
124# AVAILABILITY
125
126Added in 7.17.1.
127
128# RETURN VALUE
129
130Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
131