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