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


SYNOPSIS

       #include <curl/curl.h>

       CURLcode curl_formparse(char * string, struct HttpPost  **
       firstitem, struct HttpPost ** lastitem);


DESCRIPTION

       curl_formparse()  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 in  a  faster
       way.   string  must be a zero terminated string abiding to
       the syntax described in a section below

       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.

       This function will copy all input data 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.

       See example below.


FORM PARSE STRINGS

       The string parameter must be using one  of  the  following
       patterns.  Note that the [] letters should not be included
       in the real-life string.

       [name]=[contents]
               Add a form field named 'name'  with  the  contents
               'contents'.  This  is  the typcial contents of the
               HTML tag <input type=text>.

       [name]=@[filename]
               Add a form field named 'name' with the contents as
               read from the local file named 'filename'. This is
               the  typcial  contents  of  the  HTML  tag  <input
               type=file>.

       [name]=@[filename1,filename2,...]
               Add a form field named 'name' with the contents as

               'filename2'.  This  is  identical  to  the  upper,
               except that you get the contents of several  files
               in one section.

       [name]=@[filename];[type=<content-type>]
               Whenever  you specify a file to read from, you can
               optionally specify the content-type as  well.  The
               content-type is passed to the server together with
               the contents of the  file.  curl_formparse()  will
               guess  content-type  for  a  number  of well-known
               extensions and otherwise it will set it to binary.
               You  can  override  the internal decision by using
               this option.

       [name]=@[filename1,filename2,...];[type=<content-type>]
               When you specify several files to  read  the  con­
               tents  from,  you can set the content-type for all
               of them in the same way as with a single file.


RETURN VALUE

       Returns non-zero if an error occurs.


EXAMPLE

        HttpPost* post = NULL;
        HttpPost* last = NULL;

        /* Add an image section */
        curl_formparse("picture=@my-face.jpg", &post, &last);
        /* Add a normal text section */
        curl_formparse("name=FooBar", &post, &last);
        /* Set the form info */
        curl_easy_setopt(curl, CURLOPT_HTTPPOST, post);


SEE ALSO

       curl_easy_setopt(3), curl_formfree(3)


BUGS

       Surely there are some, you tell me!


Man(1) output converted with man2html