quickjs-tart

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

CURLOPT_XFERINFOFUNCTION.md (3509B)

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