1 .\" You can view this file with:
3 .\" $Id: curl_formadd.3,v 1.8 2004/02/27 15:34:06 bagder Exp $
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 refered 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 First, there are some basics you need to understand about multipart/formdata
30 posts. Each part consists of at least a NAME and a CONTENTS part. If the part
31 is made for file upload, there are also a stored CONTENT-TYPE and a
32 FILENAME. Below here, we'll discuss on what options you use to set these
33 properties in the parts you want to add to your post.
36 followed by string is used to set the name of this part. libcurl copies the
37 given data, so your application doesn't need to keep it around after this
38 function call. If the name isn't zero terminated properly, or if you'd like it
39 to contain zero bytes, you need to set the length of the name with
40 \fBCURLFORM_NAMELENGTH\fP.
43 followed by a string is used for the name of this part. libcurl will use the
44 pointer and refer to the data in your application, you must make sure it
45 remains until curl no longer needs it. If the name isn't zero terminated
46 properly, or if you'd like it to contain zero bytes, you need to set the
47 length of the name with \fBCURLFORM_NAMELENGTH\fP.
49 .B CURLFORM_COPYCONTENTS
50 followed by a string is used for the contents of this part, the actual data to
51 send away. libcurl copies the given data, so your application doesn't need to
52 keep it around after this function call. If the data isn't zero terminated
53 properly, or if you'd like it to contain zero bytes, you need to set the
54 length of the name with \fBCURLFORM_CONTENTSLENGTH\fP.
56 .B CURLFORM_PTRCONTENTS
57 followed by a string is used for the contents of this part, the actual data to
58 send away. libcurl will use the pointer and refer to the data in your
59 application, you must make sure it remains until curl no longer needs it. If
60 the data isn't zero terminated properly, or if you'd like it to contain zero
61 bytes, you need to set the length of the name with
62 \fBCURLFORM_CONTENTSLENGTH\fP.
64 .B CURLFORM_FILECONTENT
65 followed by a file name, makes that file read and the contents will be used in
69 followed by a file name, makes this part a file upload part. It sets the file
70 name field to the actual file name used here, it gets the contents of the file
71 and passes as data and sets the content-type if the given file match one of
72 the new internally known file extension. For \fBCURLFORM_FILE\fP the user may
73 send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP
74 arguments each followed by the filename (and each CURLFORM_FILE is allowed to
75 have a CURLFORM_CONTENTTYPE).
77 .B CURLFORM_CONTENTTYPE
78 followed by a pointer to a string with a content-type will make curl use this
79 given content-type for this file upload part, possibly instead of an
80 internally chosen one.
83 followed by a pointer to a string to a name, will make libcurl use the given
84 name in the file upload part, intead of the actual file name given to
88 followed by a string, tells libcurl that a buffer is to be used to upload data
89 instead of using a file. The given string is used as the value of the file
90 name field in the content header.
93 followed by a pointer to a data area, tells libcurl the address of the buffer
94 containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The
95 buffer containing this data must not be freed until after
96 \fIcurl_easy_cleanup(3)\fP is called.
98 .B CURLFORM_BUFFERLENGTH
99 followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area,
100 tells libcurl the length of the buffer to upload.
103 Another possibility to send options to curl_formadd() is the
104 \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
105 its value. Each curl_forms structure element has a CURLformoption and a char
106 pointer. The final element in the array must be a CURLFORM_END. All available
107 options can be used in an array, except the CURLFORM_ARRAY option itself! The
108 last argument in such an array must always be \fBCURLFORM_END\fP.
110 .B CURLFORM_CONTENTHEADER
111 specifies extra headers for the form POST section. This takes a curl_slist
112 prepared in the usual way using \fBcurl_slist_append\fP and appends the list
113 of headers to those libcurl automatically generates. The list must exist while
114 the POST occurs, if you free it before the post completes you may experience
117 When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
118 the \fICURLOPT_HTTPPOST\fP option), you must not free the list until after
119 you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
123 0 means everything was ok, non-zero means an error occurred as
129 struct HttpPost* post = NULL;
130 struct HttpPost* last = NULL;
131 char namebuffer[] = "name buffer";
132 long namelength = strlen(namebuffer);
133 char buffer[] = "test buffer";
134 char htmlbuffer[] = "<HTML>test buffer</HTML>";
135 long htmlbufferlength = strlen(htmlbuffer);
136 struct curl_forms forms[3];
137 char file1[] = "my-face.jpg";
138 char file2[] = "your-face.jpg";
139 /* add null character into htmlbuffer, to demonstrate that
140 transfers of buffers containing null characters actually work
142 htmlbuffer[8] = '\\0';
144 /* Add simple name/content section */
145 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
146 CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
148 /* Add simple name/content/contenttype section */
149 curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
150 CURLFORM_COPYCONTENTS, "<HTML></HTML>",
151 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
153 /* Add name/ptrcontent section */
154 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
155 CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
157 /* Add ptrname/ptrcontent section */
158 curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
159 CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
160 namelength, CURLFORM_END);
162 /* Add name/ptrcontent/contenttype section */
163 curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
164 CURLFORM_PTRCONTENTS, htmlbuffer,
165 CURLFORM_CONTENTSLENGTH, htmlbufferlength,
166 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
168 /* Add simple file section */
169 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
170 CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
172 /* Add file/contenttype section */
173 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
174 CURLFORM_FILE, "my-face.jpg",
175 CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
177 /* Add two file section */
178 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
179 CURLFORM_FILE, "my-face.jpg",
180 CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
182 /* Add two file section using CURLFORM_ARRAY */
183 forms[0].option = CURLFORM_FILE;
184 forms[0].value = file1;
185 forms[1].option = CURLFORM_FILE;
186 forms[1].value = file2;
187 forms[2].option = CURLFORM_END;
189 /* Add a buffer to upload */
190 curl_formadd(&post, &last,
191 CURLFORM_COPYNAME, "name",
192 CURLFORM_BUFFER, "data",
193 CURLFORM_BUFFERPTR, record,
194 CURLFORM_BUFFERLENGTH, record_length,
197 /* no option needed for the end marker */
198 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
199 CURLFORM_ARRAY, forms, CURLFORM_END);
200 /* Add the content of a file as a normal post text value */
201 curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
202 CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
203 /* Set the form info */
204 curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
207 .BR curl_easy_setopt "(3), "
208 .BR curl_formparse "(3) [deprecated], "
209 .BR curl_formfree "(3)"