Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/curl/docs/libcurl/curl_mime_data_cb.3 @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
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 "22 August 2017" "libcurl 7.56.0" "libcurl Manual"
23 .SH NAME
24 curl_mime_data_cb - set a callback-based data source for a mime part's body
25 .SH SYNOPSIS
26 .B #include <curl/curl.h>
27 .sp
28 size_t readfunc(char *buffer, size_t size, size_t nitems, void *arg);
29 .br
30 int seekfunc(void *arg, curl_off_t offset, int origin);
31 .br
32 void freefunc(void *arg);
33 .sp
34 .BI "CURLcode curl_mime_data_cb(curl_mimepart * " part ", curl_off_t " datasize ,
35 .br
36 .BI " curl_read_callback " readfunc ", curl_seek_callback " seekfunc ,
37 .br
38 .BI " curl_free_callback " freefunc ", void * " arg ");"
39 .ad
40 .SH DESCRIPTION
41 \fIcurl_mime_data_cb(3)\fP sets the data source of a mime part's body content
42 from a data read callback function.
43
44 \fIpart\fP is the part's to assign contents to.
45
46 \fIreadfunc\fP is a pointer to a data read callback function, with a signature
47 as shown by the above prototype. It may not be set to NULL.
48
49 \fIseekfunc\fP is a pointer to a seek callback function, with a signature as
50 shown by the above prototype. This function will be used upon resending data
51 (i.e.: after a redirect); this pointer may be set to NULL, in which case a
52 resend is not possible.
53
54 \fIfreefunc\fP is a pointer to a user resource freeing callback function, with
55 a signature as shown by the above prototype. If no resource is to be freed, it
56 may safely be set to NULL. This function will be called upon mime structure
57 freeing.
58
59 \fIarg\fP is a user defined argument to callback functions.
60
61 The read callback function gets called by libcurl as soon as it needs to
62 read data in order to send it to the peer - like if you ask it to upload or
63 post data to the server. The data area pointed at by the pointer \fIbuffer\fP
64 should be filled up with at most \fIsize\fP multiplied with \fInmemb\fP number
65 of bytes by your function.
66
67 Your read function must then return the actual number of bytes that it stored
68 in that memory area. Returning 0 will signal end-of-file to the library and
69 cause it to stop the current transfer.
70
71 If you stop the current transfer by returning 0 "pre-maturely" (i.e. before the
72 server expected it, like when you've said you will upload N bytes and you
73 upload less than N bytes), you may experience that the server "hangs" waiting
74 for the rest of the data that won't come.
75
76 The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current
77 operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error
78 code from the transfer.
79
80 The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this
81 connection to pause. See \fIcurl_easy_pause(3)\fP for further details.
82
83 The seek function gets called by libcurl to rewind input stream data or to
84 seek to a certain position. The function shall work like fseek(3) or lseek(3)
85 and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP,
86 although libcurl currently only passes SEEK_SET.
87
88 The callback function must return \fICURL_SEEKFUNC_OK\fP on success,
89 \fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or
90 \fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl
91 is free to work around the problem if possible. The latter can sometimes be
92 done by instead reading from the input or similar.
93
94 Care must be taken if the part is bound to a curl easy handle that is later
95 duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in
96 the pointed item to be shared between the original and the copied handle.
97 In particular, special attention should be given to the \fIfreefunc\fP
98 procedure code since it will be called twice with the same argument.
99
100 .SH AVAILABILITY
101 As long as at least one of HTTP, SMTP or IMAP is enabled. Added in 7.56.0.
102 .SH RETURN VALUE
103 CURLE_OK or a CURL error code upon failure.
104 .SH EXAMPLE
105 Sending a huge data string will cause the same amount of memory to be
106 allocated: to avoid overhead resources consumption, one might want to use a
107 callback source to avoid data duplication. In this case, original data
108 must be retained until after the transfer terminates.
109 .nf
110
111 char hugedata[512000];
112
113 struct ctl {
114 char *buffer;
115 curl_off_t size;
116 curl_off_t position;
117 };
118
119 size_t read_callback(char *buffer, size_t size, size_t nitems, void *arg)
120 {
121 struct ctl *p = (struct ctl *) arg;
122 curl_off_t sz = p->size - p->position;
123
124 nitems *= size;
125 if(sz > nitems)
126 sz = nitems;
127 if(sz)
128 memcpy(buffer, p->buffer + p->position, sz);
129 p->position += sz;
130 return sz;
131 }
132
133 int seek_callback(void *arg, curl_off_t offset, int origin)
134 {
135 struct ctl *p = (struct ctl *) arg;
136
137 switch(origin) {
138 case SEEK_END:
139 offset += p->size;
140 break;
141 case SEEK_CUR:
142 offset += p->position;
143 break;
144 }
145
146 if(offset < 0)
147 return CURL_SEEKFUNC_FAIL;
148 p->position = offset;
149 return CURL_SEEKFUNC_OK;
150 }
151
152 CURL *easy = curl_easy_init();
153 curl_mime *mime = curl_mime_init(easy);
154 curl_mimepart *part = curl_mime_addpart(mime);
155 struct ctl hugectl;
156
157 hugectl.buffer = hugedata;
158 hugectl.size = sizeof hugedata;
159 hugectl.position = 0;
160 curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL,
161 &hugectl);
162
163 .SH "SEE ALSO"
164 .BR curl_mime_addpart "(3),"
165 .BR curl_mime_data "(3),"
166 .BR curl_mime_name "(3),"
167 .BR curl_easy_duphandle "(3)"