| .\" You can view this file with: |
| .\" nroff -man [file] |
| .\" $Id$ |
| .\" |
| .TH curl_formadd 3 "29 October 2001" "libcurl 7.9.1" "libcurl Manual" |
| .SH NAME |
| curl_formadd - add a section to a multipart/formdata HTTP POST |
| .SH SYNOPSIS |
| .B #include <curl/curl.h> |
| .sp |
| .BI "int curl_formadd(struct HttpPost ** " firstitem, |
| .BI "struct HttpPost ** " lastitem, " ...);" |
| .ad |
| .SH DESCRIPTION |
| curl_formadd() is used to append sections when building a multipart/formdata |
| HTTP POST (sometimes refered to as rfc1867-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 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. (If the following |
| description confuses you, jump directly to the examples): |
| |
| \fBCURLFORM_COPYNAME\fP or \fBCURLFORM_PTRNAME\fP followed by a string is used |
| for the name of the section. Optionally one may use \fBCURLFORM_NAMELENGTH\fP |
| to specify the length of the name (allowing null characters within the |
| name). All options that use the word COPY in their names copy the given |
| contents, while the ones with PTR in their names simply points to the (static) |
| data you must make sure remain until curl no longer needs it. |
| |
| The four options for providing values are: \fBCURLFORM_COPYCONTENTS\fP, |
| \fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, or \fBCURLFORM_FILECONTENT\fP |
| followed by a char or void pointer (allowed for PTRCONTENTS). |
| |
| \fBCURLFORM_FILECONTENT\fP does a normal post like \fBCURLFORM_COPYCONTENTS\fP |
| but the actual value is read from the filename given as a string. |
| |
| Other arguments may be \fBCURLFORM_CONTENTTYPE\fP if the user wishes to |
| specify one (for FILE if no type is given the library tries to provide the |
| correct one; for CONTENTS no Content-Type is sent in this case). |
| |
| For \fBCURLFORM_PTRCONTENTS\fP or \fBCURLFORM_COPYNAME\fP the user may also |
| add \fBCURLFORM_CONTENTSLENGTH\fP followed by the length as a long (if not |
| given the library will use strlen to determine the length). |
| |
| For \fBCURLFORM_FILE\fP the user may send multiple files in one section by |
| providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename |
| (and each FILE is allowed to have a CONTENTTYPE). |
| |
| Another possibility to send single or multiple files in one section is to use |
| \fBCURLFORM_ARRAY\fP that gets a struct curl_forms array pointer as its |
| value. Each structure element has a CURLformoption and a char pointer. For the |
| options only \fBCURLFORM_FILE\fP, \fBCURLFORM_CONTENTTYPE\fP, and |
| \fBCURLFORM_END\fP (that is used to determine the end of the array and thus |
| must be the option of the last and no other element of the curl_forms array) |
| are allowed. The effect of this parameter is the same as giving multiple |
| \fBCURLFORM_FILE\fP options possibly with \fBCURLFORM_CONTENTTYPE\fP after or |
| before each \fBCURLFORM_FILE\fP option. |
| |
| Should you need to specify extra headers for the form POST section, use |
| \fBCURLFORM_CONTENTHEADER\fP. This takes a curl_slist prepared in the usual way |
| using \fBcurl_slist_append\fP and appends the list of headers to those Curl |
| automatically generates for \fBCURLFORM_CONTENTTYPE\fP and the content |
| disposition. The list must exist while the POST occurs, if you free it before |
| the post completes you may experience problems. |
| |
| The last argument in such an array must always be \fBCURLFORM_END\fP. |
| |
| The pointers \fI*firstitem\fP and \fI*lastitem\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\fP after the form post has |
| been done to free the resources again. |
| |
| This function will copy all input data except the data pointed to by the |
| arguments after \fBCURLFORM_PTRNAME\fP and \fBCURLFORM_PTRCONTENTS\fP and keep |
| its own version of it allocated until you call \fIcurl_formfree\fP. When |
| you've passed the pointer to \fIcurl_easy_setopt\fP, you must not free the |
| list until after you've called \fIcurl_easy_cleanup\fP for the curl handle. If |
| you provide a pointer as an arguments after \fBCURLFORM_PTRNAME\fP or |
| \fBCURLFORM_PTRCONTENTS\fP you must ensure that the pointer stays valid until |
| you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP. |
| |
| See example below. |
| .SH RETURN VALUE |
| Returns non-zero if an error occurs. |
| .SH EXAMPLE |
| .nf |
| |
| HttpPost* post = NULL; |
| 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; |
| |
| /* 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_formparse "(3) [deprecated], " |
| .BR curl_formfree "(3)" |
| .SH BUGS |
| Surely there are some, you tell me! |
| |