NAME

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


SYNOPSIS

     #include <curl/curl.h>

     CURLcode 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 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 in a faster way.

     After lastitem follow the real arguments that constitute the
     new  section (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).

     The  three  options for providing values are: CURLFORM_COPY­
     CONTENTS, CURLFORM_PTRCONTENTS, or  CURLFORM_FILE,  followed
     by a char or void pointer (allowed for PTRCONTENTS).

     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).

     The last argument always is CURLFORM_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);
      /* 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);
      /* 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