diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/TODO | 18 | ||||
| -rw-r--r-- | docs/examples/progressfunc.c | 47 | ||||
| -rw-r--r-- | docs/libcurl/curl_easy_setopt.3 | 44 | ||||
| -rw-r--r-- | docs/libcurl/symbols-in-versions | 4 |
4 files changed, 92 insertions, 21 deletions
@@ -16,9 +16,8 @@ 1.3 struct lifreq 1.4 signal-based resolver timeouts 1.5 get rid of PATH_MAX - 1.6 progress callback without doubles - 1.7 Happy Eyeball dual stack connect - 1,8 Modified buffer size approach + 1.6 Happy Eyeball dual stack connect + 1.7 Modified buffer size approach 2. libcurl - multi interface 2.1 More non-blocking @@ -158,16 +157,7 @@ we need libssh2 to properly tell us when we pass in a too small buffer and its current API (as of libssh2 1.2.7) doesn't. -1.6 progress callback without doubles - - The progress callback was introduced way back in the days and the choice to - use doubles in the arguments was possibly good at the time. Today the doubles - only confuse users and make the amounts less precise. We should introduce - another progress callback option that take precedence over the old one and - have both co-exist for a forseeable time until we can remove the double-using - one. - -1.7 Happy Eyeball dual stack connect +1.6 Happy Eyeball dual stack connect In order to make alternative technologies not suffer when transitioning, like when introducing IPv6 as an alternative to IPv4 and there are more than one @@ -179,7 +169,7 @@ http://tools.ietf.org/html/rfc6555 -1.8 Modified buffer size approach +1.7 Modified buffer size approach Current libcurl allocates a fixed 16K size buffer for download and an additional 16K for upload. They are always unconditionally part of the easy diff --git a/docs/examples/progressfunc.c b/docs/examples/progressfunc.c index 51a9c9b5e..b2635bc8a 100644 --- a/docs/examples/progressfunc.c +++ b/docs/examples/progressfunc.c @@ -5,7 +5,7 @@ * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. + * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al. * * This software is licensed as described in the file COPYING, which * you should have received as part of this distribution. The terms @@ -30,9 +30,10 @@ struct myprogress { CURL *curl; }; -static int progress(void *p, - double dltotal, double dlnow, - double ultotal, double ulnow) +/* this is how the CURLOPT_XFERINFOFUNCTION callback works */ +static int xferinfo(void *p, + curl_off_t dltotal, curl_off_t dlnow, + curl_off_t ultotal, curl_off_t ulnow) { struct myprogress *myp = (struct myprogress *)p; CURL *curl = myp->curl; @@ -48,7 +49,9 @@ static int progress(void *p, fprintf(stderr, "TOTAL TIME: %f \r\n", curtime); } - fprintf(stderr, "UP: %g of %g DOWN: %g of %g\r\n", + fprintf(stderr, "UP: %" CURL_FORMAT_CURL_OFF_T " of %" CURL_FORMAT_CURL_OFF_T + " DOWN: %" CURL_FORMAT_CURL_OFF_T " of %" CURL_FORMAT_CURL_OFF_T + "\r\n", ulnow, ultotal, dlnow, dltotal); if(dlnow > STOP_DOWNLOAD_AFTER_THIS_MANY_BYTES) @@ -56,6 +59,19 @@ static int progress(void *p, return 0; } +/* for libcurl older than 7.32.0 (CURLOPT_PROGRESSFUNCTION) */ +static int older_progress(void *p, + double dltotal, double dlnow, + double ultotal, double ulnow) +{ + return xferinfo(p, + (curl_off_t)dltotal, + (curl_off_t)dlnow, + (curl_off_t)ultotal, + (curl_off_t)ulnow); +} + + int main(void) { CURL *curl; @@ -68,9 +84,28 @@ int main(void) prog.curl = curl; curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/"); - curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, progress); + + curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, older_progress); /* pass the struct pointer into the progress function */ curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &prog); + +#if LIBCURL_VERSION_NUM >= 0x072000 + /* xferinfo was introduced in 7.32.0, no earlier libcurl versions will + compile as they won't have the symbols around. + + If built with a newer libcurl, but running with an older libcurl: + curl_easy_setopt() will fail in run-time trying to set the new + callback, making the older callback get used. + + New libcurls will prefer the new callback and instead use that one even + if both callbacks are set. */ + + curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, xferinfo); + /* pass the struct pointer into the xferinfo function, note that this is + an alias to CURLOPT_PROGRESSDATA */ + curl_easy_setopt(curl, CURLOPT_XFERINFODATA, &prog); +#endif + curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L); res = curl_easy_perform(curl); 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 |