NAME
curl_formparse - add a section to a multipart/formdata HTTP
POST: deprecated (use curl_formadd instead)
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 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 in a faster way. string must be a zero ter
minated string abiding to the syntax described in a section
below
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 and keep its own ver
sion 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 pat
terns. 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
read from the local files named 'filename1' and
'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 exten
sions 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 contents
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_formadd(3), curl_formfree(3)
BUGS
Surely there are some, you tell me!
Man(1) output converted with
man2html