mirror of
https://github.com/moparisthebest/curl
synced 2024-11-16 06:25:03 -05:00
86 lines
3.3 KiB
Groff
86 lines
3.3 KiB
Groff
.\" You can view this file with:
|
|
.\" nroff -man [file]
|
|
.\" $Id$
|
|
.\"
|
|
.TH curl_formparse 3 "21 May 2001" "libcurl 7.7.4" "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 (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 \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP.
|
|
\fIlastitem\fP 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. \fIstring\fP must be a zero terminated string abiding to the syntax
|
|
described in a section below
|
|
|
|
The pointers \fI*firstitem\fP and \fI*lastitem\fP 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 \fIcurl_formfree\fP 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 \fIcurl_formfree\fP. When you've passed the pointer
|
|
to \fIcurl_easy_setopt\fP, you must not free the list until after you've
|
|
called \fIcurl_easy_cleanup\fP for the curl handle.
|
|
|
|
See example below.
|
|
.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 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);
|
|
|
|
.SH "SEE ALSO"
|
|
.BR curl_easy_setopt "(3), "
|
|
.BR curl_formfree "(3)
|
|
.SH BUGS
|
|
Surely there are some, you tell me!
|
|
|