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:
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
|
.\" * This software is licensed as described in the file COPYING, which
|
||||||
.\" * you should have received as part of this distribution. The terms
|
.\" * 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
|
CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the
|
||||||
whole process or when a timeout occurs.
|
whole process or when a timeout occurs.
|
||||||
|
|
||||||
At return, \fBrunning_handles\fP points to the number
|
At return, \fBrunning_handles\fP points to the number of running easy handles
|
||||||
of running easy handles within the multi handle. When this number reaches
|
within the multi handle. When this number reaches zero, all transfers are
|
||||||
zero, all transfers are complete/done. When you call
|
complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific
|
||||||
\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter
|
socket and the counter decreases by one, it DOES NOT necessarily mean that
|
||||||
decreases by one, it DOES NOT necessarily mean that this exact socket/transfer
|
this exact socket/transfer is the one that completed. Use
|
||||||
is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out
|
\fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed.
|
||||||
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
|
updates in the socket (file descriptor) status by doing none, one, or multiple
|
||||||
calls to the socket callback function set with the
|
calls to the socket callback function set with the
|
||||||
\fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They
|
\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
|
\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
|
for an event-based system using the callback is far better than relying on
|
||||||
polling the timeout value.
|
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"
|
.SH "TYPICAL USAGE"
|
||||||
1. Create a multi handle
|
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
|
.\" * This software is licensed as described in the file COPYING, which
|
||||||
.\" * you should have received as part of this distribution. The terms
|
.\" * 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
|
Pass a pointer to your callback function, which should match the prototype
|
||||||
shown above.
|
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
|
application about updates in the socket (file descriptor) status by doing
|
||||||
none, one, or multiple calls to the \fBsocket_callback\fP. The callback gets
|
none, one, or multiple calls to the \fBsocket_callback\fP. The callback
|
||||||
status updates with changes since the previous time the callback was called.
|
function gets status updates with changes since the previous time the callback
|
||||||
If the given callback pointer is NULL, no callback will be called. Set the
|
was called. If the given callback pointer is set to NULL, no callback will be
|
||||||
callback's \fBuserp\fP argument with \fICURLMOPT_SOCKETDATA(3)\fP. See
|
called.
|
||||||
\fIcurl_multi_socket_action(3)\fP for more details on how the callback is used
|
.SH "CALLBACK ARGUMENTS"
|
||||||
and should work.
|
\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
|
The \fBwhat\fP parameter informs the callback on the status of the given
|
||||||
socket. It can hold one of these values:
|
socket. It can hold one of these values:
|
||||||
|
Loading…
Reference in New Issue
Block a user