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