curl_formparse - add a section to a multipart/formdata
HTTP POST
SYNOPSIS
#include <curl/curl.h>
CURLcode curl_formparse(char * string, struct HttpPost **
firstitem, struct HttpPost ** lastitem);
DESCRIPTION
curl_formparse() 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 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 in a faster
way. string must be a zero terminated string abiding to
the syntax described in a section below
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 after the form post has been done
to free the resources again.
This function will copy all input data 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.
See example below.
FORM PARSE STRINGS
The string parameter must be using one of the following
patterns. Note that the [] letters should not be included
in the real-life string.
[name]=[contents]
Add a form field named 'name' with the contents
'contents'. This is the typcial contents of the
HTML tag <input type=text>.
[name]=@[filename]
Add a form field named 'name' with the contents as
read from the local file named 'filename'. This is
the typcial contents of the HTML tag <input
type=file>.
[name]=@[filename1,filename2,...]
Add a form field named 'name' with the contents as
'filename2'. This is identical to the upper,
except that you get the contents of several files
in one section.
[name]=@[filename];[type=<content-type>]
Whenever you specify a file to read from, you can
optionally specify the content-type as well. The
content-type is passed to the server together with
the contents of the file. curl_formparse() will
guess content-type for a number of well-known
extensions and otherwise it will set it to binary.
You can override the internal decision by using
this option.
[name]=@[filename1,filename2,...];[type=<content-type>]
When you specify several files to read the con
tents from, you can set the content-type for all
of them in the same way as with a single file.
RETURN VALUE
Returns non-zero if an error occurs.
EXAMPLE
HttpPost* post = NULL;
HttpPost* last = NULL;
/* Add an image section */
curl_formparse("picture=@my-face.jpg", &post, &last);
/* Add a normal text section */
curl_formparse("name=FooBar", &post, &last);
/* Set the form info */
curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
SEE ALSO
curl_easy_setopt(3), curl_formfree(3)
BUGS
Surely there are some, you tell me!
Man(1) output converted with
man2html