mirror of
https://github.com/moparisthebest/curl
synced 2024-12-23 16:48:49 -05:00
CURLMOPT_SOCKETFUNCTION.3: clarified
Moved away the callback explanation from curl_multi_socket_action.3 and expanded it somewhat. Closes #4006
This commit is contained in:
Daniel Stenberg
parent
4da5794d81
commit
f0b7b106ff
@ -5,7 +5,7 @@
|
||||
.\" * | (__| |_| | _ <| |___
|
||||
.\" * \___|\___/|_| \_\_____|
|
||||
.\" *
|
||||
.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
|
||||
.\" * Copyright (C) 1998 - 2019, 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
|
||||
@ -43,15 +43,14 @@ libcurl will test the descriptor internally. It is also permissible to pass
|
||||
CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the
|
||||
whole process or when a timeout occurs.
|
||||
|
||||
At return, \fBrunning_handles\fP points to the number
|
||||
of running easy handles within the multi handle. When this number reaches
|
||||
zero, all transfers are complete/done. When you call
|
||||
\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter
|
||||
decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
|
||||
is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out
|
||||
which easy handle that completed.
|
||||
At return, \fBrunning_handles\fP points to the number of running easy handles
|
||||
within the multi handle. When this number reaches zero, all transfers are
|
||||
complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific
|
||||
socket and the counter decreases by one, it DOES NOT necessarily mean that
|
||||
this exact socket/transfer is the one that completed. Use
|
||||
\fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed.
|
||||
|
||||
The \fIcurl_multi_socket_action(3)\fP functions inform the application about
|
||||
The \fIcurl_multi_socket_action(3)\fP function informs the application about
|
||||
updates in the socket (file descriptor) status by doing none, one, or multiple
|
||||
calls to the socket callback function set with the
|
||||
\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They
|
||||
@ -66,65 +65,6 @@ timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the
|
||||
\fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but
|
||||
for an event-based system using the callback is far better than relying on
|
||||
polling the timeout value.
|
||||
.SH "CALLBACK DETAILS"
|
||||
|
||||
The socket \fBcallback\fP function uses a prototype like this
|
||||
.nf
|
||||
|
||||
int curl_socket_callback(CURL *easy, /* easy handle */
|
||||
curl_socket_t s, /* socket */
|
||||
int action, /* see values below */
|
||||
void *userp, /* private callback pointer */
|
||||
void *socketp); /* private socket pointer,
|
||||
\fBNULL\fP if not
|
||||
previously assigned with
|
||||
\fIcurl_multi_assign(3)\fP */
|
||||
|
||||
.fi
|
||||
The callback MUST return 0.
|
||||
|
||||
The \fIeasy\fP argument is a pointer to the easy handle that deals with this
|
||||
particular socket. Note that a single handle may work with several sockets
|
||||
simultaneously.
|
||||
|
||||
The \fIs\fP argument is the actual socket value as you use it within your
|
||||
system.
|
||||
|
||||
The \fIaction\fP argument to the callback has one of five values:
|
||||
.RS
|
||||
.IP "CURL_POLL_NONE (0)"
|
||||
register, not interested in readiness (yet)
|
||||
.IP "CURL_POLL_IN (1)"
|
||||
register, interested in read readiness
|
||||
.IP "CURL_POLL_OUT (2)"
|
||||
register, interested in write readiness
|
||||
.IP "CURL_POLL_INOUT (3)"
|
||||
register, interested in both read and write readiness
|
||||
.IP "CURL_POLL_REMOVE (4)"
|
||||
unregister
|
||||
.RE
|
||||
|
||||
The \fIsocketp\fP argument is a private pointer you have previously set with
|
||||
\fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no
|
||||
pointer has been set, socketp will be NULL. This argument is of course a
|
||||
service to applications that want to keep certain data or structs that are
|
||||
strictly associated to the given socket.
|
||||
|
||||
The \fIuserp\fP argument is a private pointer you have previously set with
|
||||
\fIcurl_multi_setopt(3)\fP and the \fICURLMOPT_SOCKETDATA(3)\fP option.
|
||||
.SH "RETURN VALUE"
|
||||
CURLMcode type, general libcurl multi interface error code.
|
||||
|
||||
Before version 7.20.0: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this
|
||||
basically means that you should call \fIcurl_multi_socket_action(3)\fP again
|
||||
before you wait for more actions on libcurl's sockets. You don't have to do it
|
||||
immediately, but the return code means that libcurl may have more data
|
||||
available to return or that there may be more data to send off before it is
|
||||
"satisfied".
|
||||
|
||||
The return code from this function is for the whole multi stack. Problems
|
||||
still might have occurred on individual transfers even when one of these
|
||||
functions return OK.
|
||||
.SH "TYPICAL USAGE"
|
||||
1. Create a multi handle
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
.\" * | (__| |_| | _ <| |___
|
||||
.\" * \___|\___/|_| \_\_____|
|
||||
.\" *
|
||||
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
|
||||
.\" * Copyright (C) 1998 - 2019, 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
|
||||
@ -38,14 +38,24 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callb
|
||||
Pass a pointer to your callback function, which should match the prototype
|
||||
shown above.
|
||||
|
||||
When the \fIcurl_multi_socket_action(3)\fP function runs, it informs the
|
||||
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 gets
|
||||
status updates with changes since the previous time the callback was called.
|
||||
If the given callback pointer is NULL, no callback will be called. Set the
|
||||
callback's \fBuserp\fP argument with \fICURLMOPT_SOCKETDATA(3)\fP. See
|
||||
\fIcurl_multi_socket_action(3)\fP for more details on how the callback is used
|
||||
and should work.
|
||||
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 alredy monitored.
|
||||
|
||||
\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:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user