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