quickjs-tart

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

CURLOPT_WRITEFUNCTION.md (3746B)

      1 ---
      2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
      3 SPDX-License-Identifier: curl
      4 Title: CURLOPT_WRITEFUNCTION
      5 Section: 3
      6 Source: libcurl
      7 See-also:
      8   - CURLOPT_HEADERFUNCTION (3)
      9   - CURLOPT_READFUNCTION (3)
     10   - CURLOPT_WRITEDATA (3)
     11 Protocol:
     12   - All
     13 Added-in: 7.1
     14 ---
     15 
     16 # NAME
     17 
     18 CURLOPT_WRITEFUNCTION - callback for writing received data
     19 
     20 # SYNOPSIS
     21 
     22 ~~~c
     23 #include <curl/curl.h>
     24 
     25 size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);
     26 
     27 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback);
     28 ~~~
     29 
     30 # DESCRIPTION
     31 
     32 Pass a pointer to your callback function, which should match the prototype
     33 shown above.
     34 
     35 This callback function gets called by libcurl as soon as there is data
     36 received that needs to be saved. For most transfers, this callback gets called
     37 many times and each invoke delivers another chunk of data. *ptr* points to the
     38 delivered data, and the size of that data is *nmemb*; *size* is always 1.
     39 
     40 The data passed to this function is not null-terminated.
     41 
     42 The callback function is passed as much data as possible in all invokes, but
     43 you must not make any assumptions. It may be one byte, it may be
     44 thousands. The maximum amount of body data that is passed to the write
     45 callback is defined in the curl.h header file: *CURL_MAX_WRITE_SIZE* (the
     46 usual default is 16K). If CURLOPT_HEADER(3) is enabled, which makes header
     47 data get passed to the write callback, you can get up to
     48 *CURL_MAX_HTTP_HEADER* bytes of header data passed into it. This usually means
     49 100K.
     50 
     51 This function may be called with zero bytes data if the transferred file is
     52 empty.
     53 
     54 Set the *userdata* argument with the CURLOPT_WRITEDATA(3) option.
     55 
     56 Your callback should return the number of bytes actually taken care of. If
     57 that amount differs from the amount passed to your callback function, it
     58 signals an error condition to the library. This causes the transfer to get
     59 aborted and the libcurl function used returns *CURLE_WRITE_ERROR*.
     60 
     61 You can also abort the transfer by returning CURL_WRITEFUNC_ERROR (added in
     62 7.87.0), which makes *CURLE_WRITE_ERROR* get returned.
     63 
     64 If the callback function returns CURL_WRITEFUNC_PAUSE it pauses this
     65 transfer. See curl_easy_pause(3) for further details.
     66 
     67 Set this option to NULL to get the internal default function used instead of
     68 your callback. The internal default function writes the data to the FILE *
     69 given with CURLOPT_WRITEDATA(3).
     70 
     71 This option does not enable HSTS, you need to use CURLOPT_HSTS_CTRL(3) to
     72 do that.
     73 
     74 # DEFAULT
     75 
     76 fwrite(3)
     77 
     78 # %PROTOCOLS%
     79 
     80 # EXAMPLE
     81 
     82 ~~~c
     83 #include <stdlib.h> /* for realloc */
     84 #include <string.h> /* for memcpy */
     85 
     86 struct memory {
     87   char *response;
     88   size_t size;
     89 };
     90 
     91 static size_t cb(char *data, size_t size, size_t nmemb, void *clientp)
     92 {
     93   size_t realsize = size * nmemb;
     94   struct memory *mem = (struct memory *)clientp;
     95 
     96   char *ptr = realloc(mem->response, mem->size + realsize + 1);
     97   if(!ptr)
     98     return 0;  /* out of memory */
     99 
    100   mem->response = ptr;
    101   memcpy(&(mem->response[mem->size]), data, realsize);
    102   mem->size += realsize;
    103   mem->response[mem->size] = 0;
    104 
    105   return realsize;
    106 }
    107 
    108 int main(void)
    109 {
    110   struct memory chunk = {0};
    111   CURLcode res;
    112   CURL *curl = curl_easy_init();
    113   if(curl) {
    114     /* send all data to this function  */
    115     curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, cb);
    116 
    117     /* we pass our 'chunk' struct to the callback function */
    118     curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);
    119 
    120     /* send a request */
    121     res = curl_easy_perform(curl);
    122 
    123     /* remember to free the buffer */
    124     free(chunk.response);
    125 
    126     curl_easy_cleanup(curl);
    127   }
    128 }
    129 ~~~
    130 
    131 # HISTORY
    132 
    133 Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
    134 
    135 # %AVAILABILITY%
    136 
    137 # RETURN VALUE
    138 
    139 This returns CURLE_OK.