CURLMOPT_SOCKETFUNCTION.3: clarified

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * 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

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

\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

.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * 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

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: