docs/libcurl/curl_formadd.3

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