1curl_formadd(3)                 libcurl Manual                 curl_formadd(3)
2
3
4

NAME

6       curl_formadd - add a section to a multipart/formdata HTTP POST
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       CURLFORMcode  curl_formadd(struct  curl_httppost  **  firstitem, struct
12       curl_httppost ** lastitem, ...);
13

DESCRIPTION

15       curl_formadd() is used  to  append  sections  when  building  a  multi‐
16       part/formdata HTTP POST (sometimes referred to as RFC2388-style posts).
17       Append one section at a time until you've added all  the  sections  you
18       want  included  and then you pass the firstitem pointer as parameter to
19       CURLOPT_HTTPPOST.  lastitem is set after  each  call  and  on  repeated
20       invokes  it should be left as set to allow repeated invokes to find the
21       end of the list faster.
22
23       After the lastitem pointer follow the real arguments.
24
25       The pointers *firstitem and *lastitem should both be pointing  to  NULL
26       in  the first call to this function. All list-data will be allocated by
27       the function itself. You must call curl_formfree(3) after the form post
28       has been done to free the resources.
29
30       Using  POST  with  HTTP 1.1 implies the use of a "Expect: 100-continue"
31       header.  You can disable this header with CURLOPT_HTTPHEADER as usual.
32
33       First, there are some  basics  you  need  to  understand  about  multi‐
34       part/formdata  posts.  Each part consists of at least a NAME and a CON‐
35       TENTS part. If the part is made for  file  upload,  there  are  also  a
36       stored  CONTENT-TYPE and a FILENAME.  Below, we'll discuss what options
37       you use to set these properties in the parts you want to  add  to  your
38       post.
39
40       The  options listed first are for making normal parts. The options from
41       CURLFORM_FILE through CURLFORM_BUFFERLENGTH are for file upload parts.
42

OPTIONS

44       CURLFORM_COPYNAME
45              followed by a string which  provides  the  name  of  this  part.
46              libcurl  copies  the  string so your application doesn't need to
47              keep it around after this function call. If the name isn't  NUL-
48              terminated,  or if you'd like it to contain zero bytes, you must
49              set its length with CURLFORM_NAMELENGTH. The copied data will be
50              freed by curl_formfree(3).
51
52       CURLFORM_PTRNAME
53              followed  by  a  string  which  provides  the name of this part.
54              libcurl will use the pointer and  refer  to  the  data  in  your
55              application,  so  you  must  make  sure it remains until curl no
56              longer needs it. If the name isn't NUL-terminated, or  if  you'd
57              like  it  to  contain  zero  bytes, you must set its length with
58              CURLFORM_NAMELENGTH.
59
60       CURLFORM_COPYCONTENTS
61              followed by a pointer to the contents of this part,  the  actual
62              data  to  send  away.  libcurl copies the provided data, so your
63              application doesn't need to keep it around after  this  function
64              call.  If the data isn't null terminated, or if you'd like it to
65              contain zero bytes, you must set the length  of  the  name  with
66              CURLFORM_CONTENTSLENGTH.  The  copied  data  will  be  freed  by
67              curl_formfree(3).
68
69       CURLFORM_PTRCONTENTS
70              followed by a pointer to the contents of this part,  the  actual
71              data to send away. libcurl will use the pointer and refer to the
72              data in your application, so you must make sure it remains until
73              curl  no  longer needs it.  If the data isn't NUL-terminated, or
74              if you'd like it to contain zero bytes, you must set its  length
75              with CURLFORM_CONTENTSLENGTH.
76
77       CURLFORM_CONTENTSLENGTH
78              followed  by a long giving the length of the contents. Note that
79              for CURLFORM_STREAM contents, this option is mandatory.
80
81       CURLFORM_FILECONTENT
82              followed by a filename, causes that file to be read and its con‐
83              tents  used  as  data in this part. This part does not automati‐
84              cally become a file upload part simply because its data was read
85              from a file.
86
87       CURLFORM_FILE
88              followed  by  a filename, makes this part a file upload part. It
89              sets the filename field to the basename of  the  provided  file‐
90              name,  it reads the contents of the file and passes them as data
91              and sets the content-type if the given file  match  one  of  the
92              internally  known  file  extensions.  For CURLFORM_FILE the user
93              may send one or more files in one  part  by  providing  multiple
94              CURLFORM_FILE  arguments each followed by the filename (and each
95              CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE).
96
97       CURLFORM_CONTENTTYPE
98              is used in combination with CURLFORM_FILE. Followed by a pointer
99              to  a string which provides the content-type for this part, pos‐
100              sibly instead of an internally chosen one.
101
102       CURLFORM_FILENAME
103              is used in combination with CURLFORM_FILE. Followed by a pointer
104              to  a  string,  it  tells libcurl to use the given string as the
105              filename in the file upload part  instead  of  the  actual  file
106              name.
107
108       CURLFORM_BUFFER
109              is  used  for  custom  file  upload  parts  without use of CURL‐
110              FORM_FILE.  It tells libcurl that the file contents are  already
111              present  in  a buffer.  The parameter is a string which provides
112              the filename field in the content header.
113
114       CURLFORM_BUFFERPTR
115              is used in combination with CURLFORM_BUFFER. The parameter is  a
116              pointer  to  the  buffer to be uploaded. This buffer must not be
117              freed until after curl_easy_cleanup(3) is called. You must  also
118              use CURLFORM_BUFFERLENGTH to set the number of bytes in the buf‐
119              fer.
120
121       CURLFORM_BUFFERLENGTH
122              is used in combination with CURLFORM_BUFFER. The parameter is  a
123              long which gives the length of the buffer.
124
125       CURLFORM_STREAM
126              Tells  libcurl  to  use the CURLOPT_READFUNCTION callback to get
127              data. The parameter you pass to CURLFORM_STREAM is  the  pointer
128              passed  on  to  the read callback's fourth argument. If you want
129              the part to look like a file upload one, set the  CURLFORM_FILE‐
130              NAME  parameter  as  well. Note that when using CURLFORM_STREAM,
131              CURLFORM_CONTENTSLENGTH must also be set with the total expected
132              length of the part. (Option added in libcurl 7.18.2)
133
134       CURLFORM_ARRAY
135              Another  possibility  to  send  options to curl_formadd() is the
136              CURLFORM_ARRAY option, that passes  a  struct  curl_forms  array
137              pointer  as  its  value. Each curl_forms structure element has a
138              CURLformoption and a char pointer.  The  final  element  in  the
139              array  must be a CURLFORM_END. All available options can be used
140              in an array, except the CURLFORM_ARRAY option itself!  The  last
141              argument in such an array must always be CURLFORM_END.
142
143       CURLFORM_CONTENTHEADER
144              specifies extra headers for the form POST section.  This takes a
145              curl_slist prepared in the usual way using curl_slist_append and
146              appends  the list of headers to those libcurl automatically gen‐
147              erates. The list must exist while the POST occurs, if  you  free
148              it before the post completes you may experience problems.
149
150              When  you've  passed the HttpPost pointer to curl_easy_setopt(3)
151              (using the CURLOPT_HTTPPOST option), you must not free the  list
152              until after you've called curl_easy_cleanup(3) for the curl han‐
153              dle.
154
155              See example below.
156

RETURN VALUE

158       0 means everything was ok, non-zero means an error occurred correspond‐
159       ing to a CURL_FORMADD_* constant defined in <curl/curl.h>
160

EXAMPLE

162        struct curl_httppost* post = NULL;
163        struct curl_httppost* last = NULL;
164        char namebuffer[] = "name buffer";
165        long namelength = strlen(namebuffer);
166        char buffer[] = "test buffer";
167        char htmlbuffer[] = "<HTML>test buffer</HTML>";
168        long htmlbufferlength = strlen(htmlbuffer);
169        struct curl_forms forms[3];
170        char file1[] = "my-face.jpg";
171        char file2[] = "your-face.jpg";
172        /* add null character into htmlbuffer, to demonstrate that
173           transfers of buffers containing null characters actually work
174        */
175        htmlbuffer[8] = '\0';
176
177        /* Add simple name/content section */
178        curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
179                     CURLFORM_COPYCONTENTS, "content", CURLFORM_END);
180
181        /* Add simple name/content/contenttype section */
182        curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
183                     CURLFORM_COPYCONTENTS, "<HTML></HTML>",
184                     CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
185
186        /* Add name/ptrcontent section */
187        curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
188                     CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);
189
190        /* Add ptrname/ptrcontent section */
191        curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
192                  CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
193                  namelength, CURLFORM_END);
194
195        /* Add name/ptrcontent/contenttype section */
196        curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
197                     CURLFORM_PTRCONTENTS, htmlbuffer,
198                     CURLFORM_CONTENTSLENGTH, htmlbufferlength,
199                     CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);
200
201        /* Add simple file section */
202        curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
203                     CURLFORM_FILE, "my-face.jpg", CURLFORM_END);
204
205        /* Add file/contenttype section */
206        curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
207                     CURLFORM_FILE, "my-face.jpg",
208                     CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);
209
210        /* Add two file section */
211        curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
212                     CURLFORM_FILE, "my-face.jpg",
213                     CURLFORM_FILE, "your-face.jpg", CURLFORM_END);
214
215        /* Add two file section using CURLFORM_ARRAY */
216        forms[0].option = CURLFORM_FILE;
217        forms[0].value  = file1;
218        forms[1].option = CURLFORM_FILE;
219        forms[1].value  = file2;
220        forms[2].option  = CURLFORM_END;
221
222        /* Add a buffer to upload */
223        curl_formadd(&post, &last,
224                     CURLFORM_COPYNAME, "name",
225                     CURLFORM_BUFFER, "data",
226                     CURLFORM_BUFFERPTR, record,
227                     CURLFORM_BUFFERLENGTH, record_length,
228                     CURLFORM_END);
229
230        /* no option needed for the end marker */
231        curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
232                     CURLFORM_ARRAY, forms, CURLFORM_END);
233        /* Add the content of a file as a normal post text value */
234        curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
235                     CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
236        /* Set the form info */
237        curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);
238
239

SEE ALSO

241       curl_easy_setopt(3), curl_formfree(3)
242
243
244
245libcurl 7.9.8                    24 June 2002                  curl_formadd(3)
Impressum