quickjs-tart

quickjs-based runtime for wallet-core logic
Log | Files | Refs | README | LICENSE

CURLOPT_PROGRESSFUNCTION.md (3584B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLOPT_PROGRESSFUNCTION
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLOPT_NOPROGRESS (3)
      9   - CURLOPT_VERBOSE (3)
     10   - CURLOPT_XFERINFOFUNCTION (3)
     11 Protocol:
     12   - All
     13 Added-in: 7.1
     14 ---
     15 
     16 # NAME
     17 
     18 CURLOPT_PROGRESSFUNCTION - progress meter callback
     19 
     20 # SYNOPSIS
     21 
     22 ~~~c
     23 #include <curl/curl.h>
     24 
     25 int progress_callback(void *clientp,
     26                       double dltotal,
     27                       double dlnow,
     28                       double ultotal,
     29                       double ulnow);
     30 
     31 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSFUNCTION,
     32                           progress_callback);
     33 ~~~
     34 
     35 # DESCRIPTION
     36 
     37 Pass a pointer to your callback function, which should match the prototype
     38 shown above.
     39 
     40 This option is deprecated and we encourage users to use the
     41 newer CURLOPT_XFERINFOFUNCTION(3) instead, if you can.
     42 
     43 This function gets called by libcurl instead of its internal equivalent with a
     44 frequent interval. While data is being transferred it is invoked frequently,
     45 and during slow periods like when nothing is being transferred it can slow
     46 down to about one call per second.
     47 
     48 *clientp* is the pointer set with CURLOPT_PROGRESSDATA(3), it is not
     49 used by libcurl but is only passed along from the application to the callback.
     50 
     51 The callback gets told how much data libcurl is about to transfer and has
     52 transferred, in number of bytes. *dltotal* is the total number of bytes
     53 libcurl expects to download in this transfer. *dlnow* is the number of
     54 bytes downloaded so far. *ultotal* is the total number of bytes libcurl
     55 expects to upload in this transfer. *ulnow* is the number of bytes
     56 uploaded so far.
     57 
     58 Unknown/unused argument values passed to the callback are be set to zero (like
     59 if you only download data, the upload size remains 0). Many times the callback
     60 is called one or more times first, before it knows the data sizes so a program
     61 must be made to handle that.
     62 
     63 Return zero from the callback if everything is fine.
     64 
     65 If your callback function returns CURL_PROGRESSFUNC_CONTINUE it causes libcurl
     66 to continue executing the default progress function.
     67 
     68 Return 1 from this callback to make libcurl abort the transfer and return
     69 *CURLE_ABORTED_BY_CALLBACK*.
     70 
     71 If you transfer data with the multi interface, this function is not called
     72 during periods of idleness unless you call the appropriate libcurl function
     73 that performs transfers.
     74 
     75 CURLOPT_NOPROGRESS(3) must be set to 0 to make this function actually
     76 get called.
     77 
     78 # DEFAULT
     79 
     80 NULL. libcurl has an internal progress meter. That is rarely wanted by users.
     81 
     82 # %PROTOCOLS%
     83 
     84 # EXAMPLE
     85 
     86 ~~~c
     87 struct progress {
     88   char *private;
     89   size_t size;
     90 };
     91 
     92 static int progress_callback(void *clientp,
     93                              double dltotal,
     94                              double dlnow,
     95                              double ultotal,
     96                              double ulnow)
     97 {
     98   struct progress *memory = clientp;
     99   printf("private: %p\n", memory->private);
    100 
    101   /* use the values */
    102 
    103   return 0; /* all is good */
    104 }
    105 
    106 int main(void)
    107 {
    108   struct progress data;
    109 
    110   CURL *curl = curl_easy_init();
    111   if(curl) {
    112     /* pass struct to callback  */
    113     curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &data);
    114     curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, progress_callback);
    115 
    116     curl_easy_perform(curl);
    117   }
    118 }
    119 ~~~
    120 
    121 # DEPRECATED
    122 
    123 Deprecated since 7.32.0.
    124 
    125 # %AVAILABILITY%
    126 
    127 # RETURN VALUE
    128 
    129 curl_easy_setopt(3) returns a CURLcode indicating success or error.
    130 
    131 CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
    132 libcurl-errors(3).