mirror of https://github.com/moparisthebest/curl
187 lines
7.8 KiB
Groff
187 lines
7.8 KiB
Groff
.\" You can view this file with:
|
|
.\" nroff -man [file]
|
|
.\" $Id$
|
|
.\"
|
|
.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 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 options for providing values are: \fBCURLFORM_COPYCONTENTS\fP,
|
|
\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, \fBCURLFORM_BUFFER\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).
|
|
|
|
\fBCURLFORM_BUFFER\fP
|
|
tells libcurl that a buffer is to be used to upload data instead of using a
|
|
file. The value of the next parameter is used as the value of the "filename"
|
|
parameter in the content header.
|
|
|
|
\fBCURLFORM_BUFFERPTR\fP
|
|
tells libcurl that the address of the next parameter is a pointer to the buffer
|
|
containing data to upload. The buffer containing this data must not be freed
|
|
until after curl_easy_cleanup is called.
|
|
|
|
\fBCURLFORM_BUFFERLENGTH\fP
|
|
tells libcurl that the length of the buffer to upload is the value of the
|
|
next parameter.
|
|
|
|
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!
|
|
|
|
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
|
|
0 means everything was ok, non-zero means an error occurred as
|
|
.I <curl/curl.h>
|
|
defines.
|
|
.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;
|
|
|
|
/* 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_formparse "(3) [deprecated], "
|
|
.BR curl_formfree "(3)"
|
|
.SH BUGS
|
|
Surely there are some, you tell me!
|
|
|