curl posting

http://curl.haxx.se/libcurl/c/libcurl-tutorial.html

HTTP POSTing

We get many questions regarding how to issue HTTP POSTs with libcurl the proper way. This chapter will thus include examples using both different versions of HTTP POST that libcurl supports.

The first version is the simple POST, the most common version, that most HTML pages using the <form> tag uses. We provide a pointer to the data and tell libcurl to post it all to the remote site:

  char *data="name=daniel&project=curl";   curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, data);   curl_easy_setopt(easyhandle, CURLOPT_URL, "http://posthere.com/");

  curl_easy_perform(easyhandle); /* post away! */

Simple enough, huh? Since you set the POST options with the CURLOPT_POSTFIELDS, this automatically switches the handle to use POST in the upcoming request.

Ok, so what if you want to post binary data that also requires you to set the Content-Type: header of the post? Well, binary posts prevent libcurl from being able to do strlen() on the data to figure out the size, so therefore we must tell libcurl the size of the post data. Setting headers in libcurl requests are done in a generic way, by building a list of our own headers and then passing that list to libcurl.

 struct curl_slist *headers=NULL;  headers = curl_slist_append(headers, "Content-Type: text/xml");

 /* post binary data */  curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDS, binaryptr);

 /* set the size of the postfields data */  curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23L);

 /* pass our list of custom made headers */  curl_easy_setopt(easyhandle, CURLOPT_HTTPHEADER, headers);

 curl_easy_perform(easyhandle); /* post away! */

 curl_slist_free_all(headers); /* free the header list */

While the simple examples above cover the majority of all cases where HTTP POST operations are required, they don't do multi-part formposts. Multi-part formposts were introduced as a better way to post (possibly large) binary data and were first documented in the RFC 1867 (updated in RFC2388). They're called multi-part because they're built by a chain of parts, each part being a single unit of data. Each part has its own name and contents. You can in fact create and post a multi-part formpost with the regular libcurl POST support described above, but that would require that you build a formpost yourself and provide to libcurl. To make that easier, libcurl provides curl_formadd(3). Using this function, you add parts to the form. When you're done adding parts, you post the whole form.

The following example sets two simple text parts with plain textual contents, and then a file with binary contents and uploads the whole thing.

 struct curl_httppost *post=NULL;  struct curl_httppost *last=NULL;  curl_formadd(&post, &last,   CURLFORM_COPYNAME, "name",   CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END);  curl_formadd(&post, &last,   CURLFORM_COPYNAME, "project",   CURLFORM_COPYCONTENTS, "curl", CURLFORM_END);  curl_formadd(&post, &last,   CURLFORM_COPYNAME, "logotype-image",   CURLFORM_FILECONTENT, "curl.png", CURLFORM_END);

 /* Set the form info */  curl_easy_setopt(easyhandle, CURLOPT_HTTPPOST, post);

 curl_easy_perform(easyhandle); /* post away! */

 /* free the post data again */  curl_formfree(post);

Multipart formposts are chains of parts using MIME-style separators and headers. It means that each one of these separate parts get a few headers set that describe the individual content-type, size etc. To enable your application to handicraft this formpost even more, libcurl allows you to supply your own set of custom headers to such an individual form part. You can of course supply headers to as many parts as you like, but this little example will show how you set headers to one specific part when you add that to the post handle:

 struct curl_slist *headers=NULL;  headers = curl_slist_append(headers, "Content-Type: text/xml");

 curl_formadd(&post, &last,   CURLFORM_COPYNAME, "logotype-image",   CURLFORM_FILECONTENT, "curl.xml",   CURLFORM_CONTENTHEADER, headers,   CURLFORM_END);

 curl_easy_perform(easyhandle); /* post away! */

 curl_formfree(post); /* free post */  curl_slist_free_all(headers); /* free custom header list */

Since all options on an easyhandle are "sticky", they remain the same until changed even if you do call curl_easy_perform(3), you may need to tell curl to go back to a plain GET request if you intend to do one as your next request. You force an easyhandle to go back to GET by using the CURLOPT_HTTPGET option:

 curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, 1L);

Just setting CURLOPT_POSTFIELDS to "" or NULL will *not* stop libcurl from doing a POST. It will just make it POST without any data to send!