docs/libcurl/curl_formadd.3

   1 .\" You can view this file with:
   2 .\" nroff -man [file]
   3 .\" $Id$
   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\fP after the form post has
  27 been done to free the resources again.
  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
  35 FILENAME. Below here, we'll discuss on what options you use to set these
  36 properties in the parts you want to add to your post.
  37 .SH OPTIONS
  38 .B CURLFORM_COPYNAME
  39 followed by string is used to set the name of this part. libcurl copies the
  40 given data, so your application doesn't need to keep it around after this
  41 function call. If the name isn't zero terminated properly, or if you'd like it
  42 to contain zero bytes, you need to set the length of the name with
  43 \fBCURLFORM_NAMELENGTH\fP.
  44
  45 .B CURLFORM_PTRNAME
  46 followed by a string is used for the name of this part. libcurl will use the
  47 pointer and refer to the data in your application, you must make sure it
  48 remains until curl no longer needs it. If the name isn't zero terminated
  49 properly, or if you'd like it to contain zero bytes, you need to set the
  50 length of the name with \fBCURLFORM_NAMELENGTH\fP.
  51
  52 .B CURLFORM_COPYCONTENTS
  53 followed by a string is used for the contents of this part, the actual data to
  54 send away. libcurl copies the given data, so your application doesn't need to
  55 keep it around after this function call. If the data isn't zero terminated
  56 properly, or if you'd like it to contain zero bytes, you need to set the
  57 length of the name with \fBCURLFORM_CONTENTSLENGTH\fP.
  58
  59 .B CURLFORM_PTRCONTENTS
  60 followed by a string is used for the contents of this part, the actual data to
  61 send away. libcurl will use the pointer and refer to the data in your
  62 application, you must make sure it remains until curl no longer needs it. If
  63 the data isn't zero terminated properly, or if you'd like it to contain zero
  64 bytes, you need to set the length of the name with
  65 \fBCURLFORM_CONTENTSLENGTH\fP.
  66
  67 .B CURLFORM_FILECONTENT
  68 followed by a file name, makes that file read and the contents will be used in
  69 as data in this part.
  70
  71 .B CURLFORM_FILE
  72 followed by a file name, makes this part a file upload part. It sets the file
  73 name field to the actual file name used here, it gets the contents of the file
  74 and passes as data and sets the content-type if the given file match one of
  75 the new internally known file extension.  For \fBCURLFORM_FILE\fP the user may
  76 send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP
  77 arguments each followed by the filename (and each CURLFORM_FILE is allowed to
  78 have a CURLFORM_CONTENTTYPE).
  79
  80 .B CURLFORM_CONTENTTYPE
  81 followed by a pointer to a string with a content-type will make curl use this
  82 given content-type for this file upload part, possibly instead of an
  83 internally chosen one.
  84
  85 .B CURLFORM_FILENAME
  86 followed by a pointer to a string to a name, will make libcurl use the given
  87 name in the file upload part, instead of the actual file name given to
  88 \fICURLFORM_FILE\fP.
  89
  90 .B BCURLFORM_BUFFER
  91 followed by a string, tells libcurl that a buffer is to be used to upload data
  92 instead of using a file. The given string is used as the value of the file
  93 name field in the content header.
  94
  95 .B CURLFORM_BUFFERPTR
  96 followed by a pointer to a data area, tells libcurl the address of the buffer
  97 containing data to upload (as indicated with \fICURLFORM_BUFFER\fP). The
  98 buffer containing this data must not be freed until after
  99 \fIcurl_easy_cleanup(3)\fP is called.
 100
 101 .B CURLFORM_BUFFERLENGTH
 102 followed by a long with the size of the \fICURLFORM_BUFFERPTR\fP data area,
 103 tells libcurl the length of the buffer to upload.
 104
 105 .B CURLFORM_ARRAY
 106 Another possibility to send options to curl_formadd() is the
 107 \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
 108 its value. Each curl_forms structure element has a CURLformoption and a char
 109 pointer. The final element in the array must be a CURLFORM_END. All available
 110 options can be used in an array, except the CURLFORM_ARRAY option itself!  The
 111 last argument in such an array must always be \fBCURLFORM_END\fP.
 112
 113 .B CURLFORM_CONTENTHEADER
 114 specifies extra headers for the form POST section.  This takes a curl_slist
 115 prepared in the usual way using \fBcurl_slist_append\fP and appends the list
 116 of headers to those libcurl automatically generates. The list must exist while
 117 the POST occurs, if you free it before the post completes you may experience
 118 problems.
 119
 120 When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
 121 the \fICURLOPT_HTTPPOST\fP option), you must not free the list until after
 122 you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
 123
 124 See example below.
 125 .SH RETURN VALUE
 126 0 means everything was ok, non-zero means an error occurred as
 127 .I <curl/curl.h>
 128 defines.
 129 .SH EXAMPLE
 130 .nf
 131
 132  struct HttpPost* post = NULL;
 133  struct HttpPost* last = NULL;
 134  char namebuffer[] = "name buffer";
 135  long namelength = strlen(namebuffer);
 136  char buffer[] = "test buffer";
 137  char htmlbuffer[] = "<HTML>test buffer</HTML>";
 138  long htmlbufferlength = strlen(htmlbuffer);
 139  struct curl_forms forms[3];
 140  char file1[] = "my-face.jpg";
 141  char file2[] = "your-face.jpg";
 142  /* add null character into htmlbuffer, to demonstrate that
 143     transfers of buffers containing null characters actually work
 144  */
 145  htmlbuffer[8] = '\\0';
 146
 147  /* Add simple name/content section */
 148  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
 149               CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
 150
 151  /* Add simple name/content/contenttype section */
 152  curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
 153               CURLFORM_COPYCONTENTS, "<HTML></HTML>",
 154               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
 155
 156  /* Add name/ptrcontent section */
 157  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
 158               CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
 159
 160  /* Add ptrname/ptrcontent section */
 161  curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
 162               CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
 163               namelength, CURLFORM_END);
 164
 165  /* Add name/ptrcontent/contenttype section */
 166  curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
 167               CURLFORM_PTRCONTENTS, htmlbuffer,
 168               CURLFORM_CONTENTSLENGTH, htmlbufferlength,
 169               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
 170
 171  /* Add simple file section */
 172  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
 173               CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
 174
 175  /* Add file/contenttype section */
 176  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
 177               CURLFORM_FILE, "my-face.jpg",
 178               CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
 179
 180  /* Add two file section */
 181  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
 182               CURLFORM_FILE, "my-face.jpg",
 183               CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
 184
 185  /* Add two file section using CURLFORM_ARRAY */
 186  forms[0].option = CURLFORM_FILE;
 187  forms[0].value  = file1;
 188  forms[1].option = CURLFORM_FILE;
 189  forms[1].value  = file2;
 190  forms[2].option  = CURLFORM_END;
 191
 192  /* Add a buffer to upload */
 193  curl_formadd(&post, &last,
 194               CURLFORM_COPYNAME, "name",
 195               CURLFORM_BUFFER, "data",
 196               CURLFORM_BUFFERPTR, record,
 197               CURLFORM_BUFFERLENGTH, record_length,
 198               CURLFORM_END);
 199
 200  /* no option needed for the end marker */
 201  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
 202               CURLFORM_ARRAY, forms, CURLFORM_END);
 203  /* Add the content of a file as a normal post text value */
 204  curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
 205               CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
 206  /* Set the form info */
 207  curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
 208
 209 .SH "SEE ALSO"
 210 .BR curl_easy_setopt "(3), "
 211 .BR curl_formfree "(3)"