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