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 RFC2388-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
44 CURLFORM_COPYNAME
45 followed by a string which provides the name of this part.
46 libcurl copies the string so your application doesn't need to
47 keep it around after this function call. If the name isn't NUL-
48 terminated, or if you'd like it to contain zero bytes, you must
49 set its length with CURLFORM_NAMELENGTH. The copied data will be
50 freed by curl_formfree(3).
51 CURLFORM_PTRNAME
53 followed by a string which provides the name of this part.
54 libcurl will use the pointer and refer to the data in your
55 application, so you must make sure it remains until curl no
56 longer needs it. If the name isn't NUL-terminated, or if you'd
57 like it to contain zero bytes, you must set its length with
58 CURLFORM_NAMELENGTH.
59 CURLFORM_COPYCONTENTS
61 followed by a pointer to the contents of this part, the actual
62 data to send away. libcurl copies the provided data, so your
63 application doesn't need to keep it around after this function
64 call. If the data isn't null terminated, or if you'd like it to
65 contain zero bytes, you must set the length of the name with
66 CURLFORM_CONTENTSLENGTH. The copied data will be freed by
67 curl_formfree(3).
68 CURLFORM_PTRCONTENTS
70 followed by a pointer to the contents of this part, the actual
71 data to send away. libcurl will use the pointer and refer to the
72 data in your application, so you must make sure it remains until
73 curl no longer needs it. If the data isn't NUL-terminated, or
74 if you'd like it to contain zero bytes, you must set its length
75 with CURLFORM_CONTENTSLENGTH.
76 CURLFORM_CONTENTSLENGTH
78 followed by a long giving the length of the contents. Note that
79 for CURLFORM_STREAM contents, this option is mandatory.
80 CURLFORM_FILECONTENT
82 followed by a filename, causes that file to be read and its con‐
83 tents used as data in this part. This part does not automati‐
84 cally become a file upload part simply because its data was read
85 from a file.
86 CURLFORM_FILE
88 followed by a filename, makes this part a file upload part. It
89 sets the filename field to the basename of the provided file‐
90 name, it reads the contents of the file and passes them as data
91 and sets the content-type if the given file match one of the
92 internally known file extensions. For CURLFORM_FILE the user
93 may send one or more files in one part by providing multiple
94 CURLFORM_FILE arguments each followed by the filename (and each
95 CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE).
96 CURLFORM_CONTENTTYPE
98 is used in combination with CURLFORM_FILE. Followed by a pointer
99 to a string which provides the content-type for this part, pos‐
100 sibly instead of an internally chosen one.
101 CURLFORM_FILENAME
103 is used in combination with CURLFORM_FILE. Followed by a pointer
104 to a string, it tells libcurl to use the given string as the
105 filename in the file upload part instead of the actual file
106 name.
107 CURLFORM_BUFFER
109 is used for custom file upload parts without use of CURL‐
110 FORM_FILE. It tells libcurl that the file contents are already
111 present in a buffer. The parameter is a string which provides
112 the filename field in the content header.
113 CURLFORM_BUFFERPTR
115 is used in combination with CURLFORM_BUFFER. The parameter is a
116 pointer to the buffer to be uploaded. This buffer must not be
117 freed until after curl_easy_cleanup(3) is called. You must also
118 use CURLFORM_BUFFERLENGTH to set the number of bytes in the buf‐
119 fer.
120 CURLFORM_BUFFERLENGTH
122 is used in combination with CURLFORM_BUFFER. The parameter is a
123 long which gives the length of the buffer.
124 CURLFORM_STREAM
126 Tells libcurl to use the CURLOPT_READFUNCTION callback to get
127 data. The parameter you pass to CURLFORM_STREAM is the pointer
128 passed on to the read callback's fourth argument. If you want
129 the part to look like a file upload one, set the CURLFORM_FILE‐
130 NAME parameter as well. Note that when using CURLFORM_STREAM,
131 CURLFORM_CONTENTSLENGTH must also be set with the total expected
132 length of the part. (Option added in libcurl 7.18.2)
133 CURLFORM_ARRAY
135 Another possibility to send options to curl_formadd() is the
136 CURLFORM_ARRAY option, that passes a struct curl_forms array
137 pointer as its value. Each curl_forms structure element has a
138 CURLformoption and a char pointer. The final element in the
139 array must be a CURLFORM_END. All available options can be used
140 in an array, except the CURLFORM_ARRAY option itself! The last
141 argument in such an array must always be CURLFORM_END.
142 CURLFORM_CONTENTHEADER
144 specifies extra headers for the form POST section. This takes a
145 curl_slist prepared in the usual way using curl_slist_append and
146 appends the list of headers to those libcurl automatically gen‐
147 erates. The list must exist while the POST occurs, if you free
148 it before the post completes you may experience problems.
149 When you've passed the HttpPost pointer to curl_easy_setopt(3)
151 (using the CURLOPT_HTTPPOST option), you must not free the list
152 until after you've called curl_easy_cleanup(3) for the curl han‐
153 dle.
154 See example below.
156
158 0 means everything was ok, non-zero means an error occurred correspond‐
159 ing to a CURL_FORMADD_* constant defined in <curl/curl.h>
160
162 struct curl_httppost* post = NULL;
163 struct curl_httppost* last = NULL;
164 char namebuffer[] = "name buffer";
165 long namelength = strlen(namebuffer);
166 char buffer[] = "test buffer";
167 char htmlbuffer[] = "<HTML>test buffer</HTML>";
168 long htmlbufferlength = strlen(htmlbuffer);
169 struct curl_forms forms[3];
170 char file1[] = "my-face.jpg";
171 char file2[] = "your-face.jpg";
172 /* add null character into htmlbuffer, to demonstrate that
173 transfers of buffers containing null characters actually work
174 */
175 htmlbuffer[8] = '\0';
176 /* Add simple name/content section */
178 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
179 CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
180 /* Add simple name/content/contenttype section */
182 curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
183 CURLFORM_COPYCONTENTS, "<HTML></HTML>",
184 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
185 /* Add name/ptrcontent section */
187 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
188 CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
189 /* Add ptrname/ptrcontent section */
191 curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
192 CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
193 namelength, CURLFORM_END);
194 /* Add name/ptrcontent/contenttype section */
196 curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
197 CURLFORM_PTRCONTENTS, htmlbuffer,
198 CURLFORM_CONTENTSLENGTH, htmlbufferlength,
199 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
200 /* Add simple file section */
202 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
203 CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
204 /* Add file/contenttype section */
206 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
207 CURLFORM_FILE, "my-face.jpg",
208 CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
209 /* Add two file section */
211 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
212 CURLFORM_FILE, "my-face.jpg",
213 CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
214 /* Add two file section using CURLFORM_ARRAY */
216 forms[0].option = CURLFORM_FILE;
217 forms[0].value = file1;
218 forms[1].option = CURLFORM_FILE;
219 forms[1].value = file2;
220 forms[2].option = CURLFORM_END;
221 /* Add a buffer to upload */
223 curl_formadd(&post, &last,
224 CURLFORM_COPYNAME, "name",
225 CURLFORM_BUFFER, "data",
226 CURLFORM_BUFFERPTR, record,
227 CURLFORM_BUFFERLENGTH, record_length,
228 CURLFORM_END);
229 /* no option needed for the end marker */
231 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
232 CURLFORM_ARRAY, forms, CURLFORM_END);
233 /* Add the content of a file as a normal post text value */
234 curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
235 CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
236 /* Set the form info */
237 curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
238
241 curl_easy_setopt(3), curl_formfree(3)
242libcurl 7.9.8 24 June 2002 curl_formadd(3)