libcurl Manual curlformadd(3)
NAME
curlformadd - add a section to a multipart/formdata HTP
POST
SYNOPSIS
#include
CURLFORMcode curlformadd(struct curlhttppost ** firstitem,
struct curlhttppost ** lastitem, ...);
DESCRIPTION
curlformadd() is used to append sections when building a
multipart/formdata HTP 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 CURLOPTHTPOST.
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 point-
ing to NUL in the first call to this function. All list-
data will be allocated by the function itself. You must call
curlformfree(3) after the form post has been done to free
the resources.
Using POST with HTP 1.1 implies the use of a "Expect: 100-
continue" header. You can disable this header with
CURLOPTHTPHEADER 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 FILENAME.
Below, we'll discuss what options you use to set these pro-
perties in the parts you want to add to your post.
The options listed first are for making normal parts. The
options from CURLFORMFILE through CURLFORMBUFERLENGTH are
for file upload parts.
OPTIONS
CURLFORMCOPYNAME
followed by a string which provides the name of this
part. libcurl copies the string so your application
doesn't need to keep it around after this function
call. If the name isn't NUL-terminated, or if you'd
like it to contain zero bytes, you must set its length
with CURLFORMNAMELENGTH. The copied data will be freed
by curlformfree(3).
libcurl 7.9.8 Last change: 24 June 2002 1
libcurl Manual curlformadd(3)
CURLFORMPTRNAME
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 NUL-terminated, or if you'd like it to contain
zero bytes, you must set its length with
CURLFORMNAMELENGTH.
CURLFORMCOPYCONTENTS
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
CURLFORMCONTENTSLENGTH. The copied data will be freed
by curlformfree(3).
CURLFORMPTRCONTENTS
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 NUL-terminated, or if you'd like it to
contain zero bytes, you must set its length with
CURLFORMCONTENTSLENGTH.
CURLFORMCONTENTSLENGTH
followed by a long giving the length of the contents.
Note that for CURLFORMSTREAM contents, this option is
mandatory.
CURLFORMFILECONTENT
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.
CURLFORMFILE
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 CURLFORMFILE the user may send one or
more files in one part by providing multiple
CURLFORMFILE arguments each followed by the filename
(and each CURLFORMFILE is allowed to have a
CURLFORMCONTENTYPE).
CURLFORMCONTENTYPE
libcurl 7.9.8 Last change: 24 June 2002 2
libcurl Manual curlformadd(3)
is used in combination with CURLFORMFILE. Followed by
a pointer to a string which provides the content-type
for this part, possibly instead of an internally chosen
one.
CURLFORMFILENAME
is used in combination with CURLFORMFILE. 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.
CURLFORMBUFER
is used for custom file upload parts without use of
CURLFORMFILE. It tells libcurl that the file contents
are already present in a buffer. The parameter is a
string which provides the filename field in the content
header.
CURLFORMBUFERPTR
is used in combination with CURLFORMBUFER. The param-
eter is a pointer to the buffer to be uploaded. This
buffer must not be freed until after
curleasycleanup(3) is called. You must also use
CURLFORMBUFERLENGTH to set the number of bytes in the
buffer.
CURLFORMBUFERLENGTH
is used in combination with CURLFORMBUFER. The param-
eter is a long which gives the length of the buffer.
CURLFORMSTREAM
Tells libcurl to use the CURLOPTREADFUNCTION callback
to get data. The parameter you pass to CURLFORMSTREAM
is the pointer passed on to the read callback's fourth
argument. If you want the part to look like a file
upload one, set the CURLFORMFILENAME parameter as
well. Note that when using CURLFORMSTREAM,
CURLFORMCONTENTSLENGTH must also be set with the total
expected length of the part. (Option added in libcurl
7.18.2)
CURLFORMARAY
Another possibility to send options to curlformadd()
is the CURLFORMARAY option, that passes a struct
curlforms array pointer as its value. Each curlforms
structure element has a CURLformoption and a char
pointer. The final element in the array must be a
CURLFORMEND. All available options can be used in an
array, except the CURLFORMARAY option itself! The
last argument in such an array must always be
CURLFORMEND.
libcurl 7.9.8 Last change: 24 June 2002 3
libcurl Manual curlformadd(3)
CURLFORMCONTENTHEADER
specifies extra headers for the form POST section.
This takes a curlslist prepared in the usual way using
curlslistappend 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 experience problems.
When you've passed the HttpPost pointer to
curleasysetopt(3) (using the CURLOPTHTPOST
option), you must not free the list until after you've
called curleasycleanup(3) for the curl handle.
See example below.
RETURN VALUE
0 means everything was ok, non-zero means an error occurred
corresponding to a CURLFORMAD* constant defined in
EXAMPLE
struct curlhttppost* post = NUL;
struct curlhttppost* last = NUL;
char namebuffer[] = "name buffer";
long namelength = strlen(namebuffer);
char buffer[] = "test buffer";
char htmlbuffer[] = "test buffer";
long htmlbufferlength = strlen(htmlbuffer);
struct curlforms 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 */
curlformadd(&post, &last, CURLFORMCOPYNAME, "name",
CURLFORMCOPYCONTENTS, "content", CURLFORMEND);
/* Add simple name/content/contenttype section */
curlformadd(&post, &last, CURLFORMCOPYNAME, "htmlcode",
CURLFORMCOPYCONTENTS, "",
CURLFORMCONTENTYPE, "text/html", CURLFORMEND);
/* Add name/ptrcontent section */
curlformadd(&post, &last, CURLFORMCOPYNAME, "nameforptrcontent",
CURLFORMPTRCONTENTS, buffer, CURLFORMEND);
/* Add ptrname/ptrcontent section */
curlformadd(&post, &last, CURLFORMPTRNAME, namebuffer,
CURLFORMPTRCONTENTS, buffer, CURLFORMNAMELENGTH,
libcurl 7.9.8 Last change: 24 June 2002 4
libcurl Manual curlformadd(3)
namelength, CURLFORMEND);
/* Add name/ptrcontent/contenttype section */
curlformadd(&post, &last, CURLFORMCOPYNAME, "htmlcodewithhole",
CURLFORMPTRCONTENTS, htmlbuffer,
CURLFORMCONTENTSLENGTH, htmlbufferlength,
CURLFORMCONTENTYPE, "text/html", CURLFORMEND);
/* Add simple file section */
curlformadd(&post, &last, CURLFORMCOPYNAME, "picture",
CURLFORMFILE, "my-face.jpg", CURLFORMEND);
/* Add file/contenttype section */
curlformadd(&post, &last, CURLFORMCOPYNAME, "picture",
CURLFORMFILE, "my-face.jpg",
CURLFORMCONTENTYPE, "image/jpeg", CURLFORMEND);
/* Add two file section */
curlformadd(&post, &last, CURLFORMCOPYNAME, "pictures",
CURLFORMFILE, "my-face.jpg",
CURLFORMFILE, "your-face.jpg", CURLFORMEND);
/* Add two file section using CURLFORMARAY */
forms[0].option = CURLFORMFILE;
forms[0].value = file1;
forms[1].option = CURLFORMFILE;
forms[1].value = file2;
forms[2].option = CURLFORMEND;
/* Add a buffer to upload */
curlformadd(&post, &last,
CURLFORMCOPYNAME, "name",
CURLFORMBUFER, "data",
CURLFORMBUFERPTR, record,
CURLFORMBUFERLENGTH, recordlength,
CURLFORMEND);
/* no option needed for the end marker */
curlformadd(&post, &last, CURLFORMCOPYNAME, "pictures",
CURLFORMARAY, forms, CURLFORMEND);
/* Add the content of a file as a normal post text value */
curlformadd(&post, &last, CURLFORMCOPYNAME, "filecontent",
CURLFORMFILECONTENT, ".bashrc", CURLFORMEND);
/* Set the form info */
curleasysetopt(curl, CURLOPTHTPOST, post);
SEE ALSO
curleasysetopt(3), curlformfree(3)
ATRIBUTES
See attributes(5) for descriptions of the following
libcurl 7.9.8 Last change: 24 June 2002 5
libcurl Manual curlformadd(3)
attributes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcurl
Interface Stability Uncommitted
NOTES
Source for C-URL is available on http:/opensolaris.org.
libcurl 7.9.8 Last change: 24 June 2002 6
|
