curl/docs/curl_formadd.3

150 lines
6.4 KiB
Groff
Raw Normal View History

.\" You can view this file with:
.\" nroff -man [file]
.\" $Id$
.\"
2001-08-28 10:55:26 +02:00
.TH curl_formadd 3 "27 August 2001" "libcurl 7.9" "libcurl Manual"
.SH NAME
curl_formadd - add a section to a multipart/formdata HTTP POST
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "CURLcode 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 in a faster
way.
After \fIlastitem\fP follow the real arguments that constitute the
new section (if the following description confuses you jump directly
to the examples):
2001-08-28 10:55:26 +02:00
CURLFORM_COPYNAME or CURLFORM_PTRNAME followed by a string is used for
the name of the section. Optionally one may use CURLFORM_NAMELENGTH to
specify the length of the name (allowing null characters within the name).
2001-10-03 10:02:17 +02:00
The four options for providing values are: CURLFORM_COPYCONTENTS,
CURLFORM_PTRCONTENTS, CURLFORM_FILE, or CURLFORM_FILECONTENT followed
by a char or void pointer (allowed for PTRCONTENTS).
CURLFORM_FILECONTENT does a normal post like CURLFORM_COPYCONTENTS but
the actual value is read from the filename given as a string.
2001-08-28 10:55:26 +02:00
Other arguments may be CURLFORM_CONTENTTYPE 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
2001-10-03 10:02:17 +02:00
in this case).
2001-08-28 10:55:26 +02:00
For CURLFORM_PTRCONTENTS or CURLFORM_COPYNAME the user may also add
CURLFORM_CONTENTSLENGTH followed by the length as a long (if not given
the library will use strlen to determine the length).
For CURLFORM_FILE the user may send multiple files in one section by
providing multiple CURLFORM_FILE arguments each followed by the filename
(and each FILE is allowed to have a CONTENTTYPE).
2001-10-03 10:02:17 +02:00
Another possibility to send single or multiple files in one section is
to use CURLFORM_ARRAY that gets a struct curl_forms array as its
value. Each structure element has a CURLformoption and a char
pointer. For the options only CURLFORM_FILE, CURLFORM_CONTENTTYPE, and
CURLFORM_END (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 CURLFORM_FILE options possibly with CURLFORM_CONTENTTYPE
after or before each CURLFORM_FILE option.
The last argument always is CURLFORM_END.
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
2001-08-28 10:55:26 +02:00
the arguments after CURLFORM_PTRNAME and CURLFORM_PTRCONTENTS 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
2001-08-28 10:55:26 +02:00
curl handle. If you provide a pointer as an arguments after
CURLFORM_PTRNAME or CURLFORM_PTRCONTENTS 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;
2001-08-28 10:55:26 +02:00
char namebuffer[] = "name buffer";
long namelength = strlen(namebuffer);
char buffer[] = "test buffer";
char htmlbuffer[] = "<HTML>test buffer</HTML>";
long htmlbufferlength = strlen(htmlbuffer);
2001-10-03 10:02:17 +02:00
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 */
2001-08-28 10:55:26 +02:00
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
2001-08-28 10:55:26 +02:00
/* 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);
2001-10-03 10:02:17 +02:00
/* 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].value = 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!