CURLMOPT_TIMERFUNCTION.3: Clarify, add an example

Pass a pointer to your callback function, which should match the prototype

Pass a pointer to your callback function, which should match the prototype

shown above.

shown above.

This callback function will be called when the timeout value changes. The

Certain features, such as timeouts and retries, require you to call libcurl

\fBtimeout_ms\fP value is at what latest time the application should call one

even when there is no activity on the file descriptors.

of the \&"performing" functions of the multi interface

(\fIcurl_multi_socket_action(3)\fP and \fIcurl_multi_perform(3)\fP) - to allow

Your callback function \fBtimer_callback\fP should install a non-repeating

libcurl to keep timeouts and retries etc to work. A \fBtimeout_ms\fP value of

timer with an interval of \fBtimeout_ms\fP. Each time that timer fires, call

-1 means that there is no timeout at all, and 0 means that the timeout is

either \fIcurl_multi_socket_action(3)\fP or \fIcurl_multi_perform(3)\fP,

already expired. libcurl attempts to limit calling this only when the fixed

depending on which interface you use.

future timeout time actually changes.

A \fBtimeout_ms\fP value of -1 means you should delete your timer.

A \fBtimeout_ms\fP value of 0 means you should call

\fIcurl_multi_socket_action(3)\fP or \fIcurl_multi_perform(3)\fP (once) as soon

as possible.

\fBtimer_callback\fP will only be called when the \fBtimeout_ms\fP changes.

The \fBuserp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP.

The \fBuserp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP.

.SH PROTOCOLS

.SH PROTOCOLS

All

All

.SH EXAMPLE

.SH EXAMPLE

TODO

.nf

static gboolean timeout_cb(gpointer user_data) {

    if (user_data) {

        g_free(user_data);

        curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL);

    }

    int running;

    curl_multi_socket_action(multi, CURL_SOCKET_TIMEOUT, 0, &running);

    return G_SOURCE_REMOVE;

}

static int timerfunc(CURLM *multi, long timeout_ms, void *userp) {

    guint *id = userp;

    if (id)

        g_source_remove(*id);

    // -1 means we should just delete our timer.

    if (timeout_ms == -1) {

        g_free(id);

        id = NULL;

    } else {

        if (!id)

            id = g_new(guint, 1);

        *id = g_timeout_add(timeout_ms, timeout_cb, id);

    }

    curl_multi_setopt(multi, CURLMOPT_TIMERDATA, id);

    return 0;

}

curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc);

.fi

.SH AVAILABILITY

.SH AVAILABILITY

Added in 7.16.0

Added in 7.16.0

.SH RETURN VALUE

.SH RETURN VALUE