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