Opensocket and closesocket callbacks

Occasionally you end up in a situation where you want your application to
control with more precision exactly what socket libcurl will use for its
operations. libcurl offers this pair of callbacks that replaces libcurl’s own
call to socket() and the subsequent close() of the same file descriptor.

Provide a file descriptor

By setting the CURLOPT_OPENSOCKETFUNCTION callback, you can provide a custom
function to return a file descriptor for libcurl to use:

curl_easy_setopt(handle, CURLOPT_OPENSOCKETFUNCTION, opensocket_callback);

The opensocket_callback function must match this prototype:

curl_socket_t opensocket_callback(void *clientp,
                                  curlsocktype purpose,
                                  struct curl_sockaddr *address);

The callback gets the clientp as first argument, which is simply an opaque
pointer you set with CURLOPT_OPENSOCKETDATA.

The other two arguments pass in data that identifies for what purpose and
address the socket is to be used. The purpose is a typedef with a value of
CURLSOCKTYPE_IPCXN or CURLSOCKTYPE_ACCEPT, basically identifying in which
circumstance the socket is created. The “accept” case being when libcurl is
used to accept an incoming FTP connection for when FTP active mode is used,
and all other cases when libcurl creates a socket for its own outgoing
connections the IPCXN value is passed in.

The address pointer points to a struct curl_sockaddr that describes the IP
address of the network destination for which this socket is created. Your
callback can for example use this information to whitelist or blacklist
specific addresses or address ranges.

The socketopen callback is also explicitly allowed to modify the target
address in that struct, if you would like to offer some sort of network filter
or translation layer.

The callback should return a file descriptor or CURL_SOCKET_BAD, which then
will cause an unrecoverable error within libcurl and it will eventually return
CURLE_COULDNT_CONNECT from its perform function.

If you want to return a file descriptor that is already connected to a
server, then you must also set the sockopt callback and
make sure that returns the correct return value.

The curl_sockaddress struct looks like this:

struct curl_sockaddr {
  int family;
  int socktype;
  int protocol;
  unsigned int addrlen;
  struct sockaddr addr;
};

Socket close callback

The corresponding callback to the open socket is of course the close
socket. Usually when you provide a custom way to provide a file descriptor you
want to provide your own cleanup version as well:

curl_easy_setopt(handle, CURLOPT_CLOSEOCKETFUNCTION, closesocket_callback);

The closesocket_callback function must match this prototype:

int closesocket_callback(void *clientp, curl_socket_t item);