From b61c06384ab88baf4b3231e84386c4a70126d888 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 12 Oct 2006 08:36:47 +0000 Subject: Jeff Pohlmeyer has been working with the hiperfifo.c example source code, and while doing so it became apparent that the current timeout system for the socket API really was a bit awkward since it become quite some work to be sure we have the correct timeout set. Jeff then provided the new CURLMOPT_TIMERFUNCTION that is yet another callback the app can set to get to know when the general timeout time changes and thus for an application like hiperfifo.c it makes everything a lot easier and nicer. There's a CURLMOPT_TIMERDATA option too of course in good old libcurl tradition. --- docs/libcurl/curl_multi_setopt.3 | 45 +++++++++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 14 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_multi_setopt.3 b/docs/libcurl/curl_multi_setopt.3 index 5279055ce..5ba81b952 100644 --- a/docs/libcurl/curl_multi_setopt.3 +++ b/docs/libcurl/curl_multi_setopt.3 @@ -1,6 +1,6 @@ .\" $Id$ .\" -.TH curl_multi_setopt 3 "8 Jan 2006" "libcurl 7.16.0" "libcurl Manual" +.TH curl_multi_setopt 3 "10 Oct 2006" "libcurl 7.16.0" "libcurl Manual" .SH NAME curl_multi_setopt \- set options for a curl multi handle .SH SYNOPSIS @@ -9,7 +9,7 @@ curl_multi_setopt \- set options for a curl multi handle CURLMcode curl_multi_setopt(CURLM * multi_handle, CURLMoption option, param); .SH DESCRIPTION curl_multi_setopt() is used to tell a libcurl multi handle how to behave. By -using the appropriate options to \fIcurl_multi_setopt\fP, you can change +using the appropriate options to \fIcurl_multi_setopt(3)\fP, you can change libcurl's behaviour when using that multi handle. All options are set with the \fIoption\fP followed by the parameter \fIparam\fP. That parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a @@ -19,19 +19,20 @@ You can only set one option in each function call. .SH OPTIONS .IP CURLMOPT_SOCKETFUNCTION -Pass a pointer to a function matching the curl_socket_callback prototype. The -\fIcurl_multi_socket(3)\fP functions inform the application about updates in -the socket (file descriptor) status by doing none, one or multiple calls to -the curl_socket_callback given in the \fBparam\fP argument. They update the -status with changes since the previous time a \fIcurl_multi_socket(3)\fP -function was called. If the given callback pointer is NULL, no callback will -be called. Set the callback's \fBuserp\fP argument with -\fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for more callback -details. +Pass a pointer to a function matching the \fBcurl_socket_callback\fP +prototype. The \fIcurl_multi_socket(3)\fP functions inform the application +about updates in the socket (file descriptor) status by doing none, one or +multiple calls to the curl_socket_callback given in the \fBparam\fP +argument. They update the status with changes since the previous time a +\fIcurl_multi_socket(3)\fP function was called. If the given callback pointer +is NULL, no callback will be called. Set the callback's \fBuserp\fP argument +with \fICURLMOPT_SOCKETDATA\fP. See \fIcurl_multi_socket(3)\fP for more +callback details. .IP CURLMOPT_SOCKETDATA -Pass a pointer to whatever you want passed to the curl_socket_callback's forth -argument, the userp pointer. This is not used by libcurl but only passed-thru -as-is. Set the callback pointer with \fICURLMOPT_SOCKETFUNCTION\fP. +Pass a pointer to whatever you want passed to the \fBcurl_socket_callback\fP's +forth argument, the userp pointer. This is not used by libcurl but only +passed-thru as-is. Set the callback pointer with +\fICURLMOPT_SOCKETFUNCTION\fP. .IP CURLMOPT_PIPELINING Pass a long set to 1 to enable or 0 to disable. Enabling pipelining on a multi handle will make it attempt to perform HTTP Pipelining as far as possible for @@ -39,6 +40,22 @@ transfers using this handle. This means that if you add a second request that can use an already existing connection, the second request will be \&"piped" on the same connection rather than being executed in parallell. (Added in 7.16.0) +.IP CURLMOPT_TIMERFUNCTION +Pass a pointer to a function matching the \fBcurl_multi_timer_callback\fP +prototype. This function will then be called when the timeout value +changes. The timeout value is at what latest time the application should call +one of the \&"performing" functions of the multi interface +(\fIcurl_multi_socket(3)\fP, \fIcurl_multi_socket_all(3)\fP and +\fIcurl_multi_perform(3)\fP) - to allow libcurl to keep timeouts and retries +etc to work. Libcurl attempts to limit calling this only when the fixed future +timeout time actually change. See also \fICURLMOPT_TIMERDATA\fP. This callback +can be used instead of, or in addition to, \fIcurl_multi_timeout(3)\fP. (Added +in 7.16.0) +.IP CURLMOPT_TIMERDATA +Pass a pointer to whatever you want passed to the +\fBcurl_multi_timer_callback\fP's third argument, the userp pointer. This is +not used by libcurl but only passed-thru as-is. Set the callback pointer with +\fICURLMOPT_TIMERFUNCTION\fP. (Added in 7.16.0) .SH RETURNS The standard CURLMcode for multi interface error codes. Note that it returns a CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl -- cgit v1.2.3