#include <curl/curl.h> CURLMcode curl_multi_socket_action(CURLM * multi_handle, curl_socket_t sockfd, int ev_bitmask, int *running_handles);
|multi_handle||Pointer to a multi handle.|
|ev_bitmask||Handle to an event bitmask.|
|running_handles||Pointer to running handles.|
If the operation was successful,
CURLM_OK is returned. Otherwise, a specific
CURLM libcurl Error Code is returned.
Before version 7.20.0: If you receive
CURLM_CALL_MULTI_PERFORM, this indicates that you should call
curl_multi_socket_action again before you wait for more actions on libcurl's sockets.
You do not have to perform this call immediately, but the return code indicates 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. Issues still may have occurred on individual transfers even when one of these functions returns successfully.
When the application has detected action on a socket handled by libcurl, it should call
curl_multi_socket_action with the sockfd argument set to the socket with the action.
When the events on a socket are known, they can be passed as an events bitmask (ev_bitmask) by first setting ev_bitmask to
0, and then adding using bitwise OR (|) any combination of events to be
CURL_CSELECT_ERR. When the events on a socket are unknown, pass
0 instead, and libcurl will test the descriptor internally.
At return, the integer running_handles points to will contain the number of running easy handles within the multi handle. When this number reaches zero, all transfers are complete/done.
When you call
curl_multi_socket_action on a specific socket and the counter decreases by one, it
DOES NOT necessarily indicate that this exact socket/transfer is the one that completed. Use
curl_multi_info_read to determine which easy
handle that completed.
curl_multi_socket_action functions inform 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
CURLMOPT_SOCKETFUNCTION option to
curl_multi_setopt. They update the status with changes since the previous time the callback
Get the timeout time by setting the
CURLMOPT_TIMERFUNCTION option with
curl_multi_setopt. Your application will then get called with
information on how long to wait for socket actions at most before doing the timeout action: call the
curl_multi_socket_action function with the sockfd argument
CURL_SOCKET_TIMEOUT. You can also use the
curl_multi_timeout 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.
The socket callback function uses a prototype like this:
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 */
The callback must return
The easy 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.
s argument is the actual socket value as you use it within your system.
socketp argument is a private pointer you have previously set with
curl_multi_assign to be associated with the
If no pointer has been set, socketp will be
NULL. This argument is a service to applications that want to keep certain data or structs that are strictly associated to the given socket.
userp argument is a private pointer you have previously set with
curl_multi_setopt and the
CURLMOPT_TIMERFUNCTION, to get to know what timeout value to use when waiting for socket activities.
curl_multi_socket_actionto kickstart everything. To get one or more callbacks called.
curl_multi_socket_actionfor the socket(s) that had action. If no activity is detected and the timeout expires, call
This function was added in libcurl 7.15.4, and is deemed stable since 7.16.0.
2013/05/08 Automated cleanup pass.
2012/05/04 Initial version.