1--- 2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al. 3SPDX-License-Identifier: curl 4Title: curl_formadd 5Section: 3 6Source: libcurl 7See-also: 8 - curl_easy_setopt (3) 9 - curl_formfree (3) 10 - curl_mime_init (3) 11--- 12 13# NAME 14 15curl_formadd - add a section to a multipart form POST 16 17# SYNOPSIS 18 19~~~c 20#include <curl/curl.h> 21 22CURLFORMcode curl_formadd(struct curl_httppost **firstitem, 23 struct curl_httppost **lastitem, ...); 24~~~ 25 26# DESCRIPTION 27 28**This function is deprecated.** Use curl_mime_init(3) instead. 29 30curl_formadd() is used to append sections when building a multipart form 31post. Append one section at a time until you have added all the sections you 32want included and then you pass the *firstitem* pointer as parameter to 33CURLOPT_HTTPPOST(3). *lastitem* is set after each curl_formadd(3) call and 34on repeated invokes it should be left as set to allow repeated invokes to find 35the end of the list faster. 36 37After the *lastitem* pointer follow the real arguments. 38 39The pointers *firstitem* and *lastitem* should both be pointing to 40NULL in the first call to this function. All list-data is allocated by the 41function itself. You must call curl_formfree(3) on the *firstitem* 42after the form post has been done to free the resources. 43 44Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. 45You can disable this header with CURLOPT_HTTPHEADER(3) as usual. 46 47First, there are some basics you need to understand about multipart form 48posts. Each part consists of at least a NAME and a CONTENTS part. If the part 49is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME. 50Below, we discuss what options you use to set these properties in the parts 51you want to add to your post. 52 53The options listed first are for making normal parts. The options from 54*CURLFORM_FILE* through *CURLFORM_BUFFERLENGTH* are for file upload 55parts. 56 57# OPTIONS 58 59## CURLFORM_COPYNAME 60 61followed by a string which provides the *name* of this part. libcurl 62copies the string so your application does not need to keep it around after 63this function call. If the name is not null-terminated, you must set its 64length with **CURLFORM_NAMELENGTH**. The *name* is not allowed to 65contain zero-valued bytes. The copied data is freed by curl_formfree(3). 66 67## CURLFORM_PTRNAME 68 69followed by a string which provides the *name* of this part. libcurl uses the 70pointer and refer to the data in your application, so you must make sure it 71remains until curl no longer needs it. If the name is not null-terminated, you 72must set its length with **CURLFORM_NAMELENGTH**. The *name* is not allowed to 73contain zero-valued bytes. 74 75## CURLFORM_COPYCONTENTS 76 77followed by a pointer to the contents of this part, the actual data to send 78away. libcurl copies the provided data, so your application does not need to 79keep it around after this function call. If the data is not null terminated, 80or if you would like it to contain zero bytes, you must set the length of the 81name with **CURLFORM_CONTENTSLENGTH**. The copied data is freed by 82curl_formfree(3). 83 84## CURLFORM_PTRCONTENTS 85 86followed by a pointer to the contents of this part, the actual data to send 87away. libcurl uses the pointer and refer to the data in your application, so 88you must make sure it remains until curl no longer needs it. If the data is 89not null-terminated, or if you would like it to contain zero bytes, you must 90set its length with **CURLFORM_CONTENTSLENGTH**. 91 92## CURLFORM_CONTENTLEN 93 94followed by a curl_off_t value giving the length of the contents. Note that 95for *CURLFORM_STREAM* contents, this option is mandatory. 96 97If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents 98to figure out the size. If you really want to send a zero byte content then 99you must make sure strlen() on the data pointer returns zero. 100 101(Option added in 7.46.0) 102 103## CURLFORM_CONTENTSLENGTH 104 105(This option is deprecated. Use *CURLFORM_CONTENTLEN* instead!) 106 107followed by a long giving the length of the contents. Note that for 108*CURLFORM_STREAM* contents, this option is mandatory. 109 110If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents 111to figure out the size. If you really want to send a zero byte content then 112you must make sure strlen() on the data pointer returns zero. 113 114## CURLFORM_FILECONTENT 115 116followed by a filename, causes that file to be read and its contents used 117as data in this part. This part does *not* automatically become a file 118upload part simply because its data was read from a file. 119 120The specified file needs to kept around until the associated transfer is done. 121 122## CURLFORM_FILE 123 124followed by a filename, makes this part a file upload part. It sets the 125*filename* field to the basename of the provided filename, it reads the 126contents of the file and passes them as data and sets the content-type if the 127given file match one of the internally known file extensions. For 128**CURLFORM_FILE** the user may send one or more files in one part by 129providing multiple **CURLFORM_FILE** arguments each followed by the filename 130(and each *CURLFORM_FILE* is allowed to have a 131*CURLFORM_CONTENTTYPE*). 132 133The given upload file has to exist in its full in the file system already when 134the upload starts, as libcurl needs to read the correct file size beforehand. 135 136The specified file needs to kept around until the associated transfer is done. 137 138## CURLFORM_CONTENTTYPE 139 140is used in combination with *CURLFORM_FILE*. Followed by a pointer to a 141string which provides the content-type for this part, possibly instead of an 142internally chosen one. 143 144## CURLFORM_FILENAME 145 146is used in combination with *CURLFORM_FILE*. Followed by a pointer to a 147string, it tells libcurl to use the given string as the *filename* in the file 148upload part instead of the actual filename. 149 150## CURLFORM_BUFFER 151 152is used for custom file upload parts without use of *CURLFORM_FILE*. It 153tells libcurl that the file contents are already present in a buffer. The 154parameter is a string which provides the *filename* field in the content 155header. 156 157## CURLFORM_BUFFERPTR 158 159is used in combination with *CURLFORM_BUFFER*. The parameter is a pointer 160to the buffer to be uploaded. This buffer must not be freed until after 161curl_easy_cleanup(3) is called. You must also use 162*CURLFORM_BUFFERLENGTH* to set the number of bytes in the buffer. 163 164## CURLFORM_BUFFERLENGTH 165 166is used in combination with *CURLFORM_BUFFER*. The parameter is a 167long which gives the length of the buffer. 168 169## CURLFORM_STREAM 170 171Tells libcurl to use the CURLOPT_READFUNCTION(3) callback to get 172data. The parameter you pass to *CURLFORM_STREAM* is the pointer passed on 173to the read callback's fourth argument. If you want the part to look like a 174file upload one, set the *CURLFORM_FILENAME* parameter as well. Note that 175when using *CURLFORM_STREAM*, *CURLFORM_CONTENTSLENGTH* must also be 176set with the total expected length of the part unless the formpost is sent 177chunked encoded. (Option added in libcurl 7.18.2) 178 179## CURLFORM_ARRAY 180 181Another possibility to send options to curl_formadd() is the 182**CURLFORM_ARRAY** option, that passes a struct curl_forms array pointer as 183its value. Each curl_forms structure element has a *CURLformoption* and a 184char pointer. The final element in the array must be a CURLFORM_END. All 185available options can be used in an array, except the CURLFORM_ARRAY option 186itself. The last argument in such an array must always be **CURLFORM_END**. 187 188## CURLFORM_CONTENTHEADER 189 190specifies extra headers for the form POST section. This takes a curl_slist 191prepared in the usual way using **curl_slist_append** and appends the list 192of headers to those libcurl automatically generates. The list must exist while 193the POST occurs, if you free it before the post completes you may experience 194problems. 195 196When you have passed the *struct curl_httppost* pointer to 197curl_easy_setopt(3) (using the CURLOPT_HTTPPOST(3) option), you 198must not free the list until after you have called curl_easy_cleanup(3) 199for the curl handle. 200 201See example below. 202 203# EXAMPLE 204 205~~~c 206#include <string.h> /* for strlen */ 207 208static const char record[]="data in a buffer"; 209 210int main(void) 211{ 212 CURL *curl = curl_easy_init(); 213 if(curl) { 214 struct curl_httppost *post = NULL; 215 struct curl_httppost *last = NULL; 216 char namebuffer[] = "name buffer"; 217 long namelength = strlen(namebuffer); 218 char buffer[] = "test buffer"; 219 char htmlbuffer[] = "<HTML>test buffer</HTML>"; 220 long htmlbufferlength = strlen(htmlbuffer); 221 struct curl_forms forms[3]; 222 char file1[] = "my-face.jpg"; 223 char file2[] = "your-face.jpg"; 224 /* add null character into htmlbuffer, to demonstrate that 225 transfers of buffers containing null characters actually work 226 */ 227 htmlbuffer[8] = '\0'; 228 229 /* Add simple name/content section */ 230 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", 231 CURLFORM_COPYCONTENTS, "content", CURLFORM_END); 232 233 /* Add simple name/content/contenttype section */ 234 curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode", 235 CURLFORM_COPYCONTENTS, "<HTML></HTML>", 236 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); 237 238 /* Add name/ptrcontent section */ 239 curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent", 240 CURLFORM_PTRCONTENTS, buffer, CURLFORM_END); 241 242 /* Add ptrname/ptrcontent section */ 243 curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer, 244 CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH, 245 namelength, CURLFORM_END); 246 247 /* Add name/ptrcontent/contenttype section */ 248 curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole", 249 CURLFORM_PTRCONTENTS, htmlbuffer, 250 CURLFORM_CONTENTSLENGTH, htmlbufferlength, 251 CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); 252 253 /* Add simple file section */ 254 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture", 255 CURLFORM_FILE, "my-face.jpg", CURLFORM_END); 256 257 /* Add file/contenttype section */ 258 curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture", 259 CURLFORM_FILE, "my-face.jpg", 260 CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END); 261 262 /* Add two file section */ 263 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", 264 CURLFORM_FILE, "my-face.jpg", 265 CURLFORM_FILE, "your-face.jpg", CURLFORM_END); 266 267 /* Add two file section using CURLFORM_ARRAY */ 268 forms[0].option = CURLFORM_FILE; 269 forms[0].value = file1; 270 forms[1].option = CURLFORM_FILE; 271 forms[1].value = file2; 272 forms[2].option = CURLFORM_END; 273 274 /* Add a buffer to upload */ 275 curl_formadd(&post, &last, 276 CURLFORM_COPYNAME, "name", 277 CURLFORM_BUFFER, "data", 278 CURLFORM_BUFFERPTR, record, 279 CURLFORM_BUFFERLENGTH, sizeof(record), 280 CURLFORM_END); 281 282 /* no option needed for the end marker */ 283 curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", 284 CURLFORM_ARRAY, forms, CURLFORM_END); 285 /* Add the content of a file as a normal post text value */ 286 curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent", 287 CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END); 288 /* Set the form info */ 289 curl_easy_setopt(curl, CURLOPT_HTTPPOST, post); 290 291 curl_easy_perform(curl); 292 293 curl_easy_cleanup(curl); 294 295 curl_formfree(post); 296 } 297} 298~~~ 299 300# AVAILABILITY 301 302Deprecated in 7.56.0. Before this release, field names were allowed to 303contain zero-valued bytes. The pseudo-filename "-" to read stdin is 304discouraged although still supported, but data is not read before being 305actually sent: the effective data size can then not be automatically 306determined, resulting in a chunked encoding transfer. Backslashes and 307double quotes in field and file names are now escaped before transmission. 308 309# RETURN VALUE 310 3110 means everything was OK, non-zero means an error occurred corresponding 312to a CURL_FORMADD_* constant defined in 313*<curl/curl.h>* 314
