quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

CURLOPT_SOCKOPTFUNCTION.md (4055B)

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