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