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