mirror of https://github.com/moparisthebest/curl
corrected return code, general cleanup
This commit is contained in:
Daniel Stenberg
parent
c9954d1941
commit
3f248dd163
|
|
@ -2,13 +2,13 @@
|
|||
.\" nroff -man [file]
|
||||
.\" $Id$
|
||||
.\"
|
||||
.TH curl_formadd 3 "27 August 2001" "libcurl 7.9" "libcurl Manual"
|
||||
.TH curl_formadd 3 "29 October 2001" "libcurl 7.9.1" "libcurl Manual"
|
||||
.SH NAME
|
||||
curl_formadd - add a section to a multipart/formdata HTTP POST
|
||||
.SH SYNOPSIS
|
||||
.B #include <curl/curl.h>
|
||||
.sp
|
||||
.BI "CURLcode curl_formadd(struct HttpPost ** " firstitem,
|
||||
.BI "int curl_formadd(struct HttpPost ** " firstitem,
|
||||
.BI "struct HttpPost ** " lastitem, " ...);"
|
||||
.ad
|
||||
.SH DESCRIPTION
|
||||
|
|
@ -17,62 +17,62 @@ 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.
|
||||
left as set to allow repeated invokes to find the end of the list faster.
|
||||
|
||||
After \fIlastitem\fP follow the real arguments that constitute the
|
||||
new section (if the following description confuses you jump directly
|
||||
to the examples):
|
||||
After the \fIlastitem\fP pointer follow the real arguments. (If the following
|
||||
description confuses you, jump directly to the examples):
|
||||
|
||||
CURLFORM_COPYNAME or CURLFORM_PTRNAME followed by a string is used for
|
||||
the name of the section. Optionally one may use CURLFORM_NAMELENGTH to
|
||||
specify the length of the name (allowing null characters within the name).
|
||||
\fBCURLFORM_COPYNAME\fP or \fBCURLFORM_PTRNAME\fP followed by a string is used
|
||||
for the name of the section. Optionally one may use \fBCURLFORM_NAMELENGTH\fP
|
||||
to specify the length of the name (allowing null characters within the
|
||||
name). All options that use the word COPY in their names copy the given
|
||||
contents, while the ones with PTR in their names simply points to the (static)
|
||||
data you must make sure remain until curl no longer needs it.
|
||||
|
||||
The four options for providing values are: CURLFORM_COPYCONTENTS,
|
||||
CURLFORM_PTRCONTENTS, CURLFORM_FILE, or CURLFORM_FILECONTENT followed
|
||||
by a char or void pointer (allowed for PTRCONTENTS).
|
||||
The four options for providing values are: \fBCURLFORM_COPYCONTENTS\fP,
|
||||
\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, or \fBCURLFORM_FILECONTENT\fP
|
||||
followed by a char or void pointer (allowed for PTRCONTENTS).
|
||||
|
||||
CURLFORM_FILECONTENT does a normal post like CURLFORM_COPYCONTENTS but
|
||||
the actual value is read from the filename given as a string.
|
||||
\fBCURLFORM_FILECONTENT\fP does a normal post like \fBCURLFORM_COPYCONTENTS\fP
|
||||
but the actual value is read from the filename given as a string.
|
||||
|
||||
Other arguments may be CURLFORM_CONTENTTYPE if the
|
||||
user wishes to specify one (for FILE if no type is given the library
|
||||
tries to provide the correct one; for CONTENTS no Content-Type is sent
|
||||
in this case).
|
||||
Other arguments may be \fBCURLFORM_CONTENTTYPE\fP if the user wishes to
|
||||
specify one (for FILE if no type is given the library tries to provide the
|
||||
correct one; for CONTENTS no Content-Type is sent in this case).
|
||||
|
||||
For CURLFORM_PTRCONTENTS or CURLFORM_COPYNAME the user may also add
|
||||
CURLFORM_CONTENTSLENGTH followed by the length as a long (if not given
|
||||
the library will use strlen to determine the length).
|
||||
For \fBCURLFORM_PTRCONTENTS\fP or \fBCURLFORM_COPYNAME\fP the user may also
|
||||
add \fBCURLFORM_CONTENTSLENGTH\fP followed by the length as a long (if not
|
||||
given the library will use strlen to determine the length).
|
||||
|
||||
For CURLFORM_FILE the user may send multiple files in one section by
|
||||
providing multiple CURLFORM_FILE arguments each followed by the filename
|
||||
For \fBCURLFORM_FILE\fP the user may send multiple files in one section by
|
||||
providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
|
||||
(and each FILE is allowed to have a CONTENTTYPE).
|
||||
|
||||
Another possibility to send single or multiple files in one section is
|
||||
to use CURLFORM_ARRAY that gets a struct curl_forms array as its
|
||||
value. Each structure element has a CURLformoption and a char
|
||||
pointer. For the options only CURLFORM_FILE, CURLFORM_CONTENTTYPE, and
|
||||
CURLFORM_END (that is used to determine the end of the array and thus
|
||||
must be the option of the last and no other element of the curl_forms
|
||||
array) are allowed. The effect of this parameter is the same as giving
|
||||
multiple CURLFORM_FILE options possibly with CURLFORM_CONTENTTYPE
|
||||
after or before each CURLFORM_FILE option.
|
||||
Another possibility to send single or multiple files in one section is to use
|
||||
\fBCURLFORM_ARRAY\fP that gets a struct curl_forms array pointer as its
|
||||
value. Each structure element has a CURLformoption and a char pointer. For the
|
||||
options only \fBCURLFORM_FILE\fP, \fBCURLFORM_CONTENTTYPE\fP, and
|
||||
\fBCURLFORM_END\fP (that is used to determine the end of the array and thus
|
||||
must be the option of the last and no other element of the curl_forms array)
|
||||
are allowed. The effect of this parameter is the same as giving multiple
|
||||
\fBCURLFORM_FILE\fP options possibly with \fBCURLFORM_CONTENTTYPE\fP after or
|
||||
before each \fBCURLFORM_FILE\fP option.
|
||||
|
||||
The last argument always is CURLFORM_END.
|
||||
The last argument in such an array must always be \fBCURLFORM_END\fP.
|
||||
|
||||
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 except the data pointed to by
|
||||
the arguments after CURLFORM_PTRNAME and CURLFORM_PTRCONTENTS and keep
|
||||
This function will copy all input data except the data pointed to by the
|
||||
arguments after \fBCURLFORM_PTRNAME\fP and \fBCURLFORM_PTRCONTENTS\fP 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. If you provide a pointer as an arguments after
|
||||
CURLFORM_PTRNAME or CURLFORM_PTRCONTENTS you must ensure that the pointer
|
||||
stays valid until you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP.
|
||||
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. If
|
||||
you provide a pointer as an arguments after \fBCURLFORM_PTRNAME\fP or
|
||||
\fBCURLFORM_PTRCONTENTS\fP you must ensure that the pointer stays valid until
|
||||
you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP.
|
||||
|
||||
See example below.
|
||||
.SH RETURN VALUE
|
||||
|
|
@ -98,39 +98,48 @@ Returns non-zero if an error occurs.
|
|||
/* Add simple name/content section */
|
||||
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
|
||||
CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
|
||||
|
||||
/* Add simple name/content/contenttype section */
|
||||
curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
|
||||
CURLFORM_COPYCONTENTS, "<HTML></HTML>",
|
||||
CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
|
||||
|
||||
/* Add name/ptrcontent section */
|
||||
curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
|
||||
CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
|
||||
|
||||
/* Add ptrname/ptrcontent section */
|
||||
curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
|
||||
CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
|
||||
namelength, CURLFORM_END);
|
||||
|
||||
/* Add name/ptrcontent/contenttype section */
|
||||
curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
|
||||
CURLFORM_PTRCONTENTS, htmlbuffer,
|
||||
CURLFORM_CONTENTSLENGTH, htmlbufferlength,
|
||||
CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
|
||||
|
||||
/* Add simple file section */
|
||||
curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
|
||||
CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
|
||||
|
||||
/* Add file/contenttype section */
|
||||
curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
|
||||
CURLFORM_FILE, "my-face.jpg",
|
||||
CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
|
||||
|
||||
/* Add two file section */
|
||||
curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
|
||||
CURLFORM_FILE, "my-face.jpg",
|
||||
CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
|
||||
|
||||
/* Add two file section using CURLFORM_ARRAY */
|
||||
forms[0].option = CURLFORM_FILE;
|
||||
forms[0].value = file1;
|
||||
forms[1].option = CURLFORM_FILE;
|
||||
forms[1].value = file2;
|
||||
forms[2].value = CURLFORM_END;
|
||||
forms[2].option = CURLFORM_END;
|
||||
|
||||
/* no option needed for the end marker */
|
||||
curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
|
||||
CURLFORM_ARRAY, forms, CURLFORM_END);
|
||||
|
|
@ -143,7 +152,7 @@ Returns non-zero if an error occurs.
|
|||
.SH "SEE ALSO"
|
||||
.BR curl_easy_setopt "(3), "
|
||||
.BR curl_formparse "(3) [deprecated], "
|
||||
.BR curl_formfree "(3)
|
||||
.BR curl_formfree "(3)"
|
||||
.SH BUGS
|
||||
Surely there are some, you tell me!
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue