1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLMOPT_SOCKETFUNCTION 5Section: 3 6Source: libcurl 7See-also: 8 - CURLMOPT_SOCKETDATA (3) 9 - CURLMOPT_TIMERFUNCTION (3) 10 - curl_multi_socket_action (3) 11Protocol: 12 - All 13Added-in: 7.15.4 14--- 15 16# NAME 17 18CURLMOPT_SOCKETFUNCTION - callback informed about what to wait for 19 20# SYNOPSIS 21 22~~~c 23#include <curl/curl.h> 24 25int socket_callback(CURL *easy, /* easy handle */ 26 curl_socket_t s, /* socket */ 27 int what, /* describes the socket */ 28 void *clientp, /* private callback pointer */ 29 void *socketp); /* private socket pointer */ 30 31CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callback); 32~~~ 33 34# DESCRIPTION 35 36Pass a pointer to your callback function, which should match the prototype 37shown above. 38 39When the curl_multi_socket_action(3) function is called, it uses this 40callback to inform the application about updates in the socket (file 41descriptor) status by doing none, one, or multiple calls to the 42**socket_callback**. The callback function gets status updates with changes 43since the previous time the callback was called. If the given callback pointer 44is set to NULL, no callback is called. 45 46libcurl then expects the application to monitor the sockets for the specific 47activities and tell libcurl again when something happens on one of them. Tell 48libcurl by calling curl_multi_socket_action(3). 49 50# CALLBACK ARGUMENTS 51 52*easy* identifies the specific transfer for which this update is related. 53Since this callback manages a whole multi handle, an application should not 54make assumptions about which particular handle that is passed here. It might 55even be an internal easy handle that the application did not add itself. 56 57*s* is the specific socket this function invocation concerns. If the 58**what** argument is not CURL_POLL_REMOVE then it holds information about 59what activity on this socket the application is supposed to 60monitor. Subsequent calls to this callback might update the **what** bits 61for a socket that is already monitored. 62 63The socket callback should return 0 on success, and -1 on error. If this 64callback returns error, **all** transfers currently in progress in this 65multi handle are aborted and made to fail. 66 67**clientp** is set with CURLMOPT_SOCKETDATA(3). 68 69**socketp** is set with curl_multi_assign(3) or NULL. 70 71The **what** parameter informs the callback on the status of the given 72socket. It can hold one of these values: 73 74## CURL_POLL_IN 75 76Wait for incoming data. For the socket to become readable. 77 78## CURL_POLL_OUT 79 80Wait for outgoing data. For the socket to become writable. 81 82## CURL_POLL_INOUT 83 84Wait for incoming and outgoing data. For the socket to become readable or 85writable. 86 87## CURL_POLL_REMOVE 88 89The specified socket/file descriptor is no longer used by libcurl for any 90active transfer. It might soon be added again. 91 92# DEFAULT 93 94NULL (no callback) 95 96# %PROTOCOLS% 97 98# EXAMPLE 99 100~~~c 101struct priv { 102 void *ours; 103}; 104 105static int sock_cb(CURL *e, curl_socket_t s, int what, void *cbp, void *sockp) 106{ 107 struct priv *p = sockp; 108 printf("our ptr: %p\n", p->ours); 109 110 if(what == CURL_POLL_REMOVE) { 111 /* remove the socket from our collection */ 112 } 113 if(what & CURL_POLL_IN) { 114 /* wait for read on this socket */ 115 } 116 if(what & CURL_POLL_OUT) { 117 /* wait for write on this socket */ 118 } 119 120 return 0; 121} 122 123int main(void) 124{ 125 struct priv setup; 126 CURLM *multi = curl_multi_init(); 127 /* ... use socket callback and custom pointer */ 128 curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb); 129 curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup); 130} 131~~~ 132 133# %AVAILABILITY% 134 135# RETURN VALUE 136 137Returns CURLM_OK. 138