CURLOPT_SOCKOPTFUNCTION(3)

CURLOPT_SOCKOPTFUNCTION(3curl_easy_setopt optionCURLOPT_SOCKOPTFUNCTION(3)

NAME

     CURLOPT_SOCKOPTFUNCTION - set callback  for  setting  socket
     options

SYNOPSIS

     #include <curl/curl.h>

     typedef enum  {
       CURLSOCKTYPE_IPCXN,  /* socket created for a specific IP connection */
       CURLSOCKTYPE_ACCEPT, /* socket created by accept() call */
       CURLSOCKTYPE_LAST    /* never use */
     } curlsocktype;

     #define CURL_SOCKOPT_OK 0
     #define CURL_SOCKOPT_ERROR 1 /* causes libcurl to abort and return
                                     CURLE_ABORTED_BY_CALLBACK */
     #define CURL_SOCKOPT_ALREADY_CONNECTED 2

     int sockopt_callback(void *clientp,
                          curl_socket_t curlfd,
                          curlsocktype purpose);

     CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);

DESCRIPTION

     Pass a pointer to your callback function, which should match
     the prototype shown above.

     When set, this callback function gets called by libcurl when
     the  socket has been created, but before the connect call to
     allow applications to change specific  socket  options.  The
     callback's purpose argument identifies the exact purpose for
     this particular socket:

     CURLSOCKTYPE_IPCXN for actively created connections or since
     7.28.0  CURLSOCKTYPE_ACCEPT  for FTP when the connection was
     setup with PORT/EPSV  (in  earlier  versions  these  sockets
     weren't passed to this callback).

     Future versions of libcurl may support more  purposes.  lib-
     curl passes the newly created socket descriptor to the call-
     back in the  curlfd  parameter  so  additional  setsockopt()
     calls can be done at the user's discretion.

     The clientp pointer contains whatever user-defined value set
     using the CURLOPT_SOCKOPTDATA(3) function.

     Return CURL_SOCKOPT_OK from the callback on success.  Return
     CURL_SOCKOPT_ERROR  from  the callback function to signal an
     unrecoverable error to the library and  it  will  close  the
     socket and return CURLE_COULDNT_CONNECT.  Alternatively, the
     callback function can return CURL_SOCKOPT_ALREADY_CONNECTED,

libcurl 7.58.0      Last change: May 15, 2017                   1

CURLOPT_SOCKOPTFUNCTION(3curl_easy_setopt optionCURLOPT_SOCKOPTFUNCTION(3)

     to  tell  libcurl  that  the socket is already connected and
     then libcurl will not attempt to connect it. This allows  an
     application  to  pass  in  an  already connected socket with
     CURLOPT_OPENSOCKETFUNCTION(3) and then  have  this  function
     make libcurl not attempt to connect (again).

DEFAULT

     By default, this callback is NULL and unused.

PROTOCOLS

     All

EXAMPLE

     /* make libcurl use the already established socket 'sockfd' */

     static curl_socket_t opensocket(void *clientp,
                                     curlsocktype purpose,
                                     struct curl_sockaddr *address)
     {
       curl_socket_t sockfd;
       sockfd = *(curl_socket_t *)clientp;
       /* the actual externally set socket is passed in via the OPENSOCKETDATA
          option */
       return sockfd;
     }

     static int sockopt_callback(void *clientp, curl_socket_t curlfd,
                                 curlsocktype purpose)
     {
       /* This return code was added in libcurl 7.21.5 */
       return CURL_SOCKOPT_ALREADY_CONNECTED;
     }

     curl = curl_easy_init();
     if(curl) {
       /* libcurl will internally think that you connect to the host
        * and port that you specify in the URL option. */
       curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
       /* call this function to get a socket */
       curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
       curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);

       /* call this function to set options for the socket */
       curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);

       res = curl_easy_perform(curl);

       curl_easy_cleanup(curl);

AVAILABILITY

     Added in 7.16.0. The  CURL_SOCKOPT_ALREADY_CONNECTED  return
     code was added in 7.21.5.

libcurl 7.58.0      Last change: May 15, 2017                   2

CURLOPT_SOCKOPTFUNCTION(3curl_easy_setopt optionCURLOPT_SOCKOPTFUNCTION(3)

RETURN VALUE

     Returns  CURLE_OK  if   the   option   is   supported,   and
     CURLE_UNKNOWN_OPTION if not.

SEE ALSO

     CURLOPT_SOCKOPTDATA(3), CURLOPT_OPENSOCKETFUNCTION(3),

libcurl 7.58.0      Last change: May 15, 2017                   3