mirror of
https://github.com/curl/curl.git
synced 2025-01-18 14:04:30 +08:00
2b3dd01b77
The callbacks were partially documented to support this. Now the behavior is documented and returning error from either of these callbacks will effectively kill all currently ongoing transfers. Added test 530 to verify Reported-by: Marcelo Juchem Fixes #8083 Closes #8089
115 lines
4.1 KiB
Groff
115 lines
4.1 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
.\" *
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
.\" * you should have received as part of this distribution. The terms
|
|
.\" * are also available at https://curl.se/docs/copyright.html.
|
|
.\" *
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
.\" * KIND, either express or implied.
|
|
.\" *
|
|
.\" **************************************************************************
|
|
.\"
|
|
.TH CURLMOPT_SOCKETFUNCTION 3 "3 Nov 2016" "libcurl 7.39.0" "curl_multi_setopt options"
|
|
.SH NAME
|
|
CURLMOPT_SOCKETFUNCTION \- callback informed about what to wait for
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
int socket_callback(CURL *easy, /* easy handle */
|
|
curl_socket_t s, /* socket */
|
|
int what, /* describes the socket */
|
|
void *userp, /* private callback pointer */
|
|
void *socketp); /* private socket pointer */
|
|
|
|
CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback);
|
|
.SH DESCRIPTION
|
|
Pass a pointer to your callback function, which should match the prototype
|
|
shown above.
|
|
|
|
When the \fIcurl_multi_socket_action(3)\fP function is called, it informs the
|
|
application about updates in the socket (file descriptor) status by doing
|
|
none, one, or multiple calls to the \fBsocket_callback\fP. The callback
|
|
function gets status updates with changes since the previous time the callback
|
|
was called. If the given callback pointer is set to NULL, no callback will be
|
|
called.
|
|
.SH "CALLBACK ARGUMENTS"
|
|
\fIeasy\fP identifies the specific transfer for which this update is related.
|
|
|
|
\fIs\fP is the specific socket this function invocation concerns. If the
|
|
\fBwhat\fP argument is not CURL_POLL_REMOVE then it holds information about
|
|
what activity on this socket the application is supposed to
|
|
monitor. Subsequent calls to this callback might update the \fBwhat\fP bits
|
|
for a socket that is already monitored.
|
|
|
|
The socket callback should return 0 on success, and -1 on error. If this
|
|
callback returns error, \fBall\fP transfers currently in progress in this
|
|
multi handle will be aborted and fail.
|
|
|
|
\fBuserp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP.
|
|
|
|
\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or will be NULL.
|
|
|
|
The \fBwhat\fP parameter informs the callback on the status of the given
|
|
socket. It can hold one of these values:
|
|
.IP CURL_POLL_IN
|
|
Wait for incoming data. For the socket to become readable.
|
|
.IP CURL_POLL_OUT
|
|
Wait for outgoing data. For the socket to become writable.
|
|
.IP CURL_POLL_INOUT
|
|
Wait for incoming and outgoing data. For the socket to become readable or
|
|
writable.
|
|
.IP CURL_POLL_REMOVE
|
|
The specified socket/file descriptor is no longer used by libcurl.
|
|
.SH DEFAULT
|
|
NULL (no callback)
|
|
.SH PROTOCOLS
|
|
All
|
|
.SH EXAMPLE
|
|
.nf
|
|
static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp)
|
|
{
|
|
GlobalInfo *g = (GlobalInfo*) cbp;
|
|
SockInfo *fdp = (SockInfo*) sockp;
|
|
|
|
if(what == CURL_POLL_REMOVE) {
|
|
remsock(fdp);
|
|
}
|
|
else {
|
|
if(!fdp) {
|
|
addsock(s, e, what, g);
|
|
}
|
|
else {
|
|
setsock(fdp, s, e, what, g);
|
|
}
|
|
}
|
|
return 0;
|
|
}
|
|
|
|
main()
|
|
{
|
|
GlobalInfo setup;
|
|
/* ... use socket callback and custom pointer */
|
|
curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb);
|
|
curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup);
|
|
}
|
|
.fi
|
|
.SH AVAILABILITY
|
|
Added in 7.15.4
|
|
.SH RETURN VALUE
|
|
Returns CURLM_OK.
|
|
.SH "SEE ALSO"
|
|
.BR CURLMOPT_SOCKETDATA "(3), " curl_multi_socket_action "(3), "
|
|
.BR CURLMOPT_TIMERFUNCTION "(3) "
|