NAME

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


SYNOPSIS

     #include <curl/curl.h>

     int curl_formadd(struct HttpPost ** firstitem, struct  Http­
     Post ** 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 CURLOPT_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.  (If
     the following description confuses you, jump directly to the
     examples):

     CURLFORM_COPYNAME or CURLFORM_PTRNAME followed by  a  string
     is  used for the name of the section. Optionally one may use
     CURLFORM_NAMELENGTH  to  specify  the  length  of  the  name
     (allowing null characters within the name). All options that
     use the word COPY in their names copy  the  given  contents,
     while  the ones with PTR in their names simply points to the
     (static) data you must make sure remain until curl no longer
     needs it.

     The four options for providing values are: CURLFORM_COPYCON­
     TENTS,   CURLFORM_PTRCONTENTS,   CURLFORM_FILE,   or   CURL­
     FORM_FILECONTENT followed by a char or void pointer (allowed
     for PTRCONTENTS).

     CURLFORM_FILECONTENT does a normal post like  CURLFORM_COPY­
     CONTENTS  but  the  actual  value  is read from the filename
     given as a string.

     Other arguments may  be  CURLFORM_CONTENTTYPE  if  the  user
     wishes  to  specify  one  (for  FILE if no type is given the
     library tries to provide the correct one;  for  CONTENTS  no
     Content-Type is sent in this case).

     For  CURLFORM_PTRCONTENTS  or CURLFORM_COPYNAME the user may
     also add CURLFORM_CONTENTSLENGTH followed by the length as a
     long  (if not given the library will use strlen to determine
     the length).

     For CURLFORM_FILE the user may send multiple  files  in  one
     section  by  providing multiple CURLFORM_FILE arguments each
     followed by the filename (and each FILE is allowed to have a
     CONTENTTYPE).

     Another  possibility to send single or multiple files in one
     section  is  to  use  CURLFORM_ARRAY  that  gets  a   struct
     curl_forms  array  pointer as its value. Each structure ele­
     ment has a  CURLformoption  and  a  char  pointer.  For  the
     options  only CURLFORM_FILE, CURLFORM_CONTENTTYPE, and CURL­
     FORM_END (that is used to determine the end of the array and
     thus  must be the option of the last and no other element of
     the curl_forms array) are allowed. The effect of this param­
     eter  is  the  same as giving multiple CURLFORM_FILE options
     possibly with  CURLFORM_CONTENTTYPE  after  or  before  each
     CURLFORM_FILE option.

     The  last  argument  in  such  an array must always be CURL­
     FORM_END.

     The pointers *firstitem and *lastitem should both be  point­
     ing  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.

     This function will copy  all  input  data  except  the  data
     pointed to by the arguments after CURLFORM_PTRNAME and CURL­
     FORM_PTRCONTENTS and keep its own version  of  it  allocated
     until you call curl_formfree. When you've passed the pointer
     to curl_easy_setopt, you must not free the list until  after
     you've  called curl_easy_cleanup for the curl handle. If you
     provide a pointer as an arguments after CURLFORM_PTRNAME  or
     CURLFORM_PTRCONTENTS  you must ensure that the pointer stays
     valid until you call curl_form_free and curl_easy_cleanup.

     See example below.


RETURN VALUE

     Returns non-zero if an error occurs.


EXAMPLE

      HttpPost* post = NULL;
      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 */
      curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent",
                   CURLFORM_PTRCONTENTS, buffer, CURLFORM_END);

      /* 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;

      /* 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

     curl_easy_setopt(3),     curl_formparse(3)     [deprecated],
     curl_formfree(3)


BUGS

     Surely there are some, you tell me!







































Man(1) output converted with man2html