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


SYNOPSIS

       #include <curl/curl.h>

       CURLFORMcode curl_formadd(struct  HttpPost  **  firstitem,
       struct HttpPost ** lastitem, ...);


DESCRIPTION

       curl_formadd()  is used to append sections when building a
       multipart/formdata HTTP  POST  (sometimes  refered  to  as
       rfc1867-style  posts).  Append one section at a time until
       you've added all the sections you want included  and  then
       you  pass  the  firstitem  pointer  as  parameter  to CUR-
       LOPT_HTTPPOST.  lastitem is set after  each  call  and  on
       repeated  invokes  it  should  be  left  as  set  to allow
       repeated invokes to find the end of the list faster.

       After the lastitem pointer follow the real arguments.

       The pointers  *firstitem  and  *lastitem  should  both  be
       pointing  to  NULL in the first call to this function. All
       list-data will be allocated by the  function  itself.  You
       must  call curl_formfree after the form post has been done
       to free the resources again.

       First, there are some basics you need to understand  about
       multipart/formdata posts. Each part consists of at least a
       NAME and a CONTENTS part. If the part  is  made  for  file
       upload,  there  are also a stored CONTENT-TYPE and a FILE-
       NAME. Below here, we'll discuss on what options you use to
       set  these properties in the parts you want to add to your
       post.


OPTIONS

       CURLFORM_COPYNAME followed by string is used  to  set  the
       name  of this part. libcurl copies the given data, so your
       application doesn't need to  keep  it  around  after  this
       function call. If the name isn't zero terminated properly,
       or if you'd like it to contain zero bytes, you need to set
       the length of the name with CURLFORM_NAMELENGTH.

       CURLFORM_PTRNAME followed by a string is used for the name
       of this part. libcurl will use the pointer  and  refer  to
       the  data  in  your  application,  you  must  make sure it
       remains until curl no longer needs it. If the  name  isn't
       zero  terminated  properly, or if you'd like it to contain
       zero bytes, you need to set the length of  the  name  with
       CURLFORM_NAMELENGTH.

       CURLFORM_COPYCONTENTS followed by a string is used for the
       need to keep it around after this function  call.  If  the
       data  isn't  zero terminated properly, or if you'd like it
       to contain zero bytes, you need to set the length  of  the
       name with CURLFORM_CONTENTSLENGTH.

       CURLFORM_PTRCONTENTS  followed by a string is used for the
       contents of this part,  the  actual  data  to  send  away.
       libcurl will use the pointer and refer to the data in your
       application, you must make sure it remains until  curl  no
       longer  needs  it. If the data isn't zero terminated prop-
       erly, or if you'd like it to contain zero bytes, you  need
       to   set   the  length  of  the  name  with  CURLFORM_CON-
       TENTSLENGTH.

       CURLFORM_FILECONTENT followed by a file name,  makes  that
       file read and the contents will be used in as data in this
       part.

       CURLFORM_FILE followed by a file name, makes this  part  a
       file  upload  part.  It  sets  the  file name field to the
       actual file name used here, it gets the  contents  of  the
       file  and  passes as data and sets the content-type if the
       given file match one of  the  new  internally  known  file
       extension.   For  CURLFORM_FILE  the  user may send one or
       more files in one part by providing multiple CURLFORM_FILE
       arguments  each  followed  by the filename (and each CURL-
       FORM_FILE is allowed to have a CURLFORM_CONTENTTYPE).

       CURLFORM_CONTENTTYPE followed by a  pointer  to  a  string
       with a content-type will make curl use this given content-
       type for this file upload part,  possibly  instead  of  an
       internally chosen one.

       CURLFORM_FILENAME  followed  by a pointer to a string to a
       name, will make libcurl use the given  name  in  the  file
       upload part, intead of the actual file name given to CURL-
       FORM_FILE.

       BCURLFORM_BUFFER followed by a string, tells libcurl  that
       a  buffer  is to be used to upload data instead of using a
       file. The given string is used as the value  of  the  file
       name field in the content header.

       CURLFORM_BUFFERPTR  followed  by a pointer to a data area,
       tells libcurl the address of the buffer containing data to
       upload  (as  indicated  with  CURLFORM_BUFFER). The buffer
       containing  this  data  must  not  be  freed  until  after
       curl_easy_cleanup is called.

       CURLFORM_BUFFERLENGTH  followed by a long with the size of
       the CURLFORM_BUFFERPTR data area, tells libcurl the length
       of the buffer to upload.
       curl_formadd() is the CURLFORM_ARRAY option, that passes a
       struct   curl_forms  array  pointer  as  its  value.  Each
       curl_forms structure element has a  CURLformoption  and  a
       char  pointer.  The  final  element in the array must be a
       CURLFORM_END. All available options  can  be  used  in  an
       array,  except the CURLFORM_ARRAY option itself!  The last
       argument in such an array must always be CURLFORM_END.

       CURLFORM_CONTENTHEADER specifies  extra  headers  for  the
       form  POST  section.   This takes a curl_slist prepared in
       the usual way using curl_slist_append and appends the list
       of  headers  to those libcurl automatically generates. The
       list must exist while the POST  occurs,  if  you  free  it
       before the post completes you may experience problems.

       When    you've    passed    the    HttpPost   pointer   to
       curl_easy_setopt (using the CURLOPT_HTTPPOST option),  you
       must   not   free  the  list  until  after  you've  called
       curl_easy_cleanup for the curl handle.

       See example below.


RETURN VALUE

       0  means  everything  was  ok,  non-zero  means  an  error
       occurred as <curl/curl.h> defines.


EXAMPLE

        struct HttpPost* post = NULL;
        struct HttpPost* last = NULL;
        char namebuffer[] = "name buffer";
        long namelength = strlen(namebuffer);
        char buffer[] = "test buffer";
        char htmlbuffer[] = "<HTML>test buffer</HTML>";
        long htmlbufferlength = strlen(htmlbuffer);
        struct curl_forms forms[3];
        char file1[] = "my-face.jpg";
        char file2[] = "your-face.jpg";
        /* add null character into htmlbuffer, to demonstrate that
           transfers of buffers containing null characters actually work
        */
        htmlbuffer[8] = '\0';

        /* Add simple name/content section */
        curl_formadd(&post, &last, CURLFORM_COPYNAME, "name",
                     CURLFORM_COPYCONTENTS, "content", CURLFORM_END);

        /* Add simple name/content/contenttype section */
        curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode",
                     CURLFORM_COPYCONTENTS, "<HTML></HTML>",
                     CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);

        /* Add name/ptrcontent section */

        /* Add ptrname/ptrcontent section */
        curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer,
                  CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH,
                  namelength, CURLFORM_END);

        /* Add name/ptrcontent/contenttype section */
        curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole",
                     CURLFORM_PTRCONTENTS, htmlbuffer,
                     CURLFORM_CONTENTSLENGTH, htmlbufferlength,
                     CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END);

        /* Add simple file section */
        curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
                     CURLFORM_FILE, "my-face.jpg", CURLFORM_END);

        /* Add file/contenttype section */
        curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture",
                     CURLFORM_FILE, "my-face.jpg",
                     CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END);

        /* Add two file section */
        curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
                     CURLFORM_FILE, "my-face.jpg",
                     CURLFORM_FILE, "your-face.jpg", CURLFORM_END);

        /* Add two file section using CURLFORM_ARRAY */
        forms[0].option = CURLFORM_FILE;
        forms[0].value  = file1;
        forms[1].option = CURLFORM_FILE;
        forms[1].value  = file2;
        forms[2].option  = CURLFORM_END;

        /* Add a buffer to upload */
        curl_formadd(&post, &last,
                     CURLFORM_COPYNAME, "name",
                     CURLFORM_BUFFER, "data",
                     CURLFORM_BUFFERPTR, record,
                     CURLFORM_BUFFERLENGTH, record_length,
                     CURLFORM_END);

        /* no option needed for the end marker */
        curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures",
                     CURLFORM_ARRAY, forms, CURLFORM_END);
        /* Add the content of a file as a normal post text value */
        curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent",
                     CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END);
        /* Set the form info */
        curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);



SEE ALSO



BUGS

       Surely there are some, you tell me!


















































Man(1) output converted with man2html