curl/docs/curl_formparse.3

.\" You can view this file with:
.\" nroff -man [file]
.\" Written by daniel@haxx.se
.\"
.TH curl_formparse 3 "5 March 2001" "libcurl 7.0" "libcurl Manual"
.SH NAME
curl_formparse - add a section to a multipart/formdata HTTP POST
.SH SYNOPSIS
.B #include <curl/curl.h>
.sp
.BI "CURLcode curl_formparse(char *" string, "struct HttpPost **" firstitem,
.BI "struct HttpPost ** "lastitem ");"
.ad
.SH DESCRIPTION
curl_formparse() is used to append sections when building a multipart/formdata
HTTP POST. Append one section at a time until you've added all the sections
you want included and then you pass the
.I firstitem
pointer as parameter to CURLOPT_HTTPPOST.
.I 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.
.I string
must be a zero terminated string following the following syntax.
.SH "FORM PARSE STRINGS"
The
.I string 
parameter must be using one of the following patterns. Note that the []
letters should not be included in the real-life string.
.TP 0.8i
.B [name]=[contents]
Add a form field named 'name' with the contents 'contents'. This is the
typcial contents of the HTML tag <input type=text>.
.TP
.B [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>.
.TP
.B [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.
.TP
.B [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.
.TP
.B [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.
.PP
.SH RETURN VALUE
Returns non-zero if an error occurs.
.SH "SEE ALSO"
.BR curl_easy_setopt "(3) "
.SH BUGS
Surely there are some, you tell me!