From 01f04b9a4127aa2bfb9cdaa8b2d4114268f45514 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 4 Mar 2002 10:09:48 +0000 Subject: ripped out from ../ and put in its own directory now --- docs/libcurl/curl_formadd.3 | 165 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 docs/libcurl/curl_formadd.3 (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 new file mode 100644 index 000000000..e0e157279 --- /dev/null +++ b/docs/libcurl/curl_formadd.3 @@ -0,0 +1,165 @@ +.\" You can view this file with: +.\" nroff -man [file] +.\" $Id$ +.\" +.TH curl_formadd 3 "1 Match 2002" "libcurl 7.9.1" "libcurl Manual" +.SH NAME +curl_formadd - add a section to a multipart/formdata HTTP POST +.SH SYNOPSIS +.B #include +.sp +.BI "int curl_formadd(struct HttpPost ** " firstitem, +.BI "struct HttpPost ** " lastitem, " ...);" +.ad +.SH DESCRIPTION +curl_formadd() 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 faster. + +After the \fIlastitem\fP pointer follow the real arguments. (If the following +description confuses you, jump directly to the examples): + +\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: \fBCURLFORM_COPYCONTENTS\fP, +\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, or \fBCURLFORM_FILECONTENT\fP +followed by a char or void pointer (allowed for PTRCONTENTS). + +\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 \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 \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 \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 +\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. + +Should you need to specify extra headers for the form POST section, use +\fBCURLFORM_CONTENTHEADER\fP. This takes a curl_slist prepared in the usual way +using \fBcurl_slist_append\fP and appends the list of headers to those Curl +automatically generates for \fBCURLFORM_CONTENTTYPE\fP and the content +disposition. The list must exist while the POST occurs, if you free it before +the post completes you may experience problems. + +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 \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 \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 +Returns non-zero if an error occurs. +.SH EXAMPLE +.nf + + struct HttpPost* post = NULL; + struct HttpPost* last = NULL; + char namebuffer[] = "name buffer"; + long namelength = strlen(namebuffer); + char buffer[] = "test buffer"; + char htmlbuffer[] = "test buffer"; + long htmlbufferlength = strlen(htmlbuffer); + struct curl_forms forms[3]; + char file1[] = "my-face.jpg"; + char file2[] = "your-face.jpg"; + /* add null character into htmlbuffer, to demonstrate that + transfers of buffers containing null characters actually work + */ + htmlbuffer[8] = '\\0'; + + /* 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, "", + 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].option = CURLFORM_END; + + /* no option needed for the end marker */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", + CURLFORM_ARRAY, forms, CURLFORM_END); + /* Add the content of a file as a normal post text value */ + curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent", + CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END); + /* Set the form info */ + curl_easy_setopt(curl, CURLOPT_HTTPPOST, post); + +.SH "SEE ALSO" +.BR curl_easy_setopt "(3), " +.BR curl_formparse "(3) [deprecated], " +.BR curl_formfree "(3)" +.SH BUGS +Surely there are some, you tell me! + -- cgit v1.2.1 From c3c392fc9801e7eb1834613ad41c57bb386355c0 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 21 May 2002 07:47:09 +0000 Subject: return type CURLFORMcode instead of plain int --- docs/libcurl/curl_formadd.3 | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index e0e157279..93bed079d 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -2,13 +2,13 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_formadd 3 "1 Match 2002" "libcurl 7.9.1" "libcurl Manual" +.TH curl_formadd 3 "21 May 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_formadd - add a section to a multipart/formdata HTTP POST .SH SYNOPSIS .B #include .sp -.BI "int curl_formadd(struct HttpPost ** " firstitem, +.BI "CURLFORMcode curl_formadd(struct HttpPost ** " firstitem, .BI "struct HttpPost ** " lastitem, " ...);" .ad .SH DESCRIPTION @@ -83,7 +83,9 @@ you call \fIcurl_form_free\fP and \fIcurl_easy_cleanup\fP. See example below. .SH RETURN VALUE -Returns non-zero if an error occurs. +0 means everything was ok, non-zero means an error occurred as +.I +defines. .SH EXAMPLE .nf -- cgit v1.2.1 From 5cb06d8fd6e917e118fa039cf02017d6c903a145 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 15 Jun 2002 11:17:42 +0000 Subject: Chris Combes added description of his newly added options --- docs/libcurl/curl_formadd.3 | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 93bed079d..2c522c90a 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_formadd 3 "21 May 2002" "libcurl 7.9.8" "libcurl Manual" +.TH curl_formadd 3 "15 June 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_formadd - add a section to a multipart/formdata HTTP POST .SH SYNOPSIS @@ -29,9 +29,10 @@ 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: \fBCURLFORM_COPYCONTENTS\fP, -\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, or \fBCURLFORM_FILECONTENT\fP -followed by a char or void pointer (allowed for PTRCONTENTS). +The options for providing values are: \fBCURLFORM_COPYCONTENTS\fP, +\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, \fBCURLFORM_BUFFER\fP, +or \fBCURLFORM_FILECONTENT\fP followed by a char or void pointer +(allowed for PTRCONTENTS). \fBCURLFORM_FILECONTENT\fP does a normal post like \fBCURLFORM_COPYCONTENTS\fP but the actual value is read from the filename given as a string. @@ -48,6 +49,20 @@ 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). +\fBCURLFORM_BUFFER\fP +tells libcurl that a buffer is to be used to upload data instead of using a +file. The value of the next parameter is used as the value of the "filename" +parameter in the content header. + +\fBCURLFORM_BUFFERPTR\fP +tells libcurl that the address of the next parameter is a pointer to the buffer +containing data to upload. The buffer containing this data must not be freed +until after curl_easy_cleanup is called. + +\fBCURLFORM_BUFFERLENGTH\fP +tells libcurl that the length of the buffer to upload is the value of the +next parameter. + 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 @@ -149,6 +164,13 @@ defines. forms[1].value = file2; forms[2].option = CURLFORM_END; + /* Add a buffer to upload */ + curl_formadd(&post, &last, + CURLFORM_BUFFER, "data", + CURLFORM_BUFFERPTR, record, + CURLFORM_BUFFERLENGTH, record_length, + CURLFORM_END); + /* no option needed for the end marker */ curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", CURLFORM_ARRAY, forms, CURLFORM_END); -- cgit v1.2.1 From 62527fa98a822243aaf0b07dde0a85c851ed771b Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 24 Jun 2002 06:14:56 +0000 Subject: corrected to match reality better --- docs/libcurl/curl_formadd.3 | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 2c522c90a..66d4ffefd 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -2,7 +2,7 @@ .\" nroff -man [file] .\" $Id$ .\" -.TH curl_formadd 3 "15 June 2002" "libcurl 7.9.8" "libcurl Manual" +.TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_formadd - add a section to a multipart/formdata HTTP POST .SH SYNOPSIS @@ -63,15 +63,11 @@ until after curl_easy_cleanup is called. tells libcurl that the length of the buffer to upload is the value of the next parameter. -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. +Another possibility to send options to curl_formadd() is the +\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as +its value. Each curl_forms structure element has a CURLformoption and a char +pointer. The final element in the array must be a CURLFORM_END. All available +options can be used in an array, except the CURLFORM_ARRAY option itself! Should you need to specify extra headers for the form POST section, use \fBCURLFORM_CONTENTHEADER\fP. This takes a curl_slist prepared in the usual way @@ -166,6 +162,7 @@ defines. /* Add a buffer to upload */ curl_formadd(&post, &last, + CURLFORM_COPYNAME, "name", CURLFORM_BUFFER, "data", CURLFORM_BUFFERPTR, record, CURLFORM_BUFFERLENGTH, record_length, -- cgit v1.2.1 From d6654bfe00ae6d955d6f6f7367d2e7b1e11011b4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 16 Oct 2002 09:53:38 +0000 Subject: mucho fixed --- docs/libcurl/curl_formadd.3 | 158 ++++++++++++++++++++++++++------------------ 1 file changed, 92 insertions(+), 66 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 66d4ffefd..7a4cb4484 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -19,78 +19,104 @@ 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 faster. -After the \fIlastitem\fP pointer follow the real arguments. (If the following -description confuses you, jump directly to the examples): - -\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 options for providing values are: \fBCURLFORM_COPYCONTENTS\fP, -\fBCURLFORM_PTRCONTENTS\fP, \fBCURLFORM_FILE\fP, \fBCURLFORM_BUFFER\fP, -or \fBCURLFORM_FILECONTENT\fP followed by a char or void pointer -(allowed for PTRCONTENTS). - -\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 \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 \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 \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). - -\fBCURLFORM_BUFFER\fP -tells libcurl that a buffer is to be used to upload data instead of using a -file. The value of the next parameter is used as the value of the "filename" -parameter in the content header. - -\fBCURLFORM_BUFFERPTR\fP -tells libcurl that the address of the next parameter is a pointer to the buffer -containing data to upload. The buffer containing this data must not be freed -until after curl_easy_cleanup is called. - -\fBCURLFORM_BUFFERLENGTH\fP -tells libcurl that the length of the buffer to upload is the value of the -next parameter. - -Another possibility to send options to curl_formadd() is the -\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as -its value. Each curl_forms structure element has a CURLformoption and a char -pointer. The final element in the array must be a CURLFORM_END. All available -options can be used in an array, except the CURLFORM_ARRAY option itself! - -Should you need to specify extra headers for the form POST section, use -\fBCURLFORM_CONTENTHEADER\fP. This takes a curl_slist prepared in the usual way -using \fBcurl_slist_append\fP and appends the list of headers to those Curl -automatically generates for \fBCURLFORM_CONTENTTYPE\fP and the content -disposition. The list must exist while the POST occurs, if you free it before -the post completes you may experience problems. - -The last argument in such an array must always be \fBCURLFORM_END\fP. +After the \fIlastitem\fP pointer follow the real arguments. 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 \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 \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. +First, there are some basics you need to understand about multipart/formdata +posts. Each part consists of at least a NAME and a CONTENTS part. If the part +is made for file upload, there are also a stored CONTENT-TYPE and a +FILENAME. Below here, we'll discuss on what options you use to set these +properties in the parts you want to add to your post. +.SH OPTIONS +.B CURLFORM_COPYNAME +followed by string is used to set the name of this part. libcurl copies the +given data, so your application doesn't need to keep it around after this +function call. If the name isn't zero terminated properly, or if you'd like it +to contain zero bytes, you need to set the length of the name with +\fBCURLFORM_NAMELENGTH\fP. + +.B CURLFORM_PTRNAME +followed by a string is used for the name of this part. libcurl will use the +pointer and refer to the data in your application, you must make sure it +remains until curl no longer needs it. If the name isn't zero terminated +properly, or if you'd like it to contain zero bytes, you need to set the +length of the name with \fBCURLFORM_NAMELENGTH\fP. + +.B CURLFORM_COPYCONTENTS +followed by a string is used for the contents of this part, the actual data to +send away. libcurl copies the given data, so your application doesn't need to +keep it around after this function call (\f). If the data isn't zero terminated +properly, or if you'd like it to contain zero bytes, you need to set the +length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. + +.B CURLFORM_PTRCONTENTS +followed by a string is used for the contents of this part, the actual data to +send away. libcurl will use the pointer and refer to the data in your +application, you must make sure it remains until curl no longer needs it. If +the data isn't zero terminated properly, or if you'd like it to contain zero +bytes, you need to set the length of the name with +\fBCURLFORM_CONTENTSLENGTH\fP. + +.B CURLFORM_FILECONTENT +followed by a file name, makes that file read and the contents will be used in +as data in this part. + +.B CURLFORM_FILE +followed by a file name, makes this part a file upload part. It sets the file +name field to the actual file name used here, it gets the contents of the file +and passes as data and sets the content-type if the given file match one of +the new internally known file extension. For \fBCURLFORM_FILE\fP the user may +send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP +arguments each followed by the filename (and each CURLFORM_FILE is allowed to +have a CURLFORM_CONTENTTYPE). + +.B CURLFORM_CONTENTTYPE +followed by a pointer to a string with a content-type will make curl use this +given content-type for this file upload part, possibly instead of an +internally chosen one. + +.B CURLFORM_FILENAME +followed by a pointer to a string to a name, will make libcurl use the given +name in the file upload part, intead of the actual file name given to +\fICURLFORM_FILE\fP. + +.B BCURLFORM_BUFFER +followed by a string, tells libcurl that a buffer is to be used to upload data +instead of using a file. The given string is used as the value of the file +name field in the content header. + +.B CURLFORM_BUFFERPTR +followed by a pointer to a data area, tells libcurl the address of the buffer +containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The +buffer containing this data must not be freed until after curl_easy_cleanup is +called. + +.B CURLFORM_BUFFERLENGTH +followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area, +tells libcurl the length of the buffer to upload. + +.B CURLFORM_ARRAY +Another possibility to send options to curl_formadd() is the +\fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as +its value. Each curl_forms structure element has a CURLformoption and a char +pointer. The final element in the array must be a CURLFORM_END. All available +options can be used in an array, except the CURLFORM_ARRAY option itself! The +last argument in such an array must always be \fBCURLFORM_END\fP. + +.B CURLFORM_CONTENTHEADER +specifies extra headers for the form POST section. This takes a curl_slist +prepared in the usual way using \fBcurl_slist_append\fP and appends the list +of headers to those libcurl automatically generates. The list must exist while +the POST occurs, if you free it before the post completes you may experience +problems. + +When you've passed the HttpPost pointer to \fIcurl_easy_setopt\fP (using the +\fICURLOPT_HTTPPOST\fP option), you must not free the list until after you've +called \fIcurl_easy_cleanup\fP for the curl handle. See example below. .SH RETURN VALUE -- cgit v1.2.1 From 3836a70f976e5024ddc3af6b66f167e730791c61 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 15 Nov 2002 14:13:46 +0000 Subject: removed nroff mistake --- docs/libcurl/curl_formadd.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 7a4cb4484..8ede2bbb2 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -49,7 +49,7 @@ length of the name with \fBCURLFORM_NAMELENGTH\fP. .B CURLFORM_COPYCONTENTS followed by a string is used for the contents of this part, the actual data to send away. libcurl copies the given data, so your application doesn't need to -keep it around after this function call (\f). If the data isn't zero terminated +keep it around after this function call. If the data isn't zero terminated properly, or if you'd like it to contain zero bytes, you need to set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. -- cgit v1.2.1 From 0b1f7995c5296f53b577bbc73a55cb9acd85d33e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 23 Feb 2004 09:01:08 +0000 Subject: correct the input data structs --- docs/libcurl/curl_formadd.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 8ede2bbb2..9802351d1 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -8,8 +8,8 @@ curl_formadd - add a section to a multipart/formdata HTTP POST .SH SYNOPSIS .B #include .sp -.BI "CURLFORMcode curl_formadd(struct HttpPost ** " firstitem, -.BI "struct HttpPost ** " lastitem, " ...);" +.BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem, +.BI "struct curl_httppost ** " lastitem, " ...);" .ad .SH DESCRIPTION curl_formadd() is used to append sections when building a multipart/formdata -- cgit v1.2.1 From 25bcd45034b2289becfb34a762d5a8c0e9a0c0ef Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 27 Feb 2004 15:34:06 +0000 Subject: formatting update to produce better links with the new roffit version --- docs/libcurl/curl_formadd.3 | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 9802351d1..3cc428019 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -92,8 +92,8 @@ name field in the content header. .B CURLFORM_BUFFERPTR followed by a pointer to a data area, tells libcurl the address of the buffer containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The -buffer containing this data must not be freed until after curl_easy_cleanup is -called. +buffer containing this data must not be freed until after +\fIcurl_easy_cleanup(3)\fP is called. .B CURLFORM_BUFFERLENGTH followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area, @@ -114,9 +114,9 @@ of headers to those libcurl automatically generates. The list must exist while the POST occurs, if you free it before the post completes you may experience problems. -When you've passed the HttpPost pointer to \fIcurl_easy_setopt\fP (using the -\fICURLOPT_HTTPPOST\fP option), you must not free the list until after you've -called \fIcurl_easy_cleanup\fP for the curl handle. +When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using +the \fICURLOPT_HTTPPOST\fP option), you must not free the list until after +you've called \fIcurl_easy_cleanup(3)\fP for the curl handle. See example below. .SH RETURN VALUE @@ -207,6 +207,3 @@ defines. .BR curl_easy_setopt "(3), " .BR curl_formparse "(3) [deprecated], " .BR curl_formfree "(3)" -.SH BUGS -Surely there are some, you tell me! - -- cgit v1.2.1 From 4b78b4124eee95c42f05e9c3df9ca798a0318db9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 24 Mar 2004 21:40:45 +0000 Subject: Tor Arntsen's major ispell patch --- docs/libcurl/curl_formadd.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 3cc428019..95671e7f9 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -13,7 +13,7 @@ curl_formadd - add a section to a multipart/formdata HTTP POST .ad .SH DESCRIPTION curl_formadd() is used to append sections when building a multipart/formdata -HTTP POST (sometimes refered to as rfc1867-style posts). Append one section at +HTTP POST (sometimes referred 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 @@ -81,7 +81,7 @@ internally chosen one. .B CURLFORM_FILENAME followed by a pointer to a string to a name, will make libcurl use the given -name in the file upload part, intead of the actual file name given to +name in the file upload part, instead of the actual file name given to \fICURLFORM_FILE\fP. .B BCURLFORM_BUFFER -- cgit v1.2.1 From 9733cd59bb41a2022d54aa14be4a40c1dc290018 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 9 Jun 2004 08:18:17 +0000 Subject: removed reference to the removed curl_formparse --- docs/libcurl/curl_formadd.3 | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 95671e7f9..961bfbf26 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -205,5 +205,4 @@ defines. .SH "SEE ALSO" .BR curl_easy_setopt "(3), " -.BR curl_formparse "(3) [deprecated], " .BR curl_formfree "(3)" -- cgit v1.2.1 From d869b51a57c39cbc25df0df7cee375f608ec2e82 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 23 Aug 2004 14:46:43 +0000 Subject: Expect: 100-continue info added --- docs/libcurl/curl_formadd.3 | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 961bfbf26..366e6b07f 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -26,6 +26,9 @@ 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. +Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. +You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. + First, there are some basics you need to understand about multipart/formdata posts. Each part consists of at least a NAME and a CONTENTS part. If the part is made for file upload, there are also a stored CONTENT-TYPE and a -- cgit v1.2.1 From 5f60188b8adbe5055b0780df36caf3e209d06531 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 2 Sep 2004 20:42:44 +0000 Subject: use the correct struct name in the example --- docs/libcurl/curl_formadd.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 366e6b07f..c8055afb9 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -129,8 +129,8 @@ defines. .SH EXAMPLE .nf - struct HttpPost* post = NULL; - struct HttpPost* last = NULL; + struct curl_httppost* post = NULL; + struct curl_httppost* last = NULL; char namebuffer[] = "name buffer"; long namelength = strlen(namebuffer); char buffer[] = "test buffer"; -- cgit v1.2.1 From 34089c93bb83362e395dbca441c3b49e06e7c4af Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 25 Oct 2004 11:05:37 +0000 Subject: format update --- docs/libcurl/curl_formadd.3 | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index c8055afb9..693ca0f2e 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -35,28 +35,28 @@ is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME. Below here, we'll discuss on what options you use to set these properties in the parts you want to add to your post. .SH OPTIONS -.B CURLFORM_COPYNAME +.IP CURLFORM_COPYNAME followed by string is used to set the name of this part. libcurl copies the given data, so your application doesn't need to keep it around after this function call. If the name isn't zero terminated properly, or if you'd like it to contain zero bytes, you need to set the length of the name with \fBCURLFORM_NAMELENGTH\fP. -.B CURLFORM_PTRNAME +.IP CURLFORM_PTRNAME followed by a string is used for the name of this part. libcurl will use the pointer and refer to the data in your application, you must make sure it remains until curl no longer needs it. If the name isn't zero terminated properly, or if you'd like it to contain zero bytes, you need to set the length of the name with \fBCURLFORM_NAMELENGTH\fP. -.B CURLFORM_COPYCONTENTS +.IP CURLFORM_COPYCONTENTS followed by a string is used for the contents of this part, the actual data to send away. libcurl copies the given data, so your application doesn't need to keep it around after this function call. If the data isn't zero terminated properly, or if you'd like it to contain zero bytes, you need to set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. -.B CURLFORM_PTRCONTENTS +.IP CURLFORM_PTRCONTENTS followed by a string is used for the contents of this part, the actual data to send away. libcurl will use the pointer and refer to the data in your application, you must make sure it remains until curl no longer needs it. If @@ -64,11 +64,14 @@ the data isn't zero terminated properly, or if you'd like it to contain zero bytes, you need to set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. -.B CURLFORM_FILECONTENT +.IP CURLFORM_CONTENTSLENGTH +followed by a long setting the length of the contents. + +.IP CURLFORM_FILECONTENT followed by a file name, makes that file read and the contents will be used in as data in this part. -.B CURLFORM_FILE +.IP CURLFORM_FILE followed by a file name, makes this part a file upload part. It sets the file name field to the actual file name used here, it gets the contents of the file and passes as data and sets the content-type if the given file match one of @@ -77,32 +80,33 @@ send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename (and each CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE). -.B CURLFORM_CONTENTTYPE +.IP CURLFORM_CONTENTTYPE followed by a pointer to a string with a content-type will make curl use this given content-type for this file upload part, possibly instead of an internally chosen one. -.B CURLFORM_FILENAME +.IP CURLFORM_FILENAME followed by a pointer to a string to a name, will make libcurl use the given name in the file upload part, instead of the actual file name given to \fICURLFORM_FILE\fP. -.B BCURLFORM_BUFFER +.IP BCURLFORM_BUFFER followed by a string, tells libcurl that a buffer is to be used to upload data instead of using a file. The given string is used as the value of the file name field in the content header. -.B CURLFORM_BUFFERPTR +.IP CURLFORM_BUFFERPTR followed by a pointer to a data area, tells libcurl the address of the buffer containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The buffer containing this data must not be freed until after -\fIcurl_easy_cleanup(3)\fP is called. +\fIcurl_easy_cleanup(3)\fP is called. You must also use +\fICURLFORM_BUFFERLENGTH\fP to set the length of the given buffer area. -.B CURLFORM_BUFFERLENGTH +.IP CURLFORM_BUFFERLENGTH followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area, tells libcurl the length of the buffer to upload. -.B CURLFORM_ARRAY +.IP CURLFORM_ARRAY Another possibility to send options to curl_formadd() is the \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as its value. Each curl_forms structure element has a CURLformoption and a char @@ -110,7 +114,7 @@ pointer. The final element in the array must be a CURLFORM_END. All available options can be used in an array, except the CURLFORM_ARRAY option itself! The last argument in such an array must always be \fBCURLFORM_END\fP. -.B CURLFORM_CONTENTHEADER +.IP CURLFORM_CONTENTHEADER specifies extra headers for the form POST section. This takes a curl_slist prepared in the usual way using \fBcurl_slist_append\fP and appends the list of headers to those libcurl automatically generates. The list must exist while -- cgit v1.2.1 From 93558c4299f579a13a6f8fa7b262e65cb061ce8d Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 20 Jun 2005 22:32:45 +0000 Subject: mistake --- docs/libcurl/curl_formadd.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 693ca0f2e..3a45f006e 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -90,7 +90,7 @@ followed by a pointer to a string to a name, will make libcurl use the given name in the file upload part, instead of the actual file name given to \fICURLFORM_FILE\fP. -.IP BCURLFORM_BUFFER +.IP CURLFORM_BUFFER followed by a string, tells libcurl that a buffer is to be used to upload data instead of using a file. The given string is used as the value of the file name field in the content header. -- cgit v1.2.1 From 1e9be353c27a6351d96183acf23167db6394d611 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sun, 3 Sep 2006 22:12:57 +0000 Subject: Mohun Biswas' improvements and clarifications about the options and how to use them. --- docs/libcurl/curl_formadd.3 | 108 ++++++++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 50 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 3a45f006e..a94dd506f 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -23,88 +23,96 @@ After the \fIlastitem\fP pointer follow the real arguments. 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. +the function itself. You must call \fIcurl_formfree(3)\fP after the form post +has been done to free the resources. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. First, there are some basics you need to understand about multipart/formdata posts. Each part consists of at least a NAME and a CONTENTS part. If the part -is made for file upload, there are also a stored CONTENT-TYPE and a -FILENAME. Below here, we'll discuss on what options you use to set these -properties in the parts you want to add to your post. +is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME. +Below, we'll discuss what options you use to set these properties in the +parts you want to add to your post. + +The options listed first are for making normal parts. The options from +\fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload +parts. + .SH OPTIONS + .IP CURLFORM_COPYNAME -followed by string is used to set the name of this part. libcurl copies the -given data, so your application doesn't need to keep it around after this -function call. If the name isn't zero terminated properly, or if you'd like it -to contain zero bytes, you need to set the length of the name with -\fBCURLFORM_NAMELENGTH\fP. +followed by a string which provides the \fIname\fP of this part. libcurl +copies the string so your application doesn't need to keep it around after +this function call. If the name isn't null terminated, or if you'd +like it to contain zero bytes, you must set its length with +\fBCURLFORM_NAMELENGTH\fP. The copied data will be freed by +\fIcurl_formfree(3)\fP. .IP CURLFORM_PTRNAME -followed by a string is used for the name of this part. libcurl will use the -pointer and refer to the data in your application, you must make sure it -remains until curl no longer needs it. If the name isn't zero terminated -properly, or if you'd like it to contain zero bytes, you need to set the -length of the name with \fBCURLFORM_NAMELENGTH\fP. +followed by a string which provides the \fIname\fP of this part. libcurl +will use the pointer and refer to the data in your application, so you +must make sure it remains until curl no longer needs it. If the name +isn't null terminated, or if you'd like it to contain zero +bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. .IP CURLFORM_COPYCONTENTS -followed by a string is used for the contents of this part, the actual data to -send away. libcurl copies the given data, so your application doesn't need to -keep it around after this function call. If the data isn't zero terminated -properly, or if you'd like it to contain zero bytes, you need to set the -length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. +followed by a pointer to the contents of this part, the actual data +to send away. libcurl copies the provided data, so your application doesn't +need to keep it around after this function call. If the data isn't null +terminated, or if you'd like it to contain zero bytes, you must +set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied +data will be freed by \fIcurl_formfree(3)\fP. .IP CURLFORM_PTRCONTENTS -followed by a string is used for the contents of this part, the actual data to -send away. libcurl will use the pointer and refer to the data in your -application, you must make sure it remains until curl no longer needs it. If -the data isn't zero terminated properly, or if you'd like it to contain zero -bytes, you need to set the length of the name with -\fBCURLFORM_CONTENTSLENGTH\fP. +followed by a pointer to the contents of this part, the actual data +to send away. libcurl will use the pointer and refer to the data in your +application, so you must make sure it remains until curl no longer needs it. +If the data isn't null terminated, or if you'd like it to contain zero bytes, +you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. .IP CURLFORM_CONTENTSLENGTH -followed by a long setting the length of the contents. +followed by a long giving the length of the contents. .IP CURLFORM_FILECONTENT -followed by a file name, makes that file read and the contents will be used in -as data in this part. +followed by a filename, causes that file to be read and its contents used +as data in this part. This part does \fInot\fP automatically become a file +upload part simply because its data was read from a file. .IP CURLFORM_FILE -followed by a file name, makes this part a file upload part. It sets the file -name field to the actual file name used here, it gets the contents of the file -and passes as data and sets the content-type if the given file match one of -the new internally known file extension. For \fBCURLFORM_FILE\fP the user may -send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP -arguments each followed by the filename (and each CURLFORM_FILE is allowed to -have a CURLFORM_CONTENTTYPE). +followed by a filename, makes this part a file upload part. It sets the +\fIfilename\fP field to the basename of the provided filename, it reads the +contents of the file and passes them as data and sets the content-type if the +given file match one of the internally known file extensions. For +\fBCURLFORM_FILE\fP the user may send one or more files in one part by +providing multiple \fBCURLFORM_FILE\fP arguments each followed by the +filename (and each CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE). .IP CURLFORM_CONTENTTYPE -followed by a pointer to a string with a content-type will make curl use this -given content-type for this file upload part, possibly instead of an +is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a +string which provides the content-type for this part, possibly instead of an internally chosen one. .IP CURLFORM_FILENAME -followed by a pointer to a string to a name, will make libcurl use the given -name in the file upload part, instead of the actual file name given to -\fICURLFORM_FILE\fP. +is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a +string, it tells libcurl to use the given string as the \fIfilename\fP in the +file upload part instead of the actual file name. .IP CURLFORM_BUFFER -followed by a string, tells libcurl that a buffer is to be used to upload data -instead of using a file. The given string is used as the value of the file -name field in the content header. +is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It +tells libcurl that the file contents are already present in a buffer. The +parameter is a string which provides the \fIfilename\fP field in the content +header. .IP CURLFORM_BUFFERPTR -followed by a pointer to a data area, tells libcurl the address of the buffer -containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The -buffer containing this data must not be freed until after +is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer +to the buffer to be uploaded. This buffer must not be freed until after \fIcurl_easy_cleanup(3)\fP is called. You must also use -\fICURLFORM_BUFFERLENGTH\fP to set the length of the given buffer area. +\fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer. .IP CURLFORM_BUFFERLENGTH -followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area, -tells libcurl the length of the buffer to upload. +is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a +long which gives the length of the buffer. .IP CURLFORM_ARRAY Another possibility to send options to curl_formadd() is the -- cgit v1.2.1 From a83b5d1b675442d384b46a8fb8404e46c9e5f449 Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Mon, 15 Oct 2007 21:19:40 +0000 Subject: Mention first version with CURLOPT_COPYPOSTFIELDS. Don't confuse NUL with NULL. --- docs/libcurl/curl_formadd.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index a94dd506f..8508dd411 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -44,7 +44,7 @@ parts. .IP CURLFORM_COPYNAME followed by a string which provides the \fIname\fP of this part. libcurl copies the string so your application doesn't need to keep it around after -this function call. If the name isn't null terminated, or if you'd +this function call. If the name isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. The copied data will be freed by \fIcurl_formfree(3)\fP. @@ -53,7 +53,7 @@ like it to contain zero bytes, you must set its length with followed by a string which provides the \fIname\fP of this part. libcurl will use the pointer and refer to the data in your application, so you must make sure it remains until curl no longer needs it. If the name -isn't null terminated, or if you'd like it to contain zero +isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. .IP CURLFORM_COPYCONTENTS @@ -68,7 +68,7 @@ data will be freed by \fIcurl_formfree(3)\fP. followed by a pointer to the contents of this part, the actual data to send away. libcurl will use the pointer and refer to the data in your application, so you must make sure it remains until curl no longer needs it. -If the data isn't null terminated, or if you'd like it to contain zero bytes, +If the data isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. .IP CURLFORM_CONTENTSLENGTH -- cgit v1.2.1 From a2314225e02ea2f3bd49dc8557f2452846e49b19 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 31 Mar 2008 10:02:23 +0000 Subject: - Added CURLFORM_STREAM as a supported option to curl_formadd() to allow an application to provide data for a multipart with the read callback. Note that the size needs to be provided with CURLFORM_CONTENTSLENGTH when the stream option is used. This feature is verified by the new test case 554. This feature was sponsored by Xponaut. --- docs/libcurl/curl_formadd.3 | 29 +++++++++++------------------ 1 file changed, 11 insertions(+), 18 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 8508dd411..f3cea0054 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -38,9 +38,7 @@ parts you want to add to your post. The options listed first are for making normal parts. The options from \fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload parts. - .SH OPTIONS - .IP CURLFORM_COPYNAME followed by a string which provides the \fIname\fP of this part. libcurl copies the string so your application doesn't need to keep it around after @@ -48,14 +46,12 @@ this function call. If the name isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. The copied data will be freed by \fIcurl_formfree(3)\fP. - .IP CURLFORM_PTRNAME followed by a string which provides the \fIname\fP of this part. libcurl will use the pointer and refer to the data in your application, so you must make sure it remains until curl no longer needs it. If the name isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP. - .IP CURLFORM_COPYCONTENTS followed by a pointer to the contents of this part, the actual data to send away. libcurl copies the provided data, so your application doesn't @@ -63,57 +59,55 @@ need to keep it around after this function call. If the data isn't null terminated, or if you'd like it to contain zero bytes, you must set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied data will be freed by \fIcurl_formfree(3)\fP. - .IP CURLFORM_PTRCONTENTS followed by a pointer to the contents of this part, the actual data to send away. libcurl will use the pointer and refer to the data in your application, so you must make sure it remains until curl no longer needs it. If the data isn't NUL-terminated, or if you'd like it to contain zero bytes, you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. - .IP CURLFORM_CONTENTSLENGTH -followed by a long giving the length of the contents. - +followed by a long giving the length of the contents. Note that for +\fICURLFORM_STREAM\fP contents, this option is mandatory. .IP CURLFORM_FILECONTENT followed by a filename, causes that file to be read and its contents used as data in this part. This part does \fInot\fP automatically become a file upload part simply because its data was read from a file. - .IP CURLFORM_FILE followed by a filename, makes this part a file upload part. It sets the \fIfilename\fP field to the basename of the provided filename, it reads the contents of the file and passes them as data and sets the content-type if the given file match one of the internally known file extensions. For \fBCURLFORM_FILE\fP the user may send one or more files in one part by -providing multiple \fBCURLFORM_FILE\fP arguments each followed by the -filename (and each CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE). - +providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename +(and each \fICURLFORM_FILE\fP is allowed to have a +\fICURLFORM_CONTENTTYPE\fP). .IP CURLFORM_CONTENTTYPE is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a string which provides the content-type for this part, possibly instead of an internally chosen one. - .IP CURLFORM_FILENAME is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a string, it tells libcurl to use the given string as the \fIfilename\fP in the file upload part instead of the actual file name. - .IP CURLFORM_BUFFER is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It tells libcurl that the file contents are already present in a buffer. The parameter is a string which provides the \fIfilename\fP field in the content header. - .IP CURLFORM_BUFFERPTR is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer to the buffer to be uploaded. This buffer must not be freed until after \fIcurl_easy_cleanup(3)\fP is called. You must also use \fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer. - .IP CURLFORM_BUFFERLENGTH is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a long which gives the length of the buffer. - +.IP CURLFORM_STREAM +Tells libcurl to use the \fICURLOPT_READFUNCTION\fP callback to get data. The +parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on to the +read callback's fourth argument. If you want the part to look like a file +upload one, set the \fICURLFORM_FILENAME\fP parameter as well. (Option added +in libcurl 7.18.2) .IP CURLFORM_ARRAY Another possibility to send options to curl_formadd() is the \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as @@ -121,7 +115,6 @@ its value. Each curl_forms structure element has a CURLformoption and a char pointer. The final element in the array must be a CURLFORM_END. All available options can be used in an array, except the CURLFORM_ARRAY option itself! The last argument in such an array must always be \fBCURLFORM_END\fP. - .IP CURLFORM_CONTENTHEADER specifies extra headers for the form POST section. This takes a curl_slist prepared in the usual way using \fBcurl_slist_append\fP and appends the list -- cgit v1.2.1 From 60f0b4fffe3de8eb1a1fc3015c2f6643fdccb57a Mon Sep 17 00:00:00 2001 From: Dan Fandrich Date: Tue, 8 Jul 2008 21:16:18 +0000 Subject: Fixed test 554 to pass the torture test. --- docs/libcurl/curl_formadd.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index f3cea0054..e55c542f2 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -128,9 +128,9 @@ you've called \fIcurl_easy_cleanup(3)\fP for the curl handle. See example below. .SH RETURN VALUE -0 means everything was ok, non-zero means an error occurred as +0 means everything was ok, non-zero means an error occurred corresponding +to a CURL_FORMADD_* constant defined in .I -defines. .SH EXAMPLE .nf -- cgit v1.2.1 From 2f9038bf629335d0b23a7bde2e002bf587a2cd33 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Mon, 12 Jan 2009 21:22:51 +0000 Subject: Mohun Biswas clarified --- docs/libcurl/curl_formadd.3 | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index e55c542f2..190a6b20d 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -106,8 +106,9 @@ long which gives the length of the buffer. Tells libcurl to use the \fICURLOPT_READFUNCTION\fP callback to get data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on to the read callback's fourth argument. If you want the part to look like a file -upload one, set the \fICURLFORM_FILENAME\fP parameter as well. (Option added -in libcurl 7.18.2) +upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that when +using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be set +with the total expected length of the part. (Option added in libcurl 7.18.2) .IP CURLFORM_ARRAY Another possibility to send options to curl_formadd() is the \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as -- cgit v1.2.1 From 37d509f04fc9d54beb3185b866b8fe40a6af6cfb Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 4 Aug 2009 12:02:27 +0000 Subject: RFC1867 was updated by RFC2388 --- docs/libcurl/curl_formadd.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 190a6b20d..cf692ea52 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -13,7 +13,7 @@ curl_formadd - add a section to a multipart/formdata HTTP POST .ad .SH DESCRIPTION curl_formadd() is used to append sections when building a multipart/formdata -HTTP POST (sometimes referred to as rfc1867-style posts). Append one section at +HTTP POST (sometimes referred to as RFC2388-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 -- cgit v1.2.1 From a07bc79117971b96ebf3188c0a34a73ee0a3609b Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Sun, 14 Feb 2010 19:40:18 +0000 Subject: removed trailing whitespace --- docs/libcurl/curl_formadd.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index cf692ea52..906172227 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -152,7 +152,7 @@ to a CURL_FORMADD_* constant defined in /* Add simple name/content section */ curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", - CURLFORM_COPYCONTENTS, "content", CURLFORM_END); + CURLFORM_COPYCONTENTS, "content", CURLFORM_END); /* Add simple name/content/contenttype section */ curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode", -- cgit v1.2.1 From 46b112bcd439f4413925a7300d66a3e6f148765e Mon Sep 17 00:00:00 2001 From: Yang Tse Date: Tue, 16 Feb 2010 13:32:45 +0000 Subject: replaced tabs with spaces --- docs/libcurl/curl_formadd.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 906172227..90576ba9d 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -165,8 +165,8 @@ to a CURL_FORMADD_* constant defined in /* Add ptrname/ptrcontent section */ curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer, - CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH, - namelength, CURLFORM_END); + CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH, + namelength, CURLFORM_END); /* Add name/ptrcontent/contenttype section */ curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole", -- cgit v1.2.1 From 2309b4e330b96bc2e1f8e36b6184015e59544037 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 24 Mar 2010 11:02:54 +0100 Subject: remove the CVSish $Id$ lines --- docs/libcurl/curl_formadd.3 | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 90576ba9d..06757ed0a 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -1,6 +1,5 @@ .\" You can view this file with: .\" nroff -man [file] -.\" $Id$ .\" .TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME -- cgit v1.2.1 From 029136da6054a3b2d6cb36b3b4f2ed34f83e010a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 12 Mar 2011 00:14:32 +0100 Subject: source header: added to more files --- docs/libcurl/curl_formadd.3 | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index 06757ed0a..bba0c083e 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -1,6 +1,24 @@ -.\" You can view this file with: -.\" nroff -man [file] -.\" +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at http://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** .TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual" .SH NAME curl_formadd - add a section to a multipart/formdata HTTP POST -- cgit v1.2.1 From 8da5da9b6544337b8a675db092da201f279265d4 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 23 Jun 2011 09:31:12 +0200 Subject: curl_formfree: clarify which pointer to free --- docs/libcurl/curl_formadd.3 | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) (limited to 'docs/libcurl/curl_formadd.3') diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3 index bba0c083e..ce4df1e4b 100644 --- a/docs/libcurl/curl_formadd.3 +++ b/docs/libcurl/curl_formadd.3 @@ -30,18 +30,19 @@ curl_formadd - add a section to a multipart/formdata HTTP POST .ad .SH DESCRIPTION curl_formadd() is used to append sections when building a multipart/formdata -HTTP POST (sometimes referred to as RFC2388-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 faster. +HTTP POST (sometimes referred to as RFC2388-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 \fIcurl_formadd(3)\fP call and on repeated +invokes it should be left as set to allow repeated invokes to find the end of +the list faster. After the \fIlastitem\fP pointer follow the real arguments. -The pointers \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to +The pointers \fIfirstitem\fP and \fIlastitem\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(3)\fP after the form post -has been done to free the resources. +the function itself. You must call \fIcurl_formfree(3)\fP on the +\fIfirstitem\P after the form post has been done to free the resources. Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual. -- cgit v1.2.1