docs/libcurl/curl_mime_data_cb.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at https://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .TH curl_mime_data_cb 3 "January 14, 2018" "libcurl 7.59.0" "libcurl Manual"
  23
  24 .SH NAME
  25 curl_mime_data_cb - set a callback-based data source for a mime part's body
  26 .SH SYNOPSIS
  27 .B #include <curl/curl.h>
  28 .sp
  29 size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
  30 .br
  31 int seekfunc(void *arg, curl_off_t offset, int origin);
  32 .br
  33 void freefunc(void *arg);
  34 .sp
  35 .BI "CURLcode curl_mime_data_cb(curl_mimepart * " part ", curl_off_t " datasize ,
  36 .br
  37 .BI "        curl_read_callback " readfunc ", curl_seek_callback " seekfunc ,
  38 .br
  39 .BI "        curl_free_callback " freefunc ", void * " arg ");"
  40 .ad
  41 .SH DESCRIPTION
  42 \fIcurl_mime_data_cb(3)\fP sets the data source of a mime part's body content
  43 from a data read callback function.
  44
  45 \fIpart\fP is the part's to assign contents to.
  46
  47 \fIreadfunc\fP is a pointer to a data read callback function, with a signature
  48 as shown by the above prototype. It may not be set to NULL.
  49
  50 \fIseekfunc\fP is a pointer to a seek callback function, with a signature as
  51 shown by the above prototype. This function will be used upon resending data
  52 (i.e.: after a redirect); this pointer may be set to NULL, in which case a
  53 resend is not possible.
  54
  55 \fIfreefunc\fP is a pointer to a user resource freeing callback function, with
  56 a signature as shown by the above prototype. If no resource is to be freed, it
  57 may safely be set to NULL. This function will be called upon mime structure
  58 freeing.
  59
  60 \fIarg\fP is a user defined argument to callback functions.
  61
  62 The read callback function gets called by libcurl as soon as it needs to
  63 read data in order to send it to the peer - like if you ask it to upload or
  64 post data to the server. The data area pointed at by the pointer \fIbuffer\fP
  65 should be filled up with at most \fIsize\fP multiplied with \fInmemb\fP number
  66 of bytes by your function.
  67
  68 Your read function must then return the actual number of bytes that it stored
  69 in that memory area. Returning 0 will signal end-of-file to the library and
  70 cause it to stop the current transfer.
  71
  72 If you stop the current transfer by returning 0 "pre-maturely" (i.e before the
  73 server expected it, like when you've said you will upload N bytes and you
  74 upload less than N bytes), you may experience that the server "hangs" waiting
  75 for the rest of the data that won't come.
  76
  77 The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
  78 operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
  79 code from the transfer.
  80
  81 The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
  82 connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
  83
  84 The seek function gets called by libcurl to rewind input stream data or to
  85 seek to a certain position. The function shall work like fseek(3) or lseek(3)
  86 and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP,
  87 although libcurl currently only passes SEEK_SET.
  88
  89 The callback function must return \fICURL_SEEKFUNC_OK\fP on success,
  90 \fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or
  91 \fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl
  92 is free to work around the problem if possible. The latter can sometimes be
  93 done by instead reading from the input or similar.
  94
  95 Care must be taken if the part is bound to a curl easy handle that is later
  96 duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in
  97 the pointed item to be shared between the original and the copied handle.
  98 In particular, special attention should be given to the \fIfreefunc\fP
  99 procedure code since it will be called twice with the same argument.
 100
 101 .SH AVAILABILITY
 102 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
 103 .SH RETURN VALUE
 104 CURLE_OK or a CURL error code upon failure.
 105 .SH EXAMPLE
 106 Sending a huge data string will cause the same amount of memory to be
 107 allocated: to avoid overhead resources consumption, one might want to use a
 108 callback source to avoid data duplication. In this case, original data
 109 must be retained until after the transfer terminates.
 110 .nf
 111
 112 char hugedata[512000];
 113
 114 struct ctl {
 115   char *buffer;
 116   curl_off_t size;
 117   curl_off_t position;
 118 };
 119
 120 size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg)
 121 {
 122   struct ctl *p = (struct ctl *) arg;
 123   curl_off_t sz = p->size - p->position;
 124
 125   nitems *= size;
 126   if(sz > nitems)
 127     sz = nitems;
 128   if(sz)
 129     memcpy(buffer, p->buffer + p->position, sz);
 130   p->position += sz;
 131   return sz;
 132 }
 133
 134 int seek_callback(void *arg, curl_off_t offset, int origin)
 135 {
 136   struct ctl *p = (struct ctl *) arg;
 137
 138   switch(origin) {
 139   case SEEK_END:
 140     offset += p->size;
 141     break;
 142   case SEEK_CUR:
 143     offset += p->position;
 144     break;
 145   }
 146
 147   if(offset < 0)
 148     return CURL_SEEKFUNC_FAIL;
 149   p->position = offset;
 150   return CURL_SEEKFUNC_OK;
 151 }
 152
 153  CURL *easy = curl_easy_init();
 154  curl_mime *mime = curl_mime_init(easy);
 155  curl_mimepart *part = curl_mime_addpart(mime);
 156  struct ctl hugectl;
 157
 158  hugectl.buffer = hugedata;
 159  hugectl.size = sizeof hugedata;
 160  hugectl.position = 0;
 161  curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
 162                    &hugectl);
 163
 164 .SH "SEE ALSO"
 165 .BR curl_mime_addpart "(3),"
 166 .BR curl_mime_data "(3),"
 167 .BR curl_mime_name "(3),"
 168 .BR curl_easy_duphandle "(3)"