From 12d01cb6fa914519d1ced0223cd9ff96a2634de9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 15 Jun 2013 14:57:01 +0200 Subject: CURLOPT_XFERINFOFUNCTION: introducing a new progress callback CURLOPT_XFERINFOFUNCTION is now the preferred progress callback function and CURLOPT_PROGRESSFUNCTION is considered deprecated. This new callback uses pure 'curl_off_t' arguments to pass on full resolution sizes. It otherwise retains the same characteristics: the same call rate, the same meanings for the arguments and the return code is used the same way. The progressfunc.c example is updated to show how to use the new callback for newer libcurls while supporting the older one if built with an older libcurl or even built with a newer libcurl while running with an older. --- docs/libcurl/curl_easy_setopt.3 | 44 ++++++++++++++++++++++++++++++++++++++++ docs/libcurl/symbols-in-versions | 4 +++- 2 files changed, 47 insertions(+), 1 deletion(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index e5ca09f4b..bebf8c08d 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -377,10 +377,54 @@ function that performs transfers. \fICURLOPT_NOPROGRESS\fP must be set to 0 to make this function actually get called. +.IP CURLOPT_XFERINFOFUNCTION +Pass a pointer to a function that matches the following prototype: + +.nf +\fBint function(void *clientp, curl_off_t dltotal, curl_off_t dlnow, + curl_off_t ultotal, curl_off_t ulnow);\fP +.fi + +This function gets called by libcurl instead of its internal equivalent with a +frequent interval. While data is being transferred it will be called very +frequently, and during slow periods like when nothing is being transferred it +can slow down to about one call per second. + +\fIclientp\fP is the pointer set with \fICURLOPT_XFERINFODATA\fP, it is only +passed along from the application to the callback. + +The callback gets told how much data libcurl will transfer and has +transferred, in number of bytes. \fIdltotal\fP is the total number of bytes +libcurl expects to download in this transfer. \fIdlnow\fP is the number of +bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl +expects to upload in this transfer. \fIulnow\fP is the number of bytes +uploaded so far. + +Unknown/unused argument values passed to the callback will be set to zero +(like if you only download data, the upload size will remain 0). Many times +the callback will be called one or more times first, before it knows the data +sizes so a program must be made to handle that. + +Returning a non-zero value from this callback will cause libcurl to abort the +transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. + +If you transfer data with the multi interface, this function will not be +called during periods of idleness unless you call the appropriate libcurl +function that performs transfers. + +\fICURLOPT_NOPROGRESS\fP must be set to 0 to make this function actually +get called. + +(Added in 7.32.0) .IP CURLOPT_PROGRESSDATA Pass a pointer that will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP. The default value of this parameter is unspecified. +.IP CURLOPT_XFERINFODATA +Pass a pointer that will be untouched by libcurl and passed as the first +argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION\fP. +The default value of this parameter is unspecified. This option is an alias +for CURLOPT_PROGRESSDATA. (Added in 7.32.0) .IP CURLOPT_HEADERFUNCTION Pass a pointer to a function that matches the following prototype: \fBsize_t function( void *ptr, size_t size, size_t nmemb, void diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 54b6dbc3d..e61cbbee9 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -428,7 +428,7 @@ CURLOPT_POSTREDIR 7.19.1 CURLOPT_PREQUOTE 7.9.5 CURLOPT_PRIVATE 7.10.3 CURLOPT_PROGRESSDATA 7.1 -CURLOPT_PROGRESSFUNCTION 7.1 +CURLOPT_PROGRESSFUNCTION 7.1 7.32.0 CURLOPT_PROTOCOLS 7.19.4 CURLOPT_PROXY 7.1 CURLOPT_PROXYAUTH 7.10.7 @@ -525,6 +525,8 @@ CURLOPT_WRITEDATA 7.9.7 CURLOPT_WRITEFUNCTION 7.1 CURLOPT_WRITEHEADER 7.1 CURLOPT_WRITEINFO 7.1 +CURLOPT_XFERINFODATA 7.32.0 +CURLOPT_XFERINFOFUNCTION 7.32.0 CURLPAUSE_ALL 7.18.0 CURLPAUSE_CONT 7.18.0 CURLPAUSE_RECV 7.18.0 -- cgit v1.2.3