mirror of
https://codeberg.org/kiss-community/repo
synced 2024-08-19 12:46:58 +00:00
116 lines
3.7 KiB
Groff
116 lines
3.7 KiB
Groff
.\" generated by cd2nroff 0.1 from CURLOPT_WRITEFUNCTION.md
|
|
.TH CURLOPT_WRITEFUNCTION 3 "2024-06-01" libcurl
|
|
.SH NAME
|
|
CURLOPT_WRITEFUNCTION \- callback for writing received data
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
size_t write_callback(char *ptr, size_t size, size_t nmemb, void *userdata);
|
|
|
|
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_WRITEFUNCTION, write_callback);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
Pass a pointer to your callback function, which should match the prototype
|
|
shown above.
|
|
|
|
This callback function gets called by libcurl as soon as there is data
|
|
received that needs to be saved. For most transfers, this callback gets called
|
|
many times and each invoke delivers another chunk of data. \fIptr\fP points to the
|
|
delivered data, and the size of that data is \fInmemb\fP; \fIsize\fP is always 1.
|
|
|
|
The data passed to this function is not null\-terminated.
|
|
|
|
The callback function is passed as much data as possible in all invokes, but
|
|
you must not make any assumptions. It may be one byte, it may be
|
|
thousands. The maximum amount of body data that is passed to the write
|
|
callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the
|
|
usual default is 16K). If \fICURLOPT_HEADER(3)\fP is enabled, which makes header
|
|
data get passed to the write callback, you can get up to
|
|
\fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually means
|
|
100K.
|
|
|
|
This function may be called with zero bytes data if the transferred file is
|
|
empty.
|
|
|
|
Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option.
|
|
|
|
Your callback should return the number of bytes actually taken care of. If
|
|
that amount differs from the amount passed to your callback function, it
|
|
signals an error condition to the library. This causes the transfer to get
|
|
aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP.
|
|
|
|
You can also abort the transfer by returning CURL_WRITEFUNC_ERROR (added in
|
|
7.87.0), which makes \fICURLE_WRITE_ERROR\fP get returned.
|
|
|
|
If the callback function returns CURL_WRITEFUNC_PAUSE it pauses this
|
|
transfer. See \fIcurl_easy_pause(3)\fP for further details.
|
|
|
|
Set this option to NULL to get the internal default function used instead of
|
|
your callback. The internal default function writes the data to the FILE *
|
|
given with \fICURLOPT_WRITEDATA(3)\fP.
|
|
|
|
This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to
|
|
do that.
|
|
.SH DEFAULT
|
|
libcurl uses \(aqfwrite\(aq as a callback by default.
|
|
.SH PROTOCOLS
|
|
All
|
|
.SH EXAMPLE
|
|
.nf
|
|
#include <stdlib.h> /* for realloc */
|
|
#include <string.h> /* for memcpy */
|
|
|
|
struct memory {
|
|
char *response;
|
|
size_t size;
|
|
};
|
|
|
|
static size_t cb(char *data, size_t size, size_t nmemb, void *clientp)
|
|
{
|
|
size_t realsize = size * nmemb;
|
|
struct memory *mem = (struct memory *)clientp;
|
|
|
|
char *ptr = realloc(mem->response, mem->size + realsize + 1);
|
|
if(!ptr)
|
|
return 0; /* out of memory! */
|
|
|
|
mem->response = ptr;
|
|
memcpy(&(mem->response[mem->size]), data, realsize);
|
|
mem->size += realsize;
|
|
mem->response[mem->size] = 0;
|
|
|
|
return realsize;
|
|
}
|
|
|
|
int main(void)
|
|
{
|
|
struct memory chunk = {0};
|
|
CURLcode res;
|
|
CURL *curl = curl_easy_init();
|
|
if(curl) {
|
|
/* send all data to this function */
|
|
curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, cb);
|
|
|
|
/* we pass our 'chunk' struct to the callback function */
|
|
curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);
|
|
|
|
/* send a request */
|
|
res = curl_easy_perform(curl);
|
|
|
|
/* remember to free the buffer */
|
|
free(chunk.response);
|
|
|
|
curl_easy_cleanup(curl);
|
|
}
|
|
}
|
|
.fi
|
|
.SH AVAILABILITY
|
|
Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0.
|
|
.SH RETURN VALUE
|
|
This returns CURLE_OK.
|
|
.SH SEE ALSO
|
|
.BR CURLOPT_HEADERFUNCTION (3),
|
|
.BR CURLOPT_READFUNCTION (3),
|
|
.BR CURLOPT_WRITEDATA (3)
|