• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_SOCKOPTFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_OPENSOCKETFUNCTION (3)
9  - CURLOPT_SEEKFUNCTION (3)
10  - CURLOPT_SOCKOPTDATA (3)
11---
12
13# NAME
14
15CURLOPT_SOCKOPTFUNCTION - callback for setting socket options
16
17# SYNOPSIS
18
19~~~c
20#include <curl/curl.h>
21
22typedef enum  {
23  CURLSOCKTYPE_IPCXN,  /* socket created for a specific IP connection */
24  CURLSOCKTYPE_ACCEPT, /* socket created by accept() call */
25  CURLSOCKTYPE_LAST    /* never use */
26} curlsocktype;
27
28#define CURL_SOCKOPT_OK 0
29#define CURL_SOCKOPT_ERROR 1 /* causes libcurl to abort and return
30                                CURLE_ABORTED_BY_CALLBACK */
31#define CURL_SOCKOPT_ALREADY_CONNECTED 2
32
33int sockopt_callback(void *clientp,
34                     curl_socket_t curlfd,
35                     curlsocktype purpose);
36
37CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
38~~~
39
40# DESCRIPTION
41
42Pass a pointer to your callback function, which should match the prototype
43shown above.
44
45When set, this callback function gets called by libcurl when the socket has
46been created, but before the connect call to allow applications to change
47specific socket options. The callback's *purpose* argument identifies the
48exact purpose for this particular socket:
49
50*CURLSOCKTYPE_IPCXN* for actively created connections or since 7.28.0
51*CURLSOCKTYPE_ACCEPT* for FTP when the connection was setup with PORT/EPSV
52(in earlier versions these sockets were not passed to this callback).
53
54Future versions of libcurl may support more purposes. libcurl passes the newly
55created socket descriptor to the callback in the *curlfd* parameter so
56additional setsockopt() calls can be done at the user's discretion.
57
58The *clientp* pointer contains whatever user-defined value set using the
59CURLOPT_SOCKOPTDATA(3) function.
60
61Return *CURL_SOCKOPT_OK* from the callback on success. Return
62*CURL_SOCKOPT_ERROR* from the callback function to signal an unrecoverable
63error to the library and it closes the socket and returns
64*CURLE_COULDNT_CONNECT*. Alternatively, the callback function can return
65*CURL_SOCKOPT_ALREADY_CONNECTED*, to tell libcurl that the socket is
66already connected and then libcurl does no attempt to connect. This allows an
67application to pass in an already connected socket with
68CURLOPT_OPENSOCKETFUNCTION(3) and then have this function make libcurl
69not attempt to connect (again).
70
71# DEFAULT
72
73By default, this callback is NULL and unused.
74
75# PROTOCOLS
76
77All
78
79# EXAMPLE
80
81~~~c
82/* make libcurl use the already established socket 'sockfd' */
83
84static curl_socket_t opensocket(void *clientp,
85                                curlsocktype purpose,
86                                struct curl_sockaddr *address)
87{
88  curl_socket_t sockfd;
89  sockfd = *(curl_socket_t *)clientp;
90  /* the actual externally set socket is passed in via the OPENSOCKETDATA
91     option */
92  return sockfd;
93}
94
95static int sockopt_callback(void *clientp, curl_socket_t curlfd,
96                            curlsocktype purpose)
97{
98  /* This return code was added in libcurl 7.21.5 */
99  return CURL_SOCKOPT_ALREADY_CONNECTED;
100}
101
102int main(void)
103{
104  CURL *curl = curl_easy_init();
105  if(curl) {
106    CURLcode res;
107    int sockfd; /* our custom file descriptor */
108    /* libcurl thinks that you connect to the host
109     * and port that you specify in the URL option. */
110    curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
111    /* call this function to get a socket */
112    curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
113    curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
114
115    /* call this function to set options for the socket */
116    curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
117
118    res = curl_easy_perform(curl);
119
120    curl_easy_cleanup(curl);
121  }
122}
123~~~
124
125# AVAILABILITY
126
127Added in 7.16.0. The *CURL_SOCKOPT_ALREADY_CONNECTED* return code was
128added in 7.21.5.
129
130# RETURN VALUE
131
132Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
133