CURLMOPT_TIMERFUNCTION(3)

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

NAME

6       CURLMOPT_TIMERFUNCTION - set 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, /* see above */
13                          void *userp);    /* 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 interval of timeout_ms. Each time that timer fires,  call
26       either  curl_multi_socket_action(3) or curl_multi_perform(3), depending
27       on which interface you use.
28
29       A timeout_ms value of -1 means you should delete your timer.
30
31       A    timeout_ms    value    of    0    means    you     should     call
32       curl_multi_socket_action(3)  or curl_multi_perform(3) (once) as soon as
33       possible.
34
35       timer_callback will only be called when the timeout_ms changes.
36
37       The userp pointer is set with CURLMOPT_TIMERDATA(3).
38
39       The timer callback should return 0 on success, and -1  on  error.  This
40       callback  can  be  used instead of, or in addition to, curl_multi_time‐
41       out(3).
42

DEFAULT

44       NULL
45

PROTOCOLS

47       All
48

EXAMPLE

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

AVAILABILITY

85       Added in 7.16.0
86

RETURN VALUE

88       Returns CURLM_OK if the option is supported,  and  CURLM_UNKNOWN_OPTION
89       if not.
90