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
 109 The specified file needs to kept around until the associated transfer is done.
 110 .IP CURLFORM_FILE
 111 followed by a filename, makes this part a file upload part. It sets the
 112 \fIfilename\fP field to the basename of the provided filename, it reads the
 113 contents of the file and passes them as data and sets the content-type if the
 114 given file match one of the internally known file extensions.  For
 115 \fBCURLFORM_FILE\fP the user may send one or more files in one part by
 116 providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename
 117 (and each \fICURLFORM_FILE\fP is allowed to have a
 118 \fICURLFORM_CONTENTTYPE\fP).
 119
 120 The given upload file has to exist in its full in the file system already when
 121 the upload starts, as libcurl needs to read the correct file size beforehand.
 122
 123 The specified file needs to kept around until the associated transfer is done.
 124 .IP CURLFORM_CONTENTTYPE
 125 is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
 126 string which provides the content-type for this part, possibly instead of an
 127 internally chosen one.
 128 .IP CURLFORM_FILENAME
 129 is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a
 130 string, it tells libcurl to use the given string as the \fIfilename\fP in the
 131 file upload part instead of the actual file name.
 132 .IP CURLFORM_BUFFER
 133 is used for custom file upload parts without use of \fICURLFORM_FILE\fP.  It
 134 tells libcurl that the file contents are already present in a buffer.  The
 135 parameter is a string which provides the \fIfilename\fP field in the content
 136 header.
 137 .IP CURLFORM_BUFFERPTR
 138 is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer
 139 to the buffer to be uploaded. This buffer must not be freed until after
 140 \fIcurl_easy_cleanup(3)\fP is called. You must also use
 141 \fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer.
 142 .IP CURLFORM_BUFFERLENGTH
 143 is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a
 144 long which gives the length of the buffer.
 145 .IP CURLFORM_STREAM
 146 Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get
 147 data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on
 148 to the read callback's fourth argument. If you want the part to look like a
 149 file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that
 150 when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be
 151 set with the total expected length of the part unless the formpost is sent
 152 chunked encoded. (Option added in libcurl 7.18.2)
 153 .IP CURLFORM_ARRAY
 154 Another possibility to send options to curl_formadd() is the
 155 \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
 156 its value. Each curl_forms structure element has a CURLformoption and a char
 157 pointer. The final element in the array must be a CURLFORM_END. All available
 158 options can be used in an array, except the CURLFORM_ARRAY option itself!  The
 159 last argument in such an array must always be \fBCURLFORM_END\fP.
 160 .IP CURLFORM_CONTENTHEADER
 161 specifies extra headers for the form POST section.  This takes a curl_slist
 162 prepared in the usual way using \fBcurl_slist_append\fP and appends the list
 163 of headers to those libcurl automatically generates. The list must exist while
 164 the POST occurs, if you free it before the post completes you may experience
 165 problems.
 166
 167 When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
 168 the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after
 169 you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
 170
 171 See example below.
 172 .SH RETURN VALUE
 173 0 means everything was ok, non-zero means an error occurred corresponding
 174 to a CURL_FORMADD_* constant defined in
 175 .I <curl/curl.h>
 176 .SH EXAMPLE
 177 .nf
 178
 179  struct curl_httppost* post = NULL;
 180  struct curl_httppost* last = NULL;
 181  char namebuffer[] = "name buffer";
 182  long namelength = strlen(namebuffer);
 183  char buffer[] = "test buffer";
 184  char htmlbuffer[] = "<HTML>test buffer</HTML>";
 185  long htmlbufferlength = strlen(htmlbuffer);
 186  struct curl_forms forms[3];
 187  char file1[] = "my-face.jpg";
 188  char file2[] = "your-face.jpg";
 189  /* add null character into htmlbuffer, to demonstrate that
 190     transfers of buffers containing null characters actually work
 191  */
 192  htmlbuffer[8] = '\\0';
 193
 194  /* Add simple name/content section */
 195  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
 196               CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
 197
 198  /* Add simple name/content/contenttype section */
 199  curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
 200               CURLFORM_COPYCONTENTS, "<HTML></HTML>",
 201               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
 202
 203  /* Add name/ptrcontent section */
 204  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
 205               CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
 206
 207  /* Add ptrname/ptrcontent section */
 208  curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
 209               CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
 210               namelength, CURLFORM_END);
 211
 212  /* Add name/ptrcontent/contenttype section */
 213  curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
 214               CURLFORM_PTRCONTENTS, htmlbuffer,
 215               CURLFORM_CONTENTSLENGTH, htmlbufferlength,
 216               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
 217
 218  /* Add simple file section */
 219  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
 220               CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
 221
 222  /* Add file/contenttype section */
 223  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
 224               CURLFORM_FILE, "my-face.jpg",
 225               CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
 226
 227  /* Add two file section */
 228  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
 229               CURLFORM_FILE, "my-face.jpg",
 230               CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
 231
 232  /* Add two file section using CURLFORM_ARRAY */
 233  forms[0].option = CURLFORM_FILE;
 234  forms[0].value  = file1;
 235  forms[1].option = CURLFORM_FILE;
 236  forms[1].value  = file2;
 237  forms[2].option  = CURLFORM_END;
 238
 239  /* Add a buffer to upload */
 240  curl_formadd(&post, &last,
 241               CURLFORM_COPYNAME, "name",
 242               CURLFORM_BUFFER, "data",
 243               CURLFORM_BUFFERPTR, record,
 244               CURLFORM_BUFFERLENGTH, record_length,
 245               CURLFORM_END);
 246
 247  /* no option needed for the end marker */
 248  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
 249               CURLFORM_ARRAY, forms, CURLFORM_END);
 250  /* Add the content of a file as a normal post text value */
 251  curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
 252               CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
 253  /* Set the form info */
 254  curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
 255
 256 .SH "SEE ALSO"
 257 .BR curl_easy_setopt "(3), "
 258 .BR curl_formfree "(3)"