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