Annotation of embedaddon/curl/docs/libcurl/curl_formadd.3, revision 1.1.1.1
1.1 misho 1: .\" **************************************************************************
2: .\" * _ _ ____ _
3: .\" * Project ___| | | | _ \| |
4: .\" * / __| | | | |_) | |
5: .\" * | (__| |_| | _ <| |___
6: .\" * \___|\___/|_| \_\_____|
7: .\" *
8: .\" * Copyright (C) 1998 - 2020, 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_formadd 3 "March 23, 2020" "libcurl 7.70.0" "libcurl Manual"
23:
24: .SH NAME
25: curl_formadd - add a section to a multipart/formdata HTTP POST
26: .SH SYNOPSIS
27: .B #include <curl/curl.h>
28: .sp
29: .BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem,
30: .BI "struct curl_httppost ** " lastitem, " ...);"
31: .ad
32: .SH DESCRIPTION
33: This function is deprecated. Do not use! See \fIcurl_mime_init(3)\fP instead!
34:
35: curl_formadd() is used to append sections when building a multipart/formdata
36: HTTP POST (sometimes referred to as RFC2388-style posts). Append one section
37: at a time until you've added all the sections you want included and then you
38: pass the \fIfirstitem\fP pointer as parameter to \fICURLOPT_HTTPPOST(3)\fP.
39: \fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated
40: invokes it should be left as set to allow repeated invokes to find the end of
41: the list faster.
42:
43: After the \fIlastitem\fP pointer follow the real arguments.
44:
45: The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to
46: NULL in the first call to this function. All list-data will be allocated by
47: the function itself. You must call \fIcurl_formfree(3)\fP on the
48: \fIfirstitem\fP after the form post has been done to free the resources.
49:
50: Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
51: You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual.
52:
53: First, there are some basics you need to understand about multipart/formdata
54: posts. Each part consists of at least a NAME and a CONTENTS part. If the part
55: is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
56: Below, we'll discuss what options you use to set these properties in the
57: parts you want to add to your post.
58:
59: The options listed first are for making normal parts. The options from
60: \fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload
61: parts.
62: .SH OPTIONS
63: .IP CURLFORM_COPYNAME
64: followed by a string which provides the \fIname\fP of this part. libcurl
65: copies the string so your application doesn't need to keep it around after
66: this function call. If the name isn't NUL-terminated, you must set its length
67: with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to contain
68: zero-valued bytes. The copied data will be freed by \fIcurl_formfree(3)\fP.
69: .IP CURLFORM_PTRNAME
70: followed by a string which provides the \fIname\fP of this part. libcurl
71: will use the pointer and refer to the data in your application, so you
72: must make sure it remains until curl no longer needs it. If the name
73: isn't NUL-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
74: The \fIname\fP is not allowed to contain zero-valued bytes.
75: .IP CURLFORM_COPYCONTENTS
76: followed by a pointer to the contents of this part, the actual data
77: to send away. libcurl copies the provided data, so your application doesn't
78: need to keep it around after this function call. If the data isn't null
79: terminated, or if you'd like it to contain zero bytes, you must
80: set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied
81: data will be freed by \fIcurl_formfree(3)\fP.
82: .IP CURLFORM_PTRCONTENTS
83: followed by a pointer to the contents of this part, the actual data
84: to send away. libcurl will use the pointer and refer to the data in your
85: application, so you must make sure it remains until curl no longer needs it.
86: If the data isn't NUL-terminated, or if you'd like it to contain zero bytes,
87: you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP.
88: .IP CURLFORM_CONTENTLEN
89: followed by a curl_off_t value giving the length of the contents. Note that
90: for \fICURLFORM_STREAM\fP contents, this option is mandatory.
91:
92: If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
93: the contents to figure out the size. If you really want to send a zero byte
94: content then you must make sure strlen() on the data pointer returns zero.
95:
96: (Option added in 7.46.0)
97: .IP CURLFORM_CONTENTSLENGTH
98: (This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead!)
99:
100: followed by a long giving the length of the contents. Note that for
101: \fICURLFORM_STREAM\fP contents, this option is mandatory.
102:
103: If you pass a 0 (zero) for this option, libcurl will instead do a strlen() on
104: the contents to figure out the size. If you really want to send a zero byte
105: content then you must make sure strlen() on the data pointer returns zero.
106: .IP CURLFORM_FILECONTENT
107: followed by a filename, causes that file to be read and its contents used
108: as data in this part. This part does \fInot\fP automatically become a file
109: upload part simply because its data was read from a file.
110:
111: The specified file needs to kept around until the associated transfer is done.
112: .IP CURLFORM_FILE
113: followed by a filename, makes this part a file upload part. It sets the
114: \fIfilename\fP field to the basename of the provided filename, it reads the
115: contents of the file and passes them as data and sets the content-type if the
116: given file match one of the internally known file extensions. For
117: \fBCURLFORM_FILE\fP the user may send one or more files in one part by
118: providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
119: (and each \fICURLFORM_FILE\fP is allowed to have a
120: \fICURLFORM_CONTENTTYPE\fP).
121:
122: The given upload file has to exist in its full in the file system already when
123: the upload starts, as libcurl needs to read the correct file size beforehand.
124:
125: The specified file needs to kept around until the associated transfer is done.
126: .IP CURLFORM_CONTENTTYPE
127: is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
128: string which provides the content-type for this part, possibly instead of an
129: internally chosen one.
130: .IP CURLFORM_FILENAME
131: is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
132: string, it tells libcurl to use the given string as the \fIfilename\fP in the
133: file upload part instead of the actual file name.
134: .IP CURLFORM_BUFFER
135: is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It
136: tells libcurl that the file contents are already present in a buffer. The
137: parameter is a string which provides the \fIfilename\fP field in the content
138: header.
139: .IP CURLFORM_BUFFERPTR
140: is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
141: to the buffer to be uploaded. This buffer must not be freed until after
142: \fIcurl_easy_cleanup(3)\fP is called. You must also use
143: \fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
144: .IP CURLFORM_BUFFERLENGTH
145: is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
146: long which gives the length of the buffer.
147: .IP CURLFORM_STREAM
148: Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
149: data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on
150: to the read callback's fourth argument. If you want the part to look like a
151: file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that
152: when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
153: set with the total expected length of the part unless the formpost is sent
154: chunked encoded. (Option added in libcurl 7.18.2)
155: .IP CURLFORM_ARRAY
156: Another possibility to send options to curl_formadd() is the
157: \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
158: its value. Each curl_forms structure element has a CURLformoption and a char
159: pointer. The final element in the array must be a CURLFORM_END. All available
160: options can be used in an array, except the CURLFORM_ARRAY option itself! The
161: last argument in such an array must always be \fBCURLFORM_END\fP.
162: .IP CURLFORM_CONTENTHEADER
163: specifies extra headers for the form POST section. This takes a curl_slist
164: prepared in the usual way using \fBcurl_slist_append\fP and appends the list
165: of headers to those libcurl automatically generates. The list must exist while
166: the POST occurs, if you free it before the post completes you may experience
167: problems.
168:
169: When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
170: the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
171: you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
172:
173: See example below.
174: .SH AVAILABILITY
175: Deprecated in 7.56.0. Before this release, field names were allowed to
176: contain zero-valued bytes. The pseudo-filename "-" to read stdin is
177: discouraged although still supported, but data is not read before being
178: actually sent: the effective data size can then not be automatically
179: determined, resulting in a chunked encoding transfer. Backslashes and
180: double quotes in field and file names are now escaped before transmission.
181: .SH RETURN VALUE
182: 0 means everything was ok, non-zero means an error occurred corresponding
183: to a CURL_FORMADD_* constant defined in
184: .I <curl/curl.h>
185: .SH EXAMPLE
186: .nf
187:
188: struct curl_httppost* post = NULL;
189: struct curl_httppost* last = NULL;
190: char namebuffer[] = "name buffer";
191: long namelength = strlen(namebuffer);
192: char buffer[] = "test buffer";
193: char htmlbuffer[] = "<HTML>test buffer</HTML>";
194: long htmlbufferlength = strlen(htmlbuffer);
195: struct curl_forms forms[3];
196: char file1[] = "my-face.jpg";
197: char file2[] = "your-face.jpg";
198: /* add null character into htmlbuffer, to demonstrate that
199: transfers of buffers containing null characters actually work
200: */
201: htmlbuffer[8] = '\\0';
202:
203: /* Add simple name/content section */
204: curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
205: CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
206:
207: /* Add simple name/content/contenttype section */
208: curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
209: CURLFORM_COPYCONTENTS, "<HTML></HTML>",
210: CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
211:
212: /* Add name/ptrcontent section */
213: curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
214: CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
215:
216: /* Add ptrname/ptrcontent section */
217: curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
218: CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
219: namelength, CURLFORM_END);
220:
221: /* Add name/ptrcontent/contenttype section */
222: curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
223: CURLFORM_PTRCONTENTS, htmlbuffer,
224: CURLFORM_CONTENTSLENGTH, htmlbufferlength,
225: CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
226:
227: /* Add simple file section */
228: curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
229: CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
230:
231: /* Add file/contenttype section */
232: curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
233: CURLFORM_FILE, "my-face.jpg",
234: CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
235:
236: /* Add two file section */
237: curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
238: CURLFORM_FILE, "my-face.jpg",
239: CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
240:
241: /* Add two file section using CURLFORM_ARRAY */
242: forms[0].option = CURLFORM_FILE;
243: forms[0].value = file1;
244: forms[1].option = CURLFORM_FILE;
245: forms[1].value = file2;
246: forms[2].option = CURLFORM_END;
247:
248: /* Add a buffer to upload */
249: curl_formadd(&post, &last,
250: CURLFORM_COPYNAME, "name",
251: CURLFORM_BUFFER, "data",
252: CURLFORM_BUFFERPTR, record,
253: CURLFORM_BUFFERLENGTH, record_length,
254: CURLFORM_END);
255:
256: /* no option needed for the end marker */
257: curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
258: CURLFORM_ARRAY, forms, CURLFORM_END);
259: /* Add the content of a file as a normal post text value */
260: curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
261: CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
262: /* Set the form info */
263: curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
264:
265: .SH "SEE ALSO"
266: .BR curl_easy_setopt "(3),"
267: .BR curl_formfree "(3),"
268: .BR curl_mime_init "(3)"
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to curl_formadd.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl