h2-mod/deps/curl/docs/libcurl/curl_mime_data_cb.3

.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.TH curl_mime_data_cb 3 "22 August 2017" "libcurl" "libcurl"
.SH NAME
curl_mime_data_cb - set a callback-based data source for a mime part's body
.SH SYNOPSIS
.nf
#include <curl/curl.h>

size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);

int seekfunc(void *arg, curl_off_t offset, int origin);

void freefunc(void *arg);

CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize,
                           curl_read_callback readfunc,
                           curl_seek_callback seekfunc,
                           curl_free_callback freefunc, void *arg);
.fi
.SH DESCRIPTION
\fIcurl_mime_data_cb(3)\fP sets the data source of a mime part's body content
from a data read callback function.

\fIpart\fP is the part's to assign contents to.

\fIreadfunc\fP is a pointer to a data read callback function, with a signature
as shown by the above prototype. It may not be set to NULL.

\fIseekfunc\fP is a pointer to a seek callback function, with a signature as
shown by the above prototype. This function is used when resending data (i.e.:
after a redirect); this pointer may be set to NULL, in which case a resend
might not be not possible.

\fIfreefunc\fP is a pointer to a user resource freeing callback function, with
a signature as shown by the above prototype. If no resource is to be freed, it
may safely be set to NULL. This function is called upon mime structure
freeing.

\fIarg\fP is a user defined argument to callback functions.

The read callback function gets called by libcurl as soon as it needs to
read data in order to send it to the peer - like if you ask it to upload or
post data to the server. The data area pointed at by the pointer \fIbuffer\fP
should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number
of bytes by your function.

Your read function must then return the actual number of bytes that it stored
in that memory area. Returning 0 signals end-of-file to the library and cause
it to stop the current transfer.

If you stop the current transfer by returning 0 "pre-maturely" (i.e. before
the server expected it, like when you have said you intend to upload N bytes
and yet you upload less than N bytes), you may experience that the server
"hangs" waiting for the rest of the data that does not come.

The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
code from the transfer.

The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
connection to pause. See \fIcurl_easy_pause(3)\fP for further details.

The seek function gets called by libcurl to rewind input stream data or to
seek to a certain position. The function shall work like fseek(3) or lseek(3)
and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP,
although libcurl currently only passes SEEK_SET.

The callback function must return \fICURL_SEEKFUNC_OK\fP on success,
\fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or
\fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl
is free to work around the problem if possible. The latter can sometimes be
done by instead reading from the input or similar.

Care must be taken if the part is bound to a curl easy handle that is later
duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in
the pointed item to be shared between the original and the copied handle. In
particular, special attention should be given to the \fIfreefunc\fP procedure
code since it then gets called twice with the same argument.
.SH EXAMPLE
Sending a huge data string causes the same amount of memory to be allocated:
to avoid overhead resources consumption, one might want to use a callback
source to avoid data duplication. In this case, original data must be retained
until after the transfer terminates.
.nf

char hugedata[512000];

struct ctl {
  char *buffer;
  curl_off_t size;
  curl_off_t position;
};

size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg)
{
  struct ctl *p = (struct ctl *) arg;
  curl_off_t sz = p->size - p->position;

  nitems *= size;
  if(sz > nitems)
    sz = nitems;
  if(sz)
    memcpy(buffer, p->buffer + p->position, sz);
  p->position += sz;
  return sz;
}

int seek_callback(void *arg, curl_off_t offset, int origin)
{
  struct ctl *p = (struct ctl *) arg;

  switch(origin) {
  case SEEK_END:
    offset += p->size;
    break;
  case SEEK_CUR:
    offset += p->position;
    break;
  }

  if(offset < 0)
    return CURL_SEEKFUNC_FAIL;
  p->position = offset;
  return CURL_SEEKFUNC_OK;
}

 CURL *easy = curl_easy_init();
 curl_mime *mime = curl_mime_init(easy);
 curl_mimepart *part = curl_mime_addpart(mime);
 struct ctl hugectl;

 hugectl.buffer = hugedata;
 hugectl.size = sizeof hugedata;
 hugectl.position = 0;
 curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
                   &hugectl);

.SH AVAILABILITY
As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
.SH RETURN VALUE
CURLE_OK or a CURL error code upon failure.
.SH "SEE ALSO"
.BR curl_easy_duphandle (3),
.BR curl_mime_addpart (3),
.BR curl_mime_data (3),
.BR curl_mime_name (3)