mirror of
https://github.com/id-Software/DOOM-3.git
synced 2026-03-20 17:10:42 +01:00
hello world
This commit is contained in:
Timothee 'TTimo' Besset
209
neo/curl/docs/libcurl/curl_formadd.3
Normal file
209
neo/curl/docs/libcurl/curl_formadd.3
Normal file
@@ -0,0 +1,209 @@
|
||||
.\" You can view this file with:
|
||||
.\" nroff -man [file]
|
||||
.\" $Id: curl_formadd.3,v 1.8 2004/02/27 15:34:06 bagder Exp $
|
||||
.\"
|
||||
.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
|
||||
.B #include <curl/curl.h>
|
||||
.sp
|
||||
.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
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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. 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
|
||||
\fIcurl_easy_cleanup(3)\fP 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(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
|
||||
0 means everything was ok, non-zero means an error occurred as
|
||||
.I <curl/curl.h>
|
||||
defines.
|
||||
.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[] = "<HTML>test buffer</HTML>";
|
||||
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, "<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].option = CURLFORM_END;
|
||||
|
||||
/* Add a buffer to upload */
|
||||
curl_formadd(&post, &last,
|
||||
CURLFORM_COPYNAME, "name",
|
||||
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);
|
||||
/* 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)"
|
||||
Reference in New Issue
Block a user