DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

curl_formadd(3)





NAME

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


SYNOPSIS

       #include <curl/curl.h>

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


DESCRIPTION

       curl_formadd() is used  to  append  sections  when  building  a  multi-
       part/formdata HTTP POST (sometimes referred 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.

       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(3) after the form post
       has been done to free the resources.

       Using  POST  with  HTTP 1.1 implies the use of a "Expect: 100-continue"
       header.  You can disable this header with CURLOPT_HTTPHEADER as  usual.

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

       The options listed first are for making normal parts. The options  from
       CURLFORM_FILE  through CURLFORM_BUFFERLENGTH are for file upload parts.


OPTIONS

       CURLFORM_COPYNAME
              followed by a string which  provides  the  name  of  this  part.
              libcurl  copies  the  string so your application doesn't need to
              keep it around after this function call. If the name isn't  null
              terminated,  or if you'd like it to contain zero bytes, you must
              set its length with CURLFORM_NAMELENGTH. The copied data will be
              freed by curl_formfree(3).

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

       CURLFORM_COPYCONTENTS
              followed by a pointer to the contents of this part,  the  actual
              data  to  send  away.  libcurl copies the provided data, so your
              application doesn't need to keep it around after  this  function
              call.  If the data isn't null terminated, or if you'd like it to
              contain zero bytes, you must set the length  of  the  name  with
              CURLFORM_CONTENTSLENGTH.  The  copied  data  will  be  freed  by
              curl_formfree(3).

       CURLFORM_PTRCONTENTS
              followed by a pointer to the contents of this part,  the  actual
              data to send away. libcurl will use the pointer and refer to the
              data in your application, so you must make sure it remains until
              curl  no longer needs it.  If the data isn't null terminated, or
              if you'd like it to contain zero bytes, you must set its  length
              with CURLFORM_CONTENTSLENGTH.

       CURLFORM_CONTENTSLENGTH
              followed by a long giving the length of the contents.

       CURLFORM_FILECONTENT
              followed by a filename, causes that file to be read and its con-
              tents used as data in this part. This part  does  not  automati-
              cally become a file upload part simply because its data was read
              from a file.

       CURLFORM_FILE
              followed by a filename, makes this part a file upload  part.  It
              sets  the  filename  field to the basename of the provided file-
              name, it reads the contents of the file and passes them as  data
              and  sets  the  content-type  if the given file match one of the
              internally known file extensions.  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
              CURLFORM_FILE is allowed to have a CURLFORM_CONTENTTYPE).

       CURLFORM_CONTENTTYPE
              is used in combination with CURLFORM_FILE. Followed by a pointer
              to a string which provides the content-type for this part,  pos-
              sibly instead of an internally chosen one.

       CURLFORM_FILENAME
              is used in combination with CURLFORM_FILE. Followed by a pointer
              to a string, it tells libcurl to use the  given  string  as  the
              filename  in  the  file  upload  part instead of the actual file
              name.

       CURLFORM_BUFFER
              is used for custom  file  upload  parts  without  use  of  CURL-
              FORM_FILE.   It tells libcurl that the file contents are already
              present in a buffer.  The parameter is a string  which  provides
              the filename field in the content header.

       CURLFORM_BUFFERPTR
              is  used in combination with CURLFORM_BUFFER. The parameter is a
              pointer to the buffer to be uploaded. This buffer  must  not  be
              freed  until after curl_easy_cleanup(3) is called. You must also
              use CURLFORM_BUFFERLENGTH to set the  number  of  bytes  in  the
              buffer.

       CURLFORM_BUFFERLENGTH
              is  used in combination with CURLFORM_BUFFER. The parameter is a
              long which gives the length of the buffer.

       CURLFORM_ARRAY
              Another possibility to send options  to  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  gen-
              erates.  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(3)
              (using  the CURLOPT_HTTPPOST option), you must not free the list
              until after you've called curl_easy_cleanup(3) for the curl han-
              dle.

              See example below.


RETURN VALUE

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


EXAMPLE

        struct curl_httppost* post = NULL;
        struct curl_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;

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

       curl_easy_setopt(3), curl_formfree(3)

libcurl 7.9.8                    24 June 2002                  curl_formadd(3)

Man(1) output converted with man2html