diff options
| -rw-r--r-- | docs/curl_formadd.3 | 95 |
1 files changed, 52 insertions, 43 deletions
diff --git a/docs/curl_formadd.3 b/docs/curl_formadd.3 index 532e34c3f..32a60e90d 100644 --- a/docs/curl_formadd.3 +++ b/docs/curl_formadd.3 @@ -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! |