quickjs-tart

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

CURLOPT_READFUNCTION.md (3832B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLOPT_READFUNCTION
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLOPT_POST (3)
      9   - CURLOPT_READDATA (3)
     10   - CURLOPT_SEEKFUNCTION (3)
     11   - CURLOPT_UPLOAD (3)
     12   - CURLOPT_UPLOAD_BUFFERSIZE (3)
     13   - CURLOPT_WRITEFUNCTION (3)
     14 Protocol:
     15   - All
     16 Added-in: 7.1
     17 ---
     18 
     19 # NAME
     20 
     21 CURLOPT_READFUNCTION - read callback for data uploads
     22 
     23 # SYNOPSIS
     24 
     25 ~~~c
     26 #include <curl/curl.h>
     27 
     28 size_t read_callback(char *buffer, size_t size, size_t nitems, void *userdata);
     29 
     30 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_READFUNCTION, read_callback);
     31 ~~~
     32 
     33 # DESCRIPTION
     34 
     35 Pass a pointer to your callback function, as the prototype shows above.
     36 
     37 This callback function gets called by libcurl as soon as it needs to read data
     38 in order to send it to the peer - like if you ask it to upload or post data to
     39 the server. The data area pointed at by the pointer *buffer* should be
     40 filled up with at most *size* multiplied with *nitems* number of bytes
     41 by your function. *size* is always 1.
     42 
     43 Set the *userdata* argument with the CURLOPT_READDATA(3) option.
     44 
     45 Your function must return the actual number of bytes that it stored in the
     46 data area pointed at by the pointer *buffer*. Returning 0 signals
     47 end-of-file to the library and causes it to stop the current transfer.
     48 
     49 If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
     50 server expected it, like when you have said you would upload N bytes and you
     51 upload less than N bytes), you may experience that the server "hangs" waiting
     52 for the rest of the data that is not sent.
     53 
     54 The read callback may return *CURL_READFUNC_ABORT* to stop the current
     55 operation immediately, resulting in a *CURLE_ABORTED_BY_CALLBACK* error
     56 code from the transfer.
     57 
     58 The callback can return *CURL_READFUNC_PAUSE* to cause reading from this
     59 connection to pause. See curl_easy_pause(3) for further details.
     60 
     61 **Bugs**: when doing TFTP uploads, you must return the exact amount of data
     62 that the callback wants, or it is considered the final packet by the server
     63 end and the transfer ends there.
     64 
     65 If you set this callback pointer to NULL, or do not set it at all, the default
     66 internal read function is used. It is doing an fread() on the FILE * userdata
     67 set with CURLOPT_READDATA(3).
     68 
     69 You can set the total size of the data you are sending by using
     70 CURLOPT_INFILESIZE_LARGE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3),
     71 depending on the type of transfer. For some transfer types it may be required
     72 and it allows for better error checking.
     73 
     74 When this option is used in combination with telling libcurl to follow
     75 redirects with CURLOPT_FOLLOWLOCATION(3), the data might need to be rewound
     76 and sent again. The CURLOPT_SEEKFUNCTION(3) can then be invoked for that
     77 rewind operation.
     78 
     79 # DEFAULT
     80 
     81 fread(3)
     82 
     83 # %PROTOCOLS%
     84 
     85 # EXAMPLE
     86 
     87 ~~~c
     88 size_t read_callback(char *ptr, size_t size, size_t nmemb, void *userdata)
     89 {
     90   FILE *readhere = (FILE *)userdata;
     91   curl_off_t nread;
     92 
     93   /* copy as much data as possible into the 'ptr' buffer, but no more than
     94      'size' * 'nmemb' bytes. */
     95   size_t retcode = fread(ptr, size, nmemb, readhere);
     96 
     97   nread = (curl_off_t)retcode;
     98 
     99   fprintf(stderr, "*** We read %" CURL_FORMAT_CURL_OFF_T
    100           " bytes from file\n", nread);
    101   return retcode;
    102 }
    103 
    104 int main(int argc, char **argv)
    105 {
    106   FILE *file = fopen(argv[1], "rb");
    107   CURLcode result;
    108 
    109   CURL *curl = curl_easy_init();
    110   if(curl) {
    111     /* set callback to use */
    112     curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
    113 
    114     /* pass in suitable argument to callback */
    115     curl_easy_setopt(curl, CURLOPT_READDATA, (void *)file);
    116 
    117     result = curl_easy_perform(curl);
    118   }
    119 }
    120 ~~~
    121 
    122 # HISTORY
    123 
    124 CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT
    125 was added in 7.12.1.
    126 
    127 # %AVAILABILITY%
    128 
    129 # RETURN VALUE
    130 
    131 This returns CURLE_OK.