curl_formadd.md (12085B)
1 --- 2 c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 SPDX-License-Identifier: curl 4 Title: curl_formadd 5 Section: 3 6 Source: libcurl 7 See-also: 8 - curl_easy_setopt (3) 9 - curl_formfree (3) 10 - curl_mime_init (3) 11 Protocol: 12 - HTTP 13 Added-in: 7.1 14 --- 15 16 # NAME 17 18 curl_formadd - add a section to a multipart form POST 19 20 # SYNOPSIS 21 22 ~~~c 23 #include <curl/curl.h> 24 25 CURLFORMcode 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 33 curl_formadd() is used to append sections when building a multipart form 34 post. Append one section at a time until you have added all the sections you 35 want included and then you pass the *firstitem* pointer as parameter to 36 CURLOPT_HTTPPOST(3). *lastitem* is set after each curl_formadd(3) call and 37 on repeated invokes it should be left as set to allow repeated invokes to find 38 the end of the list faster. 39 40 After the *lastitem* pointer follow the real arguments. 41 42 The pointers *firstitem* and *lastitem* should both be pointing to 43 NULL in the first call to this function. All list-data is allocated by the 44 function itself. You must call curl_formfree(3) on the *firstitem* 45 after the form post has been done to free the resources. 46 47 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. 48 You can disable this header with CURLOPT_HTTPHEADER(3) as usual. 49 50 First, there are some basics you need to understand about multipart form 51 posts. Each part consists of at least a NAME and a CONTENTS part. If the part 52 is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME. 53 Below, we discuss what options you use to set these properties in the parts 54 you want to add to your post. 55 56 The options listed first are for making normal parts. The options from 57 *CURLFORM_FILE* through *CURLFORM_BUFFERLENGTH* are for file upload 58 parts. 59 60 # OPTIONS 61 62 ## CURLFORM_COPYNAME 63 64 followed by a string which provides the *name* of this part. libcurl 65 copies the string so your application does not need to keep it around after 66 this function call. If the name is not null-terminated, you must set its 67 length with **CURLFORM_NAMELENGTH**. The *name* is not allowed to 68 contain zero-valued bytes. The copied data is freed by curl_formfree(3). 69 70 ## CURLFORM_PTRNAME 71 72 followed by a string which provides the *name* of this part. libcurl uses the 73 pointer and refer to the data in your application, so you must make sure it 74 remains until curl no longer needs it. If the name is not null-terminated, you 75 must set its length with **CURLFORM_NAMELENGTH**. The *name* is not allowed to 76 contain zero-valued bytes. 77 78 ## CURLFORM_COPYCONTENTS 79 80 followed by a pointer to the contents of this part, the actual data to send 81 away. libcurl copies the provided data, so your application does not need to 82 keep it around after this function call. If the data is not null-terminated, 83 or if you would like it to contain zero bytes, you must set the length of the 84 name with **CURLFORM_CONTENTSLENGTH**. The copied data is freed by 85 curl_formfree(3). 86 87 ## CURLFORM_PTRCONTENTS 88 89 followed by a pointer to the contents of this part, the actual data to send 90 away. libcurl uses the pointer and refer to the data in your application, so 91 you must make sure it remains until curl no longer needs it. If the data is 92 not null-terminated, or if you would like it to contain zero bytes, you must 93 set its length with **CURLFORM_CONTENTSLENGTH**. 94 95 ## CURLFORM_CONTENTLEN 96 97 followed by a curl_off_t value giving the length of the contents. Note that 98 for *CURLFORM_STREAM* contents, this option is mandatory. 99 100 If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents 101 to figure out the size. If you really want to send a zero byte content then 102 you 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 110 followed by a long giving the length of the contents. Note that for 111 *CURLFORM_STREAM* contents, this option is mandatory. 112 113 If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents 114 to figure out the size. If you really want to send a zero byte content then 115 you must make sure strlen() on the data pointer returns zero. 116 117 ## CURLFORM_FILECONTENT 118 119 followed by a filename, causes that file to be read and its contents used 120 as data in this part. This part does *not* automatically become a file 121 upload part simply because its data was read from a file. 122 123 The specified file needs to kept around until the associated transfer is done. 124 125 ## CURLFORM_FILE 126 127 followed 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 129 contents of the file and passes them as data and sets the content-type if the 130 given 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 132 providing multiple **CURLFORM_FILE** arguments each followed by the filename 133 (and each *CURLFORM_FILE* is allowed to have a 134 *CURLFORM_CONTENTTYPE*). 135 136 The given upload file has to exist in its full in the file system already when 137 the upload starts, as libcurl needs to read the correct file size beforehand. 138 139 The specified file needs to kept around until the associated transfer is done. 140 141 ## CURLFORM_CONTENTTYPE 142 143 is used in combination with *CURLFORM_FILE*. Followed by a pointer to a 144 string which provides the content-type for this part, possibly instead of an 145 internally chosen one. 146 147 ## CURLFORM_FILENAME 148 149 is used in combination with *CURLFORM_FILE*. Followed by a pointer to a 150 string, it tells libcurl to use the given string as the *filename* in the file 151 upload part instead of the actual filename. 152 153 ## CURLFORM_BUFFER 154 155 is used for custom file upload parts without use of *CURLFORM_FILE*. It 156 tells libcurl that the file contents are already present in a buffer. The 157 parameter is a string which provides the *filename* field in the content 158 header. 159 160 ## CURLFORM_BUFFERPTR 161 162 is used in combination with *CURLFORM_BUFFER*. The parameter is a pointer 163 to the buffer to be uploaded. This buffer must not be freed until after 164 curl_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 169 is used in combination with *CURLFORM_BUFFER*. The parameter is a 170 long which gives the length of the buffer. 171 172 ## CURLFORM_STREAM 173 174 Tells libcurl to use the CURLOPT_READFUNCTION(3) callback to get 175 data. The parameter you pass to *CURLFORM_STREAM* is the pointer passed on 176 to the read callback's fourth argument. If you want the part to look like a 177 file upload one, set the *CURLFORM_FILENAME* parameter as well. Note that 178 when using *CURLFORM_STREAM*, *CURLFORM_CONTENTSLENGTH* must also be 179 set with the total expected length of the part unless the formpost is sent 180 chunked encoded. (Option added in libcurl 7.18.2) 181 182 ## CURLFORM_ARRAY 183 184 Another possibility to send options to curl_formadd() is the 185 **CURLFORM_ARRAY** option, that passes a struct curl_forms array pointer as 186 its value. Each curl_forms structure element has a *CURLformoption* and a 187 char pointer. The final element in the array must be a CURLFORM_END. All 188 available options can be used in an array, except the CURLFORM_ARRAY option 189 itself. The last argument in such an array must always be **CURLFORM_END**. 190 191 ## CURLFORM_CONTENTHEADER 192 193 specifies extra headers for the form POST section. This takes a curl_slist 194 prepared in the usual way using **curl_slist_append** and appends the list 195 of headers to those libcurl automatically generates. The list must exist while 196 the POST occurs, if you free it before the post completes you may experience 197 problems. 198 199 When you have passed the *struct curl_httppost* pointer to 200 curl_easy_setopt(3) (using the CURLOPT_HTTPPOST(3) option), you 201 must not free the list until after you have called curl_easy_cleanup(3) 202 for the curl handle. 203 204 See example below. 205 206 # %PROTOCOLS% 207 208 # EXAMPLE 209 210 ~~~c 211 #include <string.h> /* for strlen */ 212 213 static const char record[]="data in a buffer"; 214 215 int 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 307 Deprecated in 7.56.0. Before this release, field names were allowed to contain 308 zero-valued bytes. The pseudo-filename "-" to read stdin is discouraged 309 although still supported, but data is not read before being actually sent: the 310 effective data size can then not be automatically determined, resulting in a 311 chunked encoding transfer. Backslashes and double quotes in field and 312 filenames are now escaped before transmission. 313 314 # %AVAILABILITY% 315 316 # RETURN VALUE 317 318 0 means everything was OK, non-zero means an error occurred corresponding to a 319 `CURL_FORMADD_*` constant defined in *\<curl/curl.h\>*.