Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3, revision 1.1
1.1 ! misho 1: .\" **************************************************************************
! 2: .\" * _ _ ____ _
! 3: .\" * Project ___| | | | _ \| |
! 4: .\" * / __| | | | |_) | |
! 5: .\" * | (__| |_| | _ <| |___
! 6: .\" * \___|\___/|_| \_\_____|
! 7: .\" *
! 8: .\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
! 9: .\" *
! 10: .\" * This software is licensed as described in the file COPYING, which
! 11: .\" * you should have received as part of this distribution. The terms
! 12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
! 13: .\" *
! 14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
! 15: .\" * copies of the Software, and permit persons to whom the Software is
! 16: .\" * furnished to do so, under the terms of the COPYING file.
! 17: .\" *
! 18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
! 19: .\" * KIND, either express or implied.
! 20: .\" *
! 21: .\" **************************************************************************
! 22: .\"
! 23: .TH CURLOPT_SOCKOPTFUNCTION 3 "May 15, 2017" "libcurl 7.70.0" "curl_easy_setopt options"
! 24:
! 25: .SH NAME
! 26: CURLOPT_SOCKOPTFUNCTION \- set callback for setting socket options
! 27: .SH SYNOPSIS
! 28: .nf
! 29: #include <curl/curl.h>
! 30:
! 31: typedef enum {
! 32: CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */
! 33: CURLSOCKTYPE_ACCEPT, /* socket created by accept() call */
! 34: CURLSOCKTYPE_LAST /* never use */
! 35: } curlsocktype;
! 36:
! 37: #define CURL_SOCKOPT_OK 0
! 38: #define CURL_SOCKOPT_ERROR 1 /* causes libcurl to abort and return
! 39: CURLE_ABORTED_BY_CALLBACK */
! 40: #define CURL_SOCKOPT_ALREADY_CONNECTED 2
! 41:
! 42: int sockopt_callback(void *clientp,
! 43: curl_socket_t curlfd,
! 44: curlsocktype purpose);
! 45:
! 46: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
! 47: .SH DESCRIPTION
! 48: Pass a pointer to your callback function, which should match the prototype
! 49: shown above.
! 50:
! 51: When set, this callback function gets called by libcurl when the socket has
! 52: been created, but before the connect call to allow applications to change
! 53: specific socket options. The callback's \fIpurpose\fP argument identifies the
! 54: exact purpose for this particular socket:
! 55:
! 56: \fICURLSOCKTYPE_IPCXN\fP for actively created connections or since 7.28.0
! 57: \fICURLSOCKTYPE_ACCEPT\fP for FTP when the connection was setup with PORT/EPSV
! 58: (in earlier versions these sockets weren't passed to this callback).
! 59:
! 60: Future versions of libcurl may support more purposes. libcurl passes the newly
! 61: created socket descriptor to the callback in the \fIcurlfd\fP parameter so
! 62: additional setsockopt() calls can be done at the user's discretion.
! 63:
! 64: The \fIclientp\fP pointer contains whatever user-defined value set using the
! 65: \fICURLOPT_SOCKOPTDATA(3)\fP function.
! 66:
! 67: Return \fICURL_SOCKOPT_OK\fP from the callback on success. Return
! 68: \fICURL_SOCKOPT_ERROR\fP from the callback function to signal an unrecoverable
! 69: error to the library and it will close the socket and return
! 70: \fICURLE_COULDNT_CONNECT\fP.
! 71: Alternatively, the callback function can return
! 72: \fICURL_SOCKOPT_ALREADY_CONNECTED\fP, to tell libcurl that the socket is
! 73: already connected and then libcurl will not attempt to connect it. This allows
! 74: an application to pass in an already connected socket with
! 75: \fICURLOPT_OPENSOCKETFUNCTION(3)\fP and then have this function make libcurl
! 76: not attempt to connect (again).
! 77: .SH DEFAULT
! 78: By default, this callback is NULL and unused.
! 79: .SH PROTOCOLS
! 80: All
! 81: .SH EXAMPLE
! 82: .nf
! 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: curl = curl_easy_init();
! 104: if(curl) {
! 105: /* libcurl will internally think that you connect to the host
! 106: * and port that you specify in the URL option. */
! 107: curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
! 108: /* call this function to get a socket */
! 109: curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
! 110: curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
! 111:
! 112: /* call this function to set options for the socket */
! 113: curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
! 114:
! 115: res = curl_easy_perform(curl);
! 116:
! 117: curl_easy_cleanup(curl);
! 118: .fi
! 119: .SH AVAILABILITY
! 120: Added in 7.16.0. The \fICURL_SOCKOPT_ALREADY_CONNECTED\fP return code was
! 121: added in 7.21.5.
! 122: .SH RETURN VALUE
! 123: Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
! 124: .SH "SEE ALSO"
! 125: .BR CURLOPT_SOCKOPTDATA "(3), " CURLOPT_OPENSOCKETFUNCTION "(3), "
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>