1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLMOPT_TIMERFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLMOPT_SOCKETFUNCTION (3)
9  - CURLMOPT_TIMERDATA (3)
10Protocol:
11  - All
12Added-in: 7.16.0
13---
14
15# NAME
16
17CURLMOPT_TIMERFUNCTION - callback to receive timeout values
18
19# SYNOPSIS
20
21~~~c
22#include <curl/curl.h>
23
24int timer_callback(CURLM *multi,    /* multi handle */
25                   long timeout_ms, /* timeout in number of ms */
26                   void *clientp);  /* private callback pointer */
27
28CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback);
29~~~
30
31# DESCRIPTION
32
33Pass a pointer to your callback function, which should match the prototype
34shown above.
35
36Certain features, such as timeouts and retries, require you to call libcurl
37even when there is no activity on the file descriptors.
38
39Your callback function **timer_callback** should install a single
40non-repeating timer with an expire time of **timeout_ms** milliseconds. When
41that timer fires, call either curl_multi_socket_action(3) or
42curl_multi_perform(3), depending on which interface you use.
43
44If this callback is called when a timer is already running, this new expire
45time *replaces* the former timeout. The application should then effectively
46cancel the old timeout and set a new timeout using this new expire time.
47
48A **timeout_ms** value of -1 passed to this callback means you should delete
49the timer. All other values are valid expire times in number of milliseconds.
50
51The **timer_callback** is called when the timeout expire time is changed.
52
53The **clientp** pointer is set with CURLMOPT_TIMERDATA(3).
54
55The timer callback should return 0 on success, and -1 on error. If this
56callback returns error, **all** transfers currently in progress in this multi
57handle are aborted and made to fail.
58
59This callback can be used instead of, or in addition to,
60curl_multi_timeout(3).
61
62**WARNING:** do not call libcurl directly from within the callback itself when
63the **timeout_ms** value is zero, since it risks triggering an unpleasant
64recursive behavior that immediately calls another call to the callback with a
65zero timeout...
66
67# DEFAULT
68
69NULL
70
71# %PROTOCOLS%
72
73# EXAMPLE
74
75~~~c
76struct priv {
77  void *custom;
78};
79
80static int timerfunc(CURLM *multi, long timeout_ms, void *clientp)
81{
82  struct priv *mydata = clientp;
83  printf("our ptr: %p\n", mydata->custom);
84
85  if(timeout_ms) {
86    /* this is the new single timeout to wait for */
87  }
88  else {
89    /* delete the timeout, nothing to wait for now */
90  }
91}
92
93int main(void)
94{
95  struct priv mydata;
96  CURLM *multi = curl_multi_init();
97  curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc);
98  curl_multi_setopt(multi, CURLMOPT_TIMERDATA, &mydata);
99}
100~~~
101
102# %AVAILABILITY%
103
104# RETURN VALUE
105
106Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
107