| .\" ************************************************************************** |
| .\" * _ _ ____ _ |
| .\" * Project ___| | | | _ \| | |
| .\" * / __| | | | |_) | | |
| .\" * | (__| |_| | _ <| |___ |
| .\" * \___|\___/|_| \_\_____| |
| .\" * |
| .\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al. |
| .\" * |
| .\" * This software is licensed as described in the file COPYING, which |
| .\" * you should have received as part of this distribution. The terms |
| .\" * are also available at http://curl.haxx.se/docs/copyright.html. |
| .\" * |
| .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| .\" * copies of the Software, and permit persons to whom the Software is |
| .\" * furnished to do so, under the terms of the COPYING file. |
| .\" * |
| .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| .\" * KIND, either express or implied. |
| .\" * |
| .\" ************************************************************************** |
| .TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual" |
| .SH NAME |
| curl_formadd - add a section to a multipart/formdata HTTP POST |
| .SH SYNOPSIS |
| .B #include <curl/curl.h> |
| .sp |
| .BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem, |
| .BI "struct curl_httppost ** " lastitem, " ...);" |
| .ad |
| .SH DESCRIPTION |
| curl_formadd() is used to append sections when building a multipart/formdata |
| HTTP POST (sometimes referred to as RFC2388-style posts). Append one section |
| at a time until you've added all the sections you want included and then you |
| pass the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP. |
| \fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated |
| invokes it should be left as set to allow repeated invokes to find the end of |
| the list faster. |
| |
| After the \fIlastitem\fP pointer follow the real arguments. |
| |
| The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to |
| NULL in the first call to this function. All list-data will be allocated by |
| the function itself. You must call \fIcurl_formfree(3)\fP on the |
| \fIfirstitem\P after the form post has been done to free the resources. |
| |
| Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. |
| You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. |
| |
| First, there are some basics you need to understand about multipart/formdata |
| posts. Each part consists of at least a NAME and a CONTENTS part. If the part |
| is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME. |
| Below, we'll discuss what options you use to set these properties in the |
| parts you want to add to your post. |
| |
| The options listed first are for making normal parts. The options from |
| \fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload |
| parts. |
| .SH OPTIONS |
| .IP CURLFORM_COPYNAME |
| followed by a string which provides the \fIname\fP of this part. libcurl |
| copies the string so your application doesn't need to keep it around after |
| this function call. If the name isn't NUL-terminated, or if you'd |
| like it to contain zero bytes, you must set its length with |
| \fBCURLFORM_NAMELENGTH\fP. The copied data will be freed by |
| \fIcurl_formfree(3)\fP. |
| .IP CURLFORM_PTRNAME |
| followed by a string which provides the \fIname\fP of this part. libcurl |
| will use the pointer and refer to the data in your application, so you |
| must make sure it remains until curl no longer needs it. If the name |
| isn't NUL-terminated, or if you'd like it to contain zero |
| bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. |
| .IP CURLFORM_COPYCONTENTS |
| followed by a pointer to the contents of this part, the actual data |
| to send away. libcurl copies the provided data, so your application doesn't |
| need to keep it around after this function call. If the data isn't null |
| terminated, or if you'd like it to contain zero bytes, you must |
| set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied |
| data will be freed by \fIcurl_formfree(3)\fP. |
| .IP CURLFORM_PTRCONTENTS |
| followed by a pointer to the contents of this part, the actual data |
| to send away. libcurl will use the pointer and refer to the data in your |
| application, so you must make sure it remains until curl no longer needs it. |
| If the data isn't NUL-terminated, or if you'd like it to contain zero bytes, |
| you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. |
| .IP CURLFORM_CONTENTSLENGTH |
| followed by a long giving the length of the contents. Note that for |
| \fICURLFORM_STREAM\fP contents, this option is mandatory. |
| .IP CURLFORM_FILECONTENT |
| followed by a filename, causes that file to be read and its contents used |
| as data in this part. This part does \fInot\fP automatically become a file |
| upload part simply because its data was read from a file. |
| .IP CURLFORM_FILE |
| followed by a filename, makes this part a file upload part. It sets the |
| \fIfilename\fP field to the basename of the provided filename, it reads the |
| contents of the file and passes them as data and sets the content-type if the |
| given file match one of the internally known file extensions. For |
| \fBCURLFORM_FILE\fP the user may send one or more files in one part by |
| providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename |
| (and each \fICURLFORM_FILE\fP is allowed to have a |
| \fICURLFORM_CONTENTTYPE\fP). |
| .IP CURLFORM_CONTENTTYPE |
| is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a |
| string which provides the content-type for this part, possibly instead of an |
| internally chosen one. |
| .IP CURLFORM_FILENAME |
| is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a |
| string, it tells libcurl to use the given string as the \fIfilename\fP in the |
| file upload part instead of the actual file name. |
| .IP CURLFORM_BUFFER |
| is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It |
| tells libcurl that the file contents are already present in a buffer. The |
| parameter is a string which provides the \fIfilename\fP field in the content |
| header. |
| .IP CURLFORM_BUFFERPTR |
| is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer |
| to the buffer to be uploaded. This buffer must not be freed until after |
| \fIcurl_easy_cleanup(3)\fP is called. You must also use |
| \fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer. |
| .IP CURLFORM_BUFFERLENGTH |
| is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a |
| long which gives the length of the buffer. |
| .IP CURLFORM_STREAM |
| Tells libcurl to use the \fICURLOPT_READFUNCTION\fP callback to get data. The |
| parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on to the |
| read callback's fourth argument. If you want the part to look like a file |
| upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that when |
| using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be set |
| with the total expected length of the part. (Option added in libcurl 7.18.2) |
| .IP CURLFORM_ARRAY |
| Another possibility to send options to curl_formadd() is the |
| \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as |
| its value. Each curl_forms structure element has a CURLformoption and a char |
| pointer. The final element in the array must be a CURLFORM_END. All available |
| options can be used in an array, except the CURLFORM_ARRAY option itself! The |
| last argument in such an array must always be \fBCURLFORM_END\fP. |
| .IP CURLFORM_CONTENTHEADER |
| specifies extra headers for the form POST section. This takes a curl_slist |
| prepared in the usual way using \fBcurl_slist_append\fP and appends the list |
| of headers to those libcurl automatically generates. The list must exist while |
| the POST occurs, if you free it before the post completes you may experience |
| problems. |
| |
| When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using |
| the \fICURLOPT_HTTPPOST\fP option), you must not free the list until after |
| you've called \fIcurl_easy_cleanup(3)\fP for the curl handle. |
| |
| See example below. |
| .SH RETURN VALUE |
| 0 means everything was ok, non-zero means an error occurred corresponding |
| to a CURL_FORMADD_* constant defined in |
| .I <curl/curl.h> |
| .SH EXAMPLE |
| .nf |
| |
| struct curl_httppost* post = NULL; |
| struct curl_httppost* last = NULL; |
| char namebuffer[] = "name buffer"; |
| long namelength = strlen(namebuffer); |
| char buffer[] = "test buffer"; |
| char htmlbuffer[] = "<HTML>test buffer</HTML>"; |
| long htmlbufferlength = strlen(htmlbuffer); |
| struct curl_forms forms[3]; |
| char file1[] = "my-face.jpg"; |
| char file2[] = "your-face.jpg"; |
| /* add null character into htmlbuffer, to demonstrate that |
| transfers of buffers containing null characters actually work |
| */ |
| htmlbuffer[8] = '\\0'; |
| |
| /* Add simple name/content section */ |
| curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", |
| CURLFORM_COPYCONTENTS, "content", CURLFORM_END); |
| |
| /* Add simple name/content/contenttype section */ |
| curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode", |
| CURLFORM_COPYCONTENTS, "<HTML></HTML>", |
| CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); |
| |
| /* Add name/ptrcontent section */ |
| curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent", |
| CURLFORM_PTRCONTENTS, buffer, CURLFORM_END); |
| |
| /* Add ptrname/ptrcontent section */ |
| curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer, |
| CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH, |
| namelength, CURLFORM_END); |
| |
| /* Add name/ptrcontent/contenttype section */ |
| curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole", |
| CURLFORM_PTRCONTENTS, htmlbuffer, |
| CURLFORM_CONTENTSLENGTH, htmlbufferlength, |
| CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); |
| |
| /* Add simple file section */ |
| curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture", |
| CURLFORM_FILE, "my-face.jpg", CURLFORM_END); |
| |
| /* Add file/contenttype section */ |
| curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture", |
| CURLFORM_FILE, "my-face.jpg", |
| CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END); |
| |
| /* Add two file section */ |
| curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", |
| CURLFORM_FILE, "my-face.jpg", |
| CURLFORM_FILE, "your-face.jpg", CURLFORM_END); |
| |
| /* Add two file section using CURLFORM_ARRAY */ |
| forms[0].option = CURLFORM_FILE; |
| forms[0].value = file1; |
| forms[1].option = CURLFORM_FILE; |
| forms[1].value = file2; |
| forms[2].option = CURLFORM_END; |
| |
| /* Add a buffer to upload */ |
| curl_formadd(&post, &last, |
| CURLFORM_COPYNAME, "name", |
| CURLFORM_BUFFER, "data", |
| CURLFORM_BUFFERPTR, record, |
| CURLFORM_BUFFERLENGTH, record_length, |
| CURLFORM_END); |
| |
| /* no option needed for the end marker */ |
| curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", |
| CURLFORM_ARRAY, forms, CURLFORM_END); |
| /* Add the content of a file as a normal post text value */ |
| curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent", |
| CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END); |
| /* Set the form info */ |
| curl_easy_setopt(curl, CURLOPT_HTTPPOST, post); |
| |
| .SH "SEE ALSO" |
| .BR curl_easy_setopt "(3), " |
| .BR curl_formfree "(3)" |