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