1 .\" You can view this file with:
5 .TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual"
7 curl_formadd - add a section to a multipart/formdata HTTP POST
9 .B #include <curl/curl.h>
11 .BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem,
12 .BI "struct curl_httppost ** " lastitem, " ...);"
15 curl_formadd() is used to append sections when building a multipart/formdata
16 HTTP POST (sometimes referred to as rfc1867-style posts). Append one section at
17 a time until you've added all the sections you want included and then you pass
18 the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP.
19 \fIlastitem\fP is set after each call and on repeated invokes it should be
20 left as set to allow repeated invokes to find the end of the list faster.
22 After the \fIlastitem\fP pointer follow the real arguments.
24 The pointers \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to
25 NULL in the first call to this function. All list-data will be allocated by
26 the function itself. You must call \fIcurl_formfree\fP after the form post has
27 been done to free the resources again.
29 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
30 You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual.
32 First, there are some basics you need to understand about multipart/formdata
33 posts. Each part consists of at least a NAME and a CONTENTS part. If the part
34 is made for file upload, there are also a stored CONTENT-TYPE and a
35 FILENAME. Below here, we'll discuss on what options you use to set these
36 properties in the parts you want to add to your post.
39 followed by string is used to set the name of this part. libcurl copies the
40 given data, so your application doesn't need to keep it around after this
41 function call. If the name isn't zero terminated properly, or if you'd like it
42 to contain zero bytes, you need to set the length of the name with
43 \fBCURLFORM_NAMELENGTH\fP.
46 followed by a string is used for the name of this part. libcurl will use the
47 pointer and refer to the data in your application, you must make sure it
48 remains until curl no longer needs it. If the name isn't zero terminated
49 properly, or if you'd like it to contain zero bytes, you need to set the
50 length of the name with \fBCURLFORM_NAMELENGTH\fP.
52 .B CURLFORM_COPYCONTENTS
53 followed by a string is used for the contents of this part, the actual data to
54 send away. libcurl copies the given data, so your application doesn't need to
55 keep it around after this function call. If the data isn't zero terminated
56 properly, or if you'd like it to contain zero bytes, you need to set the
57 length of the name with \fBCURLFORM_CONTENTSLENGTH\fP.
59 .B CURLFORM_PTRCONTENTS
60 followed by a string is used for the contents of this part, the actual data to
61 send away. libcurl will use the pointer and refer to the data in your
62 application, you must make sure it remains until curl no longer needs it. If
63 the data isn't zero terminated properly, or if you'd like it to contain zero
64 bytes, you need to set the length of the name with
65 \fBCURLFORM_CONTENTSLENGTH\fP.
67 .B CURLFORM_FILECONTENT
68 followed by a file name, makes that file read and the contents will be used in
72 followed by a file name, makes this part a file upload part. It sets the file
73 name field to the actual file name used here, it gets the contents of the file
74 and passes as data and sets the content-type if the given file match one of
75 the new internally known file extension. For \fBCURLFORM_FILE\fP the user may
76 send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP
77 arguments each followed by the filename (and each CURLFORM_FILE is allowed to
78 have a CURLFORM_CONTENTTYPE).
80 .B CURLFORM_CONTENTTYPE
81 followed by a pointer to a string with a content-type will make curl use this
82 given content-type for this file upload part, possibly instead of an
83 internally chosen one.
86 followed by a pointer to a string to a name, will make libcurl use the given
87 name in the file upload part, instead of the actual file name given to
91 followed by a string, tells libcurl that a buffer is to be used to upload data
92 instead of using a file. The given string is used as the value of the file
93 name field in the content header.
96 followed by a pointer to a data area, tells libcurl the address of the buffer
97 containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The
98 buffer containing this data must not be freed until after
99 \fIcurl_easy_cleanup(3)\fP is called.
101 .B CURLFORM_BUFFERLENGTH
102 followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area,
103 tells libcurl the length of the buffer to upload.
106 Another possibility to send options to curl_formadd() is the
107 \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
108 its value. Each curl_forms structure element has a CURLformoption and a char
109 pointer. The final element in the array must be a CURLFORM_END. All available
110 options can be used in an array, except the CURLFORM_ARRAY option itself! The
111 last argument in such an array must always be \fBCURLFORM_END\fP.
113 .B CURLFORM_CONTENTHEADER
114 specifies extra headers for the form POST section. This takes a curl_slist
115 prepared in the usual way using \fBcurl_slist_append\fP and appends the list
116 of headers to those libcurl automatically generates. The list must exist while
117 the POST occurs, if you free it before the post completes you may experience
120 When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
121 the \fICURLOPT_HTTPPOST\fP option), you must not free the list until after
122 you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
126 0 means everything was ok, non-zero means an error occurred as
132 struct HttpPost* post = NULL;
133 struct HttpPost* last = NULL;
134 char namebuffer[] = "name buffer";
135 long namelength = strlen(namebuffer);
136 char buffer[] = "test buffer";
137 char htmlbuffer[] = "<HTML>test buffer</HTML>";
138 long htmlbufferlength = strlen(htmlbuffer);
139 struct curl_forms forms[3];
140 char file1[] = "my-face.jpg";
141 char file2[] = "your-face.jpg";
142 /* add null character into htmlbuffer, to demonstrate that
143 transfers of buffers containing null characters actually work
145 htmlbuffer[8] = '\\0';
147 /* Add simple name/content section */
148 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
149 CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
151 /* Add simple name/content/contenttype section */
152 curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
153 CURLFORM_COPYCONTENTS, "<HTML></HTML>",
154 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
156 /* Add name/ptrcontent section */
157 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
158 CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
160 /* Add ptrname/ptrcontent section */
161 curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
162 CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
163 namelength, CURLFORM_END);
165 /* Add name/ptrcontent/contenttype section */
166 curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
167 CURLFORM_PTRCONTENTS, htmlbuffer,
168 CURLFORM_CONTENTSLENGTH, htmlbufferlength,
169 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
171 /* Add simple file section */
172 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
173 CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
175 /* Add file/contenttype section */
176 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
177 CURLFORM_FILE, "my-face.jpg",
178 CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
180 /* Add two file section */
181 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
182 CURLFORM_FILE, "my-face.jpg",
183 CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
185 /* Add two file section using CURLFORM_ARRAY */
186 forms[0].option = CURLFORM_FILE;
187 forms[0].value = file1;
188 forms[1].option = CURLFORM_FILE;
189 forms[1].value = file2;
190 forms[2].option = CURLFORM_END;
192 /* Add a buffer to upload */
193 curl_formadd(&post, &last,
194 CURLFORM_COPYNAME, "name",
195 CURLFORM_BUFFER, "data",
196 CURLFORM_BUFFERPTR, record,
197 CURLFORM_BUFFERLENGTH, record_length,
200 /* no option needed for the end marker */
201 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
202 CURLFORM_ARRAY, forms, CURLFORM_END);
203 /* Add the content of a file as a normal post text value */
204 curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
205 CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
206 /* Set the form info */
207 curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
210 .BR curl_easy_setopt "(3), "
211 .BR curl_formfree "(3)"