1curl_formadd(3) libcurl Manual curl_formadd(3)
2
6 curl_formadd - add a section to a multipart/formdata HTTP POST
7
9 #include <curl/curl.h>
10 CURLFORMcode curl_formadd(struct curl_httppost ** firstitem, struct
12 curl_httppost ** lastitem, ...);
13
15 curl_formadd() is used to append sections when building a multi‐
16 part/formdata HTTP POST (sometimes referred to as rfc1867-style posts).
17 Append one section at a time until you've added all the sections you
18 want included and then you pass the firstitem pointer as parameter to
19 CURLOPT_HTTPPOST. lastitem is set after each call and on repeated
20 invokes it should be left as set to allow repeated invokes to find the
21 end of the list faster.
22 After the lastitem pointer follow the real arguments.
24 The pointers *firstitem and *lastitem should both be pointing to NULL
26 in the first call to this function. All list-data will be allocated by
27 the function itself. You must call curl_formfree(3) after the form post
28 has been done to free the resources.
29 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue"
31 header. You can disable this header with CURLOPT_HTTPHEADER as usual.
32 First, there are some basics you need to understand about multi‐
34 part/formdata posts. Each part consists of at least a NAME and a CON‐
35 TENTS part. If the part is made for file upload, there are also a
36 stored CONTENT-TYPE and a FILENAME. Below, we'll discuss what options
37 you use to set these properties in the parts you want to add to your
38 post.
39 The options listed first are for making normal parts. The options from
41 CURLFORM_FILE through CURLFORM_BUFFERLENGTH are for file upload parts.
42
45 CURLFORM_COPYNAME
46 followed by a string which provides the name of this part.
47 libcurl copies the string so your application doesn't need to
48 keep it around after this function call. If the name isn't null
49 terminated, or if you'd like it to contain zero bytes, you must
50 set its length with CURLFORM_NAMELENGTH. The copied data will be
51 freed by curl_formfree(3).
52 CURLFORM_PTRNAME
55 followed by a string which provides the name of this part.
56 libcurl will use the pointer and refer to the data in your
57 application, so you must make sure it remains until curl no
58 longer needs it. If the name isn't null terminated, or if you'd
59 like it to contain zero bytes, you must set its length with
60 CURLFORM_NAMELENGTH.
61 CURLFORM_COPYCONTENTS
64 followed by a pointer to the contents of this part, the actual
65 data to send away. libcurl copies the provided data, so your
66 application doesn't need to keep it around after this function
67 call. If the data isn't null terminated, or if you'd like it to
68 contain zero bytes, you must set the length of the name with
69 CURLFORM_CONTENTSLENGTH. The copied data will be freed by
70 curl_formfree(3).
71 CURLFORM_PTRCONTENTS
74 followed by a pointer to the contents of this part, the actual
75 data to send away. libcurl will use the pointer and refer to the
76 data in your application, so you must make sure it remains until
77 curl no longer needs it. If the data isn't null terminated, or
78 if you'd like it to contain zero bytes, you must set its length
79 with CURLFORM_CONTENTSLENGTH.
80 CURLFORM_CONTENTSLENGTH
83 followed by a long giving the length of the contents.
84 CURLFORM_FILECONTENT
87 followed by a filename, causes that file to be read and its con‐
88 tents used as data in this part. This part does not automati‐
89 cally become a file upload part simply because its data was read
90 from a file.
91 CURLFORM_FILE
94 followed by a filename, makes this part a file upload part. It
95 sets the filename field to the basename of the provided file‐
96 name, it reads the contents of the file and passes them as data
97 and sets the content-type if the given file match one of the
98 internally known file extensions. For CURLFORM_FILE the user
99 may send one or more files in one part by providing multiple
100 CURLFORM_FILE arguments each followed by the filename (and each
101 CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE).
102 CURLFORM_CONTENTTYPE
105 is used in combination with CURLFORM_FILE. Followed by a pointer
106 to a string which provides the content-type for this part, pos‐
107 sibly instead of an internally chosen one.
108 CURLFORM_FILENAME
111 is used in combination with CURLFORM_FILE. Followed by a pointer
112 to a string, it tells libcurl to use the given string as the
113 filename in the file upload part instead of the actual file
114 name.
115 CURLFORM_BUFFER
118 is used for custom file upload parts without use of CURL‐
119 FORM_FILE. It tells libcurl that the file contents are already
120 present in a buffer. The parameter is a string which provides
121 the filename field in the content header.
122 CURLFORM_BUFFERPTR
125 is used in combination with CURLFORM_BUFFER. The parameter is a
126 pointer to the buffer to be uploaded. This buffer must not be
127 freed until after curl_easy_cleanup(3) is called. You must also
128 use CURLFORM_BUFFERLENGTH to set the number of bytes in the buf‐
129 fer.
130 CURLFORM_BUFFERLENGTH
133 is used in combination with CURLFORM_BUFFER. The parameter is a
134 long which gives the length of the buffer.
135 CURLFORM_ARRAY
138 Another possibility to send options to curl_formadd() is the
139 CURLFORM_ARRAY option, that passes a struct curl_forms array
140 pointer as its value. Each curl_forms structure element has a
141 CURLformoption and a char pointer. The final element in the
142 array must be a CURLFORM_END. All available options can be used
143 in an array, except the CURLFORM_ARRAY option itself! The last
144 argument in such an array must always be CURLFORM_END.
145 CURLFORM_CONTENTHEADER
148 specifies extra headers for the form POST section. This takes a
149 curl_slist prepared in the usual way using curl_slist_append and
150 appends the list of headers to those libcurl automatically gen‐
151 erates. The list must exist while the POST occurs, if you free
152 it before the post completes you may experience problems.
153 When you've passed the HttpPost pointer to curl_easy_setopt(3)
155 (using the CURLOPT_HTTPPOST option), you must not free the list
156 until after you've called curl_easy_cleanup(3) for the curl han‐
157 dle.
158 See example below.
160
162 0 means everything was ok, non-zero means an error occurred as
163 <curl/curl.h> defines.
164
166 struct curl_httppost* post = NULL;
167 struct curl_httppost* last = NULL;
168 char namebuffer[] = "name buffer";
169 long namelength = strlen(namebuffer);
170 char buffer[] = "test buffer";
171 char htmlbuffer[] = "<HTML>test buffer</HTML>";
172 long htmlbufferlength = strlen(htmlbuffer);
173 struct curl_forms forms[3];
174 char file1[] = "my-face.jpg";
175 char file2[] = "your-face.jpg";
176 /* add null character into htmlbuffer, to demonstrate that
177 transfers of buffers containing null characters actually work
178 */
179 htmlbuffer[8] = '\0';
180 /* Add simple name/content section */
182 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
183 CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
184 /* Add simple name/content/contenttype section */
186 curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
187 CURLFORM_COPYCONTENTS, "<HTML></HTML>",
188 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
189 /* Add name/ptrcontent section */
191 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
192 CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
193 /* Add ptrname/ptrcontent section */
195 curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
196 CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
197 namelength, CURLFORM_END);
198 /* Add name/ptrcontent/contenttype section */
200 curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
201 CURLFORM_PTRCONTENTS, htmlbuffer,
202 CURLFORM_CONTENTSLENGTH, htmlbufferlength,
203 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
204 /* Add simple file section */
206 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
207 CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
208 /* Add file/contenttype section */
210 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
211 CURLFORM_FILE, "my-face.jpg",
212 CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
213 /* Add two file section */
215 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
216 CURLFORM_FILE, "my-face.jpg",
217 CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
218 /* Add two file section using CURLFORM_ARRAY */
220 forms[0].option = CURLFORM_FILE;
221 forms[0].value = file1;
222 forms[1].option = CURLFORM_FILE;
223 forms[1].value = file2;
224 forms[2].option = CURLFORM_END;
225 /* Add a buffer to upload */
227 curl_formadd(&post, &last,
228 CURLFORM_COPYNAME, "name",
229 CURLFORM_BUFFER, "data",
230 CURLFORM_BUFFERPTR, record,
231 CURLFORM_BUFFERLENGTH, record_length,
232 CURLFORM_END);
233 /* no option needed for the end marker */
235 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
236 CURLFORM_ARRAY, forms, CURLFORM_END);
237 /* Add the content of a file as a normal post text value */
238 curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
239 CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
240 /* Set the form info */
241 curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
242
245 curl_easy_setopt(3), curl_formfree(3)
246libcurl 7.9.8 24 June 2002 curl_formadd(3)