mingw/share/man/man3/curl_formadd.3

   1 .\" You can view this file with:
   2 .\" nroff -man [file]
   3 .\" $Id: curl_formadd.3,v 1.19 2009-01-12 21:22:51 bagder 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. Note that when
 110 using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be set
 111 with the total expected length of the part. (Option added in libcurl 7.18.2)
 112 .IP CURLFORM_ARRAY
 113 Another possibility to send options to curl_formadd() is the
 114 \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as
 115 its value. Each curl_forms structure element has a CURLformoption and a char
 116 pointer. The final element in the array must be a CURLFORM_END. All available
 117 options can be used in an array, except the CURLFORM_ARRAY option itself!  The
 118 last argument in such an array must always be \fBCURLFORM_END\fP.
 119 .IP CURLFORM_CONTENTHEADER
 120 specifies extra headers for the form POST section.  This takes a curl_slist
 121 prepared in the usual way using \fBcurl_slist_append\fP and appends the list
 122 of headers to those libcurl automatically generates. The list must exist while
 123 the POST occurs, if you free it before the post completes you may experience
 124 problems.
 125
 126 When you've passed the HttpPost pointer to \fIcurl_easy_setopt(3)\fP (using
 127 the \fICURLOPT_HTTPPOST\fP option), you must not free the list until after
 128 you've called \fIcurl_easy_cleanup(3)\fP for the curl handle.
 129
 130 See example below.
 131 .SH RETURN VALUE
 132 0 means everything was ok, non-zero means an error occurred corresponding
 133 to a CURL_FORMADD_* constant defined in
 134 .I <curl/curl.h>
 135 .SH EXAMPLE
 136 .nf
 137
 138  struct curl_httppost* post = NULL;
 139  struct curl_httppost* last = NULL;
 140  char namebuffer[] = "name buffer";
 141  long namelength = strlen(namebuffer);
 142  char buffer[] = "test buffer";
 143  char htmlbuffer[] = "<HTML>test buffer</HTML>";
 144  long htmlbufferlength = strlen(htmlbuffer);
 145  struct curl_forms forms[3];
 146  char file1[] = "my-face.jpg";
 147  char file2[] = "your-face.jpg";
 148  /* add null character into htmlbuffer, to demonstrate that
 149     transfers of buffers containing null characters actually work
 150  */
 151  htmlbuffer[8] = '\\0';
 152
 153  /* Add simple name/content section */
 154  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
 155               CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
 156
 157  /* Add simple name/content/contenttype section */
 158  curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
 159               CURLFORM_COPYCONTENTS, "<HTML></HTML>",
 160               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
 161
 162  /* Add name/ptrcontent section */
 163  curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
 164               CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
 165
 166  /* Add ptrname/ptrcontent section */
 167  curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
 168               CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
 169               namelength, CURLFORM_END);
 170
 171  /* Add name/ptrcontent/contenttype section */
 172  curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
 173               CURLFORM_PTRCONTENTS, htmlbuffer,
 174               CURLFORM_CONTENTSLENGTH, htmlbufferlength,
 175               CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
 176
 177  /* Add simple file section */
 178  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
 179               CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
 180
 181  /* Add file/contenttype section */
 182  curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
 183               CURLFORM_FILE, "my-face.jpg",
 184               CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
 185
 186  /* Add two file section */
 187  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
 188               CURLFORM_FILE, "my-face.jpg",
 189               CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
 190
 191  /* Add two file section using CURLFORM_ARRAY */
 192  forms[0].option = CURLFORM_FILE;
 193  forms[0].value  = file1;
 194  forms[1].option = CURLFORM_FILE;
 195  forms[1].value  = file2;
 196  forms[2].option  = CURLFORM_END;
 197
 198  /* Add a buffer to upload */
 199  curl_formadd(&post, &last,
 200               CURLFORM_COPYNAME, "name",
 201               CURLFORM_BUFFER, "data",
 202               CURLFORM_BUFFERPTR, record,
 203               CURLFORM_BUFFERLENGTH, record_length,
 204               CURLFORM_END);
 205
 206  /* no option needed for the end marker */
 207  curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
 208               CURLFORM_ARRAY, forms, CURLFORM_END);
 209  /* Add the content of a file as a normal post text value */
 210  curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
 211               CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
 212  /* Set the form info */
 213  curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
 214
 215 .SH "SEE ALSO"
 216 .BR curl_easy_setopt "(3), "
 217 .BR curl_formfree "(3)"