curl_mime_data_cb(3)



curl_mime_data_cb(3)     libcurl Manual      curl_mime_data_cb(3)

NAME

     curl_mime_data_cb - set a callback-based data source  for  a
     mime part's body

SYNOPSIS

     #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);

DESCRIPTION

     curl_mime_data_cb(3) sets the data source of a  mime  part's
     body content from a data read callback function.

     part is the part's to assign contents to.

     readfunc 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.

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

     freefunc 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 will be called upon mime structure freeing.

     arg 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 buffer should be filled up
     with at most size multiplied with nmemb 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 will
     signal end-of-file to the library and cause it to  stop  the
     current transfer.

libcurl 7.58.0    Last change: January 14, 2018                 1

curl_mime_data_cb(3)     libcurl Manual      curl_mime_data_cb(3)

     If you stop  the  current  transfer  by  returning  0  "pre-
     maturely"  (i.e  before  the  server  expected it, like when
     you've said you will upload N bytes and you upload less than
     N bytes), you may experience that the server "hangs" waiting
     for the rest of the data that won't come.

     The read callback may return CURL_READFUNC_ABORT to stop the
     current    operation    immediately,    resulting    in    a
     CURLE_ABORTED_BY_CALLBACK error code from the transfer.

     The callback can return CURL_READFUNC_PAUSE to cause reading
     from  this  connection  to pause. See curl_easy_pause(3) 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 origin, although lib-
     curl currently only passes SEEK_SET.

     The callback function must return CURL_SEEKFUNC_OK  on  suc-
     cess,  CURL_SEEKFUNC_FAIL  to  cause the upload operation to
     fail or CURL_SEEKFUNC_CANTSEEK 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  read-
     ing from the input or similar.

     Care must be taken if the part is bound to a curl easy  han-
     dle  that  is  later duplicated: the arg 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 freefunc  procedure
     code since it will be called twice with the same argument.

AVAILABILITY

     As long as at least one of HTTP, SMTP or  IMAP  is  enabled.
     Added in 7.56.0.

RETURN VALUE

     CURLE_OK or a CURL error code upon failure.

EXAMPLE

     Sending a huge data string will cause  the  same  amount  of
     memory to be allocated: to avoid overhead resources consump-
     tion, 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.

     char hugedata[512000];

     struct ctl {

libcurl 7.58.0    Last change: January 14, 2018                 2

curl_mime_data_cb(3)     libcurl Manual      curl_mime_data_cb(3)

       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);

curl_mime_data_cb(3)

NAME

SYNOPSIS

DESCRIPTION

AVAILABILITY

RETURN VALUE

EXAMPLE

SEE ALSO