aboutsummaryrefslogtreecommitdiff
path: root/docs/curl_formadd.3
diff options
context:
space:
mode:
Diffstat (limited to 'docs/curl_formadd.3')
-rw-r--r--docs/curl_formadd.3165
1 files changed, 0 insertions, 165 deletions
diff --git a/docs/curl_formadd.3 b/docs/curl_formadd.3
deleted file mode 100644
index e0e157279..000000000
--- a/docs/curl_formadd.3
+++ /dev/null
@@ -1,165 +0,0 @@
-.\" 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!
-