diff options
| -rw-r--r-- | docs/libcurl/curl_formadd.3 | 158 |
1 files changed, 92 insertions, 66 deletions
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 |