NAME
curl_formadd - add a section to a multipart/formdata HTTP
POST
SYNOPSIS
#include <curl/curl.h>
CURLFORMcode curl_formadd(struct HttpPost ** firstitem,
struct HttpPost ** lastitem, ...);
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 firstitem pointer as parameter to CURLOPT_HTTPPOST.
lastitem 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 lastitem pointer follow the real arguments. (If
the following description confuses you, jump directly to the
examples):
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). 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: CURLFORM_COPYCONTENTS,
CURLFORM_PTRCONTENTS, CURLFORM_FILE, CURLFORM_BUFFER, or
CURLFORM_FILECONTENT followed by a char or void pointer
(allowed for PTRCONTENTS).
CURLFORM_FILECONTENT does a normal post like CURLFORM_COPY
CONTENTS but the actual value is read from the filename
given as a string.
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 in this case).
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).
CURLFORM_BUFFER 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.
CURLFORM_BUFFERPTR 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.
CURLFORM_BUFFERLENGTH 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
CURLFORM_ARRAY 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 CURLFORM_CONTENTHEADER. This takes a curl_slist
prepared in the usual way using curl_slist_append and
appends the list of headers to those Curl automatically gen
erates for CURLFORM_CONTENTTYPE 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 CURL
FORM_END.
The pointers *firstitem and *lastitem should both be point
ing to NULL in the first call to this function. All list-
data will be allocated by the function itself. You must call
curl_formfree 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 CURLFORM_PTRNAME and CURL
FORM_PTRCONTENTS and keep its own version of it allocated
until you call curl_formfree. When you've passed the pointer
to curl_easy_setopt, you must not free the list until after
you've called curl_easy_cleanup for the 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 curl_form_free and curl_easy_cleanup.
See example below.
RETURN VALUE
0 means everything was ok, non-zero means an error occurred
as <curl/curl.h> defines.
EXAMPLE
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);
SEE ALSO
curl_easy_setopt(3), curl_formparse(3) [deprecated],
curl_formfree(3)
BUGS
Surely there are some, you tell me!
Man(1) output converted with
man2html