1curl_mime_data_cb(3)            libcurl Manual            curl_mime_data_cb(3)
2
3
4

NAME

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

SYNOPSIS

10       #include <curl/curl.h>
11
12       size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
13
14       int seekfunc(void *arg, curl_off_t offset, int origin);
15
16       void freefunc(void *arg);
17
18       CURLcode curl_mime_data_cb(curl_mimepart *part, curl_off_t datasize,
19                                  curl_read_callback readfunc,
20                                  curl_seek_callback seekfunc,
21                                  curl_free_callback freefunc, void *arg);
22

DESCRIPTION

24       curl_mime_data_cb(3) sets the data source of a mime part's body content
25       from a data read callback function.
26
27       part is the part's to assign contents to.
28
29       readfunc  is  a pointer to a data read callback function, with a signa‐
30       ture as shown by the above prototype. It may not be set to NULL.
31
32       seekfunc is a pointer to a seek callback function, with a signature  as
33       shown by the above prototype. This function will be used upon resending
34       data (i.e.: after a redirect); this pointer may  be  set  to  NULL,  in
35       which case a resend is not possible.
36
37       freefunc  is  a  pointer  to a user resource freeing callback function,
38       with a signature as shown by the above prototype. If no resource is  to
39       be  freed,  it  may safely be set to NULL. This function will be called
40       upon mime structure freeing.
41
42       arg is a user defined argument to callback functions.
43
44       The read callback function gets called by libcurl as soon as  it  needs
45       to  read  data  in order to send it to the peer - like if you ask it to
46       upload or post data to the server. The data  area  pointed  at  by  the
47       pointer  buffer  should  be filled up with at most size multiplied with
48       nitems number of bytes by your function.
49
50       Your read function must then return the actual number of bytes that  it
51       stored  in that memory area. Returning 0 will signal end-of-file to the
52       library and cause it to stop the current transfer.
53
54       If you stop the current transfer by returning  0  "pre-maturely"  (i.e.
55       before  the server expected it, like when you have said you will upload
56       N bytes and you upload less than N bytes), you may experience that  the
57       server "hangs" waiting for the rest of the data that will not come.
58
59       The  read  callback  may return CURL_READFUNC_ABORT to stop the current
60       operation immediately, resulting in a  CURLE_ABORTED_BY_CALLBACK  error
61       code from the transfer.
62
63       The  callback can return CURL_READFUNC_PAUSE to cause reading from this
64       connection to pause. See curl_easy_pause(3) for further details.
65
66       The seek function gets called by libcurl to rewind input stream data or
67       to seek to a certain position. The function shall work like fseek(3) or
68       lseek(3) and it gets SEEK_SET, SEEK_CUR or  SEEK_END  as  argument  for
69       origin, although libcurl currently only passes SEEK_SET.
70
71       The   callback   function  must  return  CURL_SEEKFUNC_OK  on  success,
72       CURL_SEEKFUNC_FAIL to cause the upload operation to fail or  CURL_SEEK‐
73       FUNC_CANTSEEK  to  indicate that while the seek failed, libcurl is free
74       to work around the problem if possible. The  latter  can  sometimes  be
75       done by instead reading from the input or similar.
76
77       Care  must  be taken if the part is bound to a curl easy handle that is
78       later duplicated: the arg pointer argument is also duplicated,  result‐
79       ing  in  the  pointed  item  to  be shared between the original and the
80       copied handle.  In particular, special attention should be given to the
81       freefunc procedure code since it will be called twice with the same ar‐
82       gument.
83

EXAMPLE

85       Sending a huge data string will cause the same amount of memory  to  be
86       allocated:  to  avoid overhead resources consumption, one might want to
87       use a callback source to avoid data duplication. In this case, original
88       data must be retained until after the transfer terminates.
89
90       char hugedata[512000];
91
92       struct ctl {
93         char *buffer;
94         curl_off_t size;
95         curl_off_t position;
96       };
97
98       size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg)
99       {
100         struct ctl *p = (struct ctl *) arg;
101         curl_off_t sz = p->size - p->position;
102
103         nitems *= size;
104         if(sz > nitems)
105           sz = nitems;
106         if(sz)
107           memcpy(buffer, p->buffer + p->position, sz);
108         p->position += sz;
109         return sz;
110       }
111
112       int seek_callback(void *arg, curl_off_t offset, int origin)
113       {
114         struct ctl *p = (struct ctl *) arg;
115
116         switch(origin) {
117         case SEEK_END:
118           offset += p->size;
119           break;
120         case SEEK_CUR:
121           offset += p->position;
122           break;
123         }
124
125         if(offset < 0)
126           return CURL_SEEKFUNC_FAIL;
127         p->position = offset;
128         return CURL_SEEKFUNC_OK;
129       }
130
131        CURL *easy = curl_easy_init();
132        curl_mime *mime = curl_mime_init(easy);
133        curl_mimepart *part = curl_mime_addpart(mime);
134        struct ctl hugectl;
135
136        hugectl.buffer = hugedata;
137        hugectl.size = sizeof hugedata;
138        hugectl.position = 0;
139        curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
140                          &hugectl);
141
142

AVAILABILITY

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

RETURN VALUE

148       CURLE_OK or a CURL error code upon failure.
149

SEE ALSO

151       curl_mime_addpart(3),       curl_mime_data(3),       curl_mime_name(3),
152       curl_easy_duphandle(3)
153
154
155
156libcurl 7.85.0                   May 17, 2022             curl_mime_data_cb(3)
Impressum