Index of Section 3 Manual Pages
| Interix / SUA | curl_formadd.3 | Interix / SUA |
curl_formadd(3) libcurl Manual curl_formadd(3)
NAME
curl_formadd - add a section to a multipart/formdata HTTP
POST
SYNOPSIS
#include
CURLFORMcode curl_formadd(struct curl_httppost **
firstitem, struct curl_httppost ** lastitem, ...);
DESCRIPTION
curl_formadd() is used to append sections when building a
multipart/formdata HTTP POST (sometimes referred 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 CUR-
LOPT_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.
The pointers *firstitem and *lastitem 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 curl_formfree(3) 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
CURLOPT_HTTPHEADER 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 FILE-
NAME. 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 CURLFORM_FILE through CURLFORM_BUFFERLENGTH
are for file upload parts.
OPTIONS
CURLFORM_COPYNAME
followed by a string which provides the name of
this part. libcurl copies the string so your appli-
cation doesn't need to keep it around after this
function call. If the name isn't null terminated,
or if you'd like it to contain zero bytes, you must
set its length with CURLFORM_NAMELENGTH. The copied
data will be freed by curl_formfree(3).
CURLFORM_PTRNAME
followed by a string which provides the name 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 null terminated, or if you'd like it
to contain zero bytes, you must set its length with
CURLFORM_NAMELENGTH.
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 CURLFORM_CONTENTSLENGTH. The copied data
will be freed by curl_formfree(3).
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 null termi-
nated, or if you'd like it to contain zero bytes,
you must set its length with CURLFORM_CON-
TENTSLENGTH.
CURLFORM_CONTENTSLENGTH
followed by a long giving the length of the con-
tents.
CURLFORM_FILECONTENT
followed by a filename, causes that file to be read
and its contents used as data in this part. This
part does not automatically become a file upload
part simply because its data was read from a file.
CURLFORM_FILE
followed by a filename, makes this part a file
upload part. It sets the filename 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 CURL-
FORM_FILE the user may send one or more files in
one part by providing multiple CURLFORM_FILE argu-
ments each followed by the filename (and each CURL-
FORM_FILE is allowed to have a CURLFORM_CONTENT-
TYPE).
CURLFORM_CONTENTTYPE
is used in combination with CURLFORM_FILE. Followed
by a pointer to a string which provides the con-
tent-type for this part, possibly instead of an
internally chosen one.
CURLFORM_FILENAME
is used in combination with CURLFORM_FILE. Followed
by a pointer to a string, it tells libcurl to use
the given string as the filename in the file upload
part instead of the actual file name.
CURLFORM_BUFFER
is used for custom file upload parts without use of
CURLFORM_FILE. It tells libcurl that the file con-
tents are already present in a buffer. The parame-
ter is a string which provides the filename field
in the content header.
CURLFORM_BUFFERPTR
is used in combination with CURLFORM_BUFFER. The
parameter is a pointer to the buffer to be
uploaded. This buffer must not be freed until after
curl_easy_cleanup(3) is called. You must also use
CURLFORM_BUFFERLENGTH to set the number of bytes in
the buffer.
CURLFORM_BUFFERLENGTH
is used in combination with CURLFORM_BUFFER. The
parameter is a long which gives the length of the
buffer.
CURLFORM_ARRAY
Another possibility to send options to curl_for-
madd() 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! The last argument in such an array
must always be CURLFORM_END.
CURLFORM_CONTENTHEADER
specifies extra headers for the form POST section.
This takes a curl_slist prepared in the usual way
using curl_slist_append 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 experi-
ence problems.
When you've passed the HttpPost pointer to
curl_easy_setopt(3) (using the CURLOPT_HTTPPOST
option), you must not free the list until after
you've called curl_easy_cleanup(3) for the curl
handle.
See example below.
RETURN VALUE
0 means everything was ok, non-zero means an error
occurred as defines.
EXAMPLE
struct curl_httppost* post = NULL;
struct curl_httppost* last = NULL;
char namebuffer[] = "name buffer";
long namelength = strlen(namebuffer);
char buffer[] = "test buffer";
char htmlbuffer[] = "test buffer";
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, "",
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_formfree(3)
libcurl 7.9.8 24 June 2002 curl_formadd(3)