summaryrefslogtreecommitdiff
path: root/plugins/FTPFileYM/curl/docs/libcurl/curl_formadd.3
diff options
context:
space:
mode:
Diffstat (limited to 'plugins/FTPFileYM/curl/docs/libcurl/curl_formadd.3')
-rw-r--r--plugins/FTPFileYM/curl/docs/libcurl/curl_formadd.3235
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)"