diff options
Diffstat (limited to 'plugins/FTPFileYM/curl/docs/libcurl/curl_formadd.3')
-rw-r--r-- | plugins/FTPFileYM/curl/docs/libcurl/curl_formadd.3 | 235 |
1 files changed, 0 insertions, 235 deletions
diff --git a/plugins/FTPFileYM/curl/docs/libcurl/curl_formadd.3 b/plugins/FTPFileYM/curl/docs/libcurl/curl_formadd.3 deleted file mode 100644 index ce4df1e4bd..0000000000 --- a/plugins/FTPFileYM/curl/docs/libcurl/curl_formadd.3 +++ /dev/null @@ -1,235 +0,0 @@ -.\" ************************************************************************** -.\" * _ _ ____ _ -.\" * 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)" |