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