docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at http://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .\"
  23 .TH CURLMOPT_TIMERFUNCTION 3 "17 Jun 2014" "libcurl 7.37.0" "curl_multi_setopt options"
  24 .SH NAME
  25 CURLMOPT_TIMERFUNCTION \- set callback to receive timeout values
  26 .SH SYNOPSIS
  27 .nf
  28 #include <curl/curl.h>
  29
  30 int timer_callback(CURLM *multi,    /* multi handle */
  31                    long timeout_ms, /* see above */
  32                    void *userp);    /* private callback pointer */
  33
  34 CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_TIMERFUNCTION, timer_callback);
  35 .SH DESCRIPTION
  36 Pass a pointer to your callback function, which should match the prototype
  37 shown above.
  38
  39 Certain features, such as timeouts and retries, require you to call libcurl
  40 even when there is no activity on the file descriptors.
  41
  42 Your callback function \fBtimer_callback\fP should install a non-repeating
  43 timer with an interval of \fBtimeout_ms\fP. Each time that timer fires, call
  44 either \fIcurl_multi_socket_action(3)\fP or \fIcurl_multi_perform(3)\fP,
  45 depending on which interface you use.
  46
  47 A \fBtimeout_ms\fP value of -1 means you should delete your timer.
  48
  49 A \fBtimeout_ms\fP value of 0 means you should call
  50 \fIcurl_multi_socket_action(3)\fP or \fIcurl_multi_perform(3)\fP (once) as soon
  51 as possible.
  52
  53 \fBtimer_callback\fP will only be called when the \fBtimeout_ms\fP changes.
  54
  55 The \fBuserp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP.
  56
  57 The timer callback should return 0 on success, and -1 on error. This callback
  58 can be used instead of, or in addition to, \fIcurl_multi_timeout(3)\fP.
  59 .SH DEFAULT
  60 NULL
  61 .SH PROTOCOLS
  62 All
  63 .SH EXAMPLE
  64 .nf
  65 static gboolean timeout_cb(gpointer user_data) {
  66     if (user_data) {
  67         g_free(user_data);
  68         curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL);
  69     }
  70     int running;
  71     curl_multi_socket_action(multi, CURL_SOCKET_TIMEOUT, 0, &running);
  72     return G_SOURCE_REMOVE;
  73 }
  74
  75 static int timerfunc(CURLM *multi, long timeout_ms, void *userp) {
  76     guint *id = userp;
  77
  78     if (id)
  79         g_source_remove(*id);
  80
  81     // -1 means we should just delete our timer.
  82     if (timeout_ms == -1) {
  83         g_free(id);
  84         id = NULL;
  85     } else {
  86         if (!id)
  87             id = g_new(guint, 1);
  88         *id = g_timeout_add(timeout_ms, timeout_cb, id);
  89     }
  90     curl_multi_setopt(multi, CURLMOPT_TIMERDATA, id);
  91     return 0;
  92 }
  93
  94 curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc);
  95 .fi
  96 .SH AVAILABILITY
  97 Added in 7.16.0
  98 .SH RETURN VALUE
  99 Returns CURLM_OK if the option is supported, and CURLM_UNKNOWN_OPTION if not.
 100 .SH "SEE ALSO"
 101 .BR CURLMOPT_TIMERDATA "(3), " CURLMOPT_SOCKETFUNCTION "(3), "