CURLMOPT_TIMERFUNCTION(3)

1CURLMOPT_TIMERFUNCTION(3)  curl_multi_setopt options CURLMOPT_TIMERFUNCTION(3)
2
3
4

NAME

6       CURLMOPT_TIMERFUNCTION - callback to receive timeout values
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       int timer_callback(CURLM *multi,    /* multi handle */
12                          long timeout_ms, /* timeout in number of ms */
13                          void *clientp);    /* private callback pointer */
14
15       CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback);
16

DESCRIPTION

18       Pass a pointer to your callback function, which should match the proto‐
19       type shown above.
20
21       Certain features, such as timeouts and retries,  require  you  to  call
22       libcurl even when there is no activity on the file descriptors.
23
24       Your  callback  function  timer_callback should install a non-repeating
25       timer with an expire time of timeout_ms milliseconds. When  that  timer
26       fires,   call  either  curl_multi_socket_action(3)  or  curl_multi_per‐
27       form(3), depending on which interface you use.
28
29       A timeout_ms value of -1 passed  to  this  callback  means  you  should
30       delete  the timer. All other values are valid expire times in number of
31       milliseconds.
32
33       The timer_callback will only be called when the timeout expire time  is
34       changed.
35
36       The clientp pointer is set with CURLMOPT_TIMERDATA(3).
37
38       The timer callback should return 0 on success, and -1 on error. If this
39       callback returns error, all transfers currently  in  progress  in  this
40       multi handle will be aborted and fail.
41
42       This   callback   can   be   used   instead  of,  or  in  addition  to,
43       curl_multi_timeout(3).
44
45       WARNING: do not call libcurl directly from within the  callback  itself
46       when  the  timeout_ms  value  is zero, since it risks triggering an un‐
47       pleasant recursive behavior that immediately calls another call to  the
48       callback with a zero timeout...
49

DEFAULT

51       NULL
52

PROTOCOLS

54       All
55

EXAMPLE

57       static gboolean timeout_cb(gpointer user_data)
58       {
59         int running;
60         if(user_data) {
61           g_free(user_data);
62           curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL);
63         }
64         curl_multi_socket_action(multi, CURL_SOCKET_TIMEOUT, 0, &running);
65         return G_SOURCE_REMOVE;
66       }
67
68       static int timerfunc(CURLM *multi, long timeout_ms, void *clientp)
69       {
70         guint *id = clientp;
71
72         if(id)
73           g_source_remove(*id);
74
75         /* -1 means we should just delete our timer. */
76         if(timeout_ms == -1) {
77           g_free(id);
78           id = NULL;
79         }
80         else {
81           if(!id)
82             id = g_new(guint, 1);
83           *id = g_timeout_add(timeout_ms, timeout_cb, id);
84         }
85         current_timer = id;
86         return 0;
87       }
88
89       curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc);
90

AVAILABILITY

92       Added in 7.16.0
93

RETURN VALUE

95       Returns  CURLM_OK  if the option is supported, and CURLM_UNKNOWN_OPTION
96       if not.
97