1curl_mime_data_cb(3) libcurl Manual curl_mime_data_cb(3)
2
6 curl_mime_data_cb - set a callback-based data source for a mime part's
7 body
8
10 #include <curl/curl.h>
11 size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
13 int seekfunc(void *arg, curl_off_t offset, int origin);
14 void freefunc(void *arg);
15 CURLcode curl_mime_data_cb(curl_mimepart * part, curl_off_t datasize,
17 curl_read_callback readfunc, curl_seek_callback seekfunc,
18 curl_free_callback freefunc, void * arg);
19
21 curl_mime_data_cb(3) sets the data source of a mime part's body content
22 from a data read callback function.
23 part is the part's to assign contents to.
25 readfunc is a pointer to a data read callback function, with a signa‐
27 ture as shown by the above prototype. It may not be set to NULL.
28 seekfunc is a pointer to a seek callback function, with a signature as
30 shown by the above prototype. This function will be used upon resending
31 data (i.e.: after a redirect); this pointer may be set to NULL, in
32 which case a resend is not possible.
33 freefunc is a pointer to a user resource freeing callback function,
35 with a signature as shown by the above prototype. If no resource is to
36 be freed, it may safely be set to NULL. This function will be called
37 upon mime structure freeing.
38 arg is a user defined argument to callback functions.
40 The read callback function gets called by libcurl as soon as it needs
42 to read data in order to send it to the peer - like if you ask it to
43 upload or post data to the server. The data area pointed at by the
44 pointer buffer should be filled up with at most size multiplied with
45 nmemb number of bytes by your function.
46 Your read function must then return the actual number of bytes that it
48 stored in that memory area. Returning 0 will signal end-of-file to the
49 library and cause it to stop the current transfer.
50 If you stop the current transfer by returning 0 "pre-maturely" (i.e.
52 before the server expected it, like when you've said you will upload N
53 bytes and you upload less than N bytes), you may experience that the
54 server "hangs" waiting for the rest of the data that won't come.
55 The read callback may return CURL_READFUNC_ABORT to stop the current
57 operation immediately, resulting in a CURLE_ABORTED_BY_CALLBACK error
58 code from the transfer.
59 The callback can return CURL_READFUNC_PAUSE to cause reading from this
61 connection to pause. See curl_easy_pause(3) for further details.
62 The seek function gets called by libcurl to rewind input stream data or
64 to seek to a certain position. The function shall work like fseek(3) or
65 lseek(3) and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for
66 origin, although libcurl currently only passes SEEK_SET.
67 The callback function must return CURL_SEEKFUNC_OK on success,
69 CURL_SEEKFUNC_FAIL to cause the upload operation to fail or CURL_SEEK‐
70 FUNC_CANTSEEK to indicate that while the seek failed, libcurl is free
71 to work around the problem if possible. The latter can sometimes be
72 done by instead reading from the input or similar.
73 Care must be taken if the part is bound to a curl easy handle that is
75 later duplicated: the arg pointer argument is also duplicated, result‐
76 ing in the pointed item to be shared between the original and the
77 copied handle. In particular, special attention should be given to the
78 freefunc procedure code since it will be called twice with the same ar‐
79 gument.
80
83 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in
84 7.56.0.
85
87 CURLE_OK or a CURL error code upon failure.
88
90 Sending a huge data string will cause the same amount of memory to be
91 allocated: to avoid overhead resources consumption, one might want to
92 use a callback source to avoid data duplication. In this case, original
93 data must be retained until after the transfer terminates.
94 char hugedata[512000];
96 struct ctl {
98 char *buffer;
99 curl_off_t size;
100 curl_off_t position;
101 };
102 size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg)
104 {
105 struct ctl *p = (struct ctl *) arg;
106 curl_off_t sz = p->size - p->position;
107 nitems *= size;
109 if(sz > nitems)
110 sz = nitems;
111 if(sz)
112 memcpy(buffer, p->buffer + p->position, sz);
113 p->position += sz;
114 return sz;
115 }
116 int seek_callback(void *arg, curl_off_t offset, int origin)
118 {
119 struct ctl *p = (struct ctl *) arg;
120 switch(origin) {
122 case SEEK_END:
123 offset += p->size;
124 break;
125 case SEEK_CUR:
126 offset += p->position;
127 break;
128 }
129 if(offset < 0)
131 return CURL_SEEKFUNC_FAIL;
132 p->position = offset;
133 return CURL_SEEKFUNC_OK;
134 }
135 CURL *easy = curl_easy_init();
137 curl_mime *mime = curl_mime_init(easy);
138 curl_mimepart *part = curl_mime_addpart(mime);
139 struct ctl hugectl;
140 hugectl.buffer = hugedata;
142 hugectl.size = sizeof hugedata;
143 hugectl.position = 0;
144 curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
145 &hugectl);
146
149 curl_mime_addpart(3), curl_mime_data(3), curl_mime_name(3),
150 curl_easy_duphandle(3)
151libcurl 7.76.1 November 05, 2020 curl_mime_data_cb(3)