docs/libcurl/curl_formadd.3

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