CMakeLua/Utilities/cmcurl-7.19.0/docs/libcurl/curl_formadd.3

   1 .\" You can view this file with:
   2 .\" nroff -man [file]
   3 .\" $Id: curl_formadd.3,v 1.1.1.1 2008-09-23 16:32:05 hoffman Exp $
   4 .\"
   5 .TH curl_formadd 3 "24 June 2002" "libcurl 7.9.8" "libcurl Manual"
   6 .SH NAME
   7 curl_formadd - add a section to a multipart/formdata HTTP POST
   8 .SH SYNOPSIS
   9 .B #include <curl/curl.h>
  10 .sp
  11 .BI "CURLFORMcode curl_formadd(struct curl_httppost ** " firstitem,
  12 .BI "struct curl_httppost ** " lastitem, " ...);"
  13 .ad
  14 .SH DESCRIPTION
  15 curl_formadd() is used to append sections when building a multipart/formdata
  16 HTTP POST (sometimes referred to as rfc1867-style posts). Append one section at
  17 a time until you've added all the sections you want included and then you pass
  18 the \fIfirstitem\fP pointer as parameter to \fBCURLOPT_HTTPPOST\fP.
  19 \fIlastitem\fP is set after each call and on repeated invokes it should be
  20 left as set to allow repeated invokes to find the end of the list faster.
  21
  22 After the \fIlastitem\fP pointer follow the real arguments.
  23
  24 The pointers \fI*firstitem\fP and \fI*lastitem\fP should both be pointing to
  25 NULL in the first call to this function. All list-data will be allocated by
  26 the function itself. You must call \fIcurl_formfree(3)\fP after the form post
  27 has been done to free the resources.
  28
  29 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
  30 You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual.
  31
  32 First, there are some basics you need to understand about multipart/formdata
  33 posts. Each part consists of at least a NAME and a CONTENTS part. If the part
  34 is made for file upload, there are also a stored CONTENT-TYPE and a FILENAME.
  35 Below, we'll discuss what options you use to set these properties in the
  36 parts you want to add to your post.
  37
  38 The options listed first are for making normal parts. The options from
  39 \fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload
  40 parts.
  41 .SH OPTIONS
  42 .IP CURLFORM_COPYNAME
  43 followed by a string which provides the \fIname\fP of this part. libcurl
  44 copies the string so your application doesn't need to keep it around after
  45 this function call. If the name isn't NUL-terminated, or if you'd
  46 like it to contain zero bytes, you must set its length with
  47 \fBCURLFORM_NAMELENGTH\fP. The copied data will be freed by
  48 \fIcurl_formfree(3)\fP.
  49 .IP CURLFORM_PTRNAME
  50 followed by a string which provides the \fIname\fP of this part. libcurl
  51 will use the pointer and refer to the data in your application, so you
  52 must make sure it remains until curl no longer needs it. If the name
  53 isn't NUL-terminated, or if you'd like it to contain zero
  54 bytes, you must set its length with \fBCURLFORM_NAMELENGTH\fP.
  55 .IP CURLFORM_COPYCONTENTS
  56 followed by a pointer to the contents of this part, the actual data
  57 to send away. libcurl copies the provided data, so your application doesn't
  58 need to keep it around after this function call. If the data isn't null
  59 terminated, or if you'd like it to contain zero bytes, you must
  60 set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied
  61 data will be freed by \fIcurl_formfree(3)\fP.
  62 .IP CURLFORM_PTRCONTENTS
  63 followed by a pointer to the contents of this part, the actual data
  64 to send away. libcurl will use the pointer and refer to the data in your
  65 application, so you must make sure it remains until curl no longer needs it.
  66 If the data isn't NUL-terminated, or if you'd like it to contain zero bytes,
  67 you must set its length  with \fBCURLFORM_CONTENTSLENGTH\fP.
  68 .IP CURLFORM_CONTENTSLENGTH
  69 followed by a long giving the length of the contents. Note that for
  70 \fICURLFORM_STREAM\fP contents, this option is mandatory.
  71 .IP CURLFORM_FILECONTENT
  72 followed by a filename, causes that file to be read and its contents used
  73 as data in this part. This part does \fInot\fP automatically become a file
  74 upload part simply because its data was read from a file.
  75 .IP CURLFORM_FILE
  76 followed by a filename, makes this part a file upload part. It sets the
  77 \fIfilename\fP field to the basename of the provided filename, it reads the
  78 contents of the file and passes them as data and sets the content-type if the
  79 given file match one of the internally known file extensions.  For
  80 \fBCURLFORM_FILE\fP the user may send one or more files in one part by
  81 providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
  82 (and each \fICURLFORM_FILE\fP is allowed to have a
  83 \fICURLFORM_CONTENTTYPE\fP).
  84 .IP CURLFORM_CONTENTTYPE
  85 is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
  86 string which provides the content-type for this part, possibly instead of an
  87 internally chosen one.
  88 .IP CURLFORM_FILENAME
  89 is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
  90 string, it tells libcurl to use the given string as the \fIfilename\fP in the
  91 file upload part instead of the actual file name.
  92 .IP CURLFORM_BUFFER
  93 is used for custom file upload parts without use of \fICURLFORM_FILE\fP.  It
  94 tells libcurl that the file contents are already present in a buffer.  The
  95 parameter is a string which provides the \fIfilename\fP field in the content
  96 header.
  97 .IP CURLFORM_BUFFERPTR
  98 is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
  99 to the buffer to be uploaded. This buffer must not be freed until after
 100 \fIcurl_easy_cleanup(3)\fP is called. You must also use
 101 \fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
 102 .IP CURLFORM_BUFFERLENGTH
 103 is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
 104 long which gives the length of the buffer.
 105 .IP CURLFORM_STREAM
 106 Tells libcurl to use the \fICURLOPT_READFUNCTION\fP callback to get data. The
 107 parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on to the
 108 read callback's fourth argument. If you want the part to look like a file
 109 upload one, set the \fICURLFORM_FILENAME\fP parameter as well. (Option added
 110 in libcurl 7.18.2)
 111 .IP CURLFORM_ARRAY
 112 Another possibility to send options to curl_formadd() is the
 113 \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
 114 its value. Each curl_forms structure element has a CURLformoption and a char
 115 pointer. The final element in the array must be a CURLFORM_END. All available
 116 options can be used in an array, except the CURLFORM_ARRAY option itself!  The
 117 last argument in such an array must always be \fBCURLFORM_END\fP.
 118 .IP CURLFORM_CONTENTHEADER
 119 specifies extra headers for the form POST section.  This takes a curl_slist
 120 prepared in the usual way using \fBcurl_slist_append\fP and appends the list
 121 of headers to those libcurl automatically generates. The list must exist while
 122 the POST occurs, if you free it before the post completes you may experience
 123 problems.
 124
 125 When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
 126 the \fICURLOPT_HTTPPOST\fP option), you must not free the list until after
 127 you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
 128
 129 See example below.
 130 .SH RETURN VALUE
 131 0 means everything was ok, non-zero means an error occurred corresponding
 132 to a CURL_FORMADD_* constant defined in
 133 .I <curl/curl.h>
 134 .SH EXAMPLE
 135 .nf
 136
 137  struct curl_httppost* post = NULL;
 138  struct curl_httppost* last = NULL;
 139  char namebuffer[] = "name buffer";
 140  long namelength = strlen(namebuffer);
 141  char buffer[] = "test buffer";
 142  char htmlbuffer[] = "<HTML>test buffer</HTML>";
 143  long htmlbufferlength = strlen(htmlbuffer);
 144  struct curl_forms forms[3];
 145  char file1[] = "my-face.jpg";
 146  char file2[] = "your-face.jpg";
 147  /* add null character into htmlbuffer, to demonstrate that
 148     transfers of buffers containing null characters actually work
 149  */
 150  htmlbuffer[8] = '\\0';
 151
 152  /* Add simple name/content section */
 153  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
 154               CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
 155
 156  /* Add simple name/content/contenttype section */
 157  curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
 158               CURLFORM_COPYCONTENTS, "<HTML></HTML>",
 159               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
 160
 161  /* Add name/ptrcontent section */
 162  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
 163               CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
 164
 165  /* Add ptrname/ptrcontent section */
 166  curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
 167               CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
 168               namelength, CURLFORM_END);
 169
 170  /* Add name/ptrcontent/contenttype section */
 171  curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
 172               CURLFORM_PTRCONTENTS, htmlbuffer,
 173               CURLFORM_CONTENTSLENGTH, htmlbufferlength,
 174               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
 175
 176  /* Add simple file section */
 177  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
 178               CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
 179
 180  /* Add file/contenttype section */
 181  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
 182               CURLFORM_FILE, "my-face.jpg",
 183               CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
 184
 185  /* Add two file section */
 186  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
 187               CURLFORM_FILE, "my-face.jpg",
 188               CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
 189
 190  /* Add two file section using CURLFORM_ARRAY */
 191  forms[0].option = CURLFORM_FILE;
 192  forms[0].value  = file1;
 193  forms[1].option = CURLFORM_FILE;
 194  forms[1].value  = file2;
 195  forms[2].option  = CURLFORM_END;
 196
 197  /* Add a buffer to upload */
 198  curl_formadd(&post, &last,
 199               CURLFORM_COPYNAME, "name",
 200               CURLFORM_BUFFER, "data",
 201               CURLFORM_BUFFERPTR, record,
 202               CURLFORM_BUFFERLENGTH, record_length,
 203               CURLFORM_END);
 204
 205  /* no option needed for the end marker */
 206  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
 207               CURLFORM_ARRAY, forms, CURLFORM_END);
 208  /* Add the content of a file as a normal post text value */
 209  curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
 210               CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
 211  /* Set the form info */
 212  curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
 213
 214 .SH "SEE ALSO"
 215 .BR curl_easy_setopt "(3), "
 216 .BR curl_formfree "(3)"