| .\" 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: |
| deprecated (use curl_formadd instead) |
| .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_formadd "(3), " |
| .BR curl_formfree "(3) |
| .SH BUGS |
| Surely there are some, you tell me! |
| |