diff options
Diffstat (limited to 'docs/libcurl/curl_formadd.3')
-rw-r--r-- | docs/libcurl/curl_formadd.3 | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 new file mode 100644 index 000000000..e0e157279 --- /dev/null +++ b/docs/libcurl/curl_formadd.3 @@ -0,0 +1,165 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_formadd 3 "1 Match 2002" "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 + + struct HttpPost* post = NULL; + struct 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! + |