mucho fixed
This commit is contained in:
Daniel Stenberg
parent
eefdd67d22
commit
d6654bfe00
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user