HTTP POST explained

diff --git a/docs/libcurl-the-guide b/docs/libcurl-the-guide
index 92f16ce13bd7afda6ad4dcccb14cfe85e3794169..6ce5db7f4892b437e28f79b9d37f044e3ee5fdff 100644 (file)
--- a/docs/libcurl-the-guide
+++ b/docs/libcurl-the-guide
@@ -300,6 +300,104 @@ Passwords
   [ more options, setting passsword callback ]
 
 
+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? 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
+ prevents 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_POSTFIELD, binaryptr);
+
+    /* set the size of the postfields data */
+    curl_easy_setopt(easyhandle, CURLOPT_POSTFIELDSIZE, 23);
+
+    /* 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 multipart formposts. Multipart
+ formposts were introduced as a better way to post (possibly large) binary
+ data and was first documented in the RFC1867. They're called multipart
+ because they're built by a chain of parts, each being a single unit. Each
+ part has its own name and contents. You can in fact create and post a
+ multipart 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(). 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 upload the whole thing.
+
+    struct HttpPost *post=NULL;
+    struct 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);
+
+ The multipart formposts are a chain of parts using MIME-style separators and
+ headers. That means that each of these separate parts get a few headers set
+ that describes its individual content-type, size etc. Now, to enable your
+ application to handicraft this formpost even more, libcurl allows you to
+ supply your own custom headers to an individual form part. You can of course
+ supply headers to as many parts you like, but this little example will show
+ how you have set headers to one specific part when you add that to 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(post); /* free custom header list */
+
+
 Showing Progress
 
 
@@ -325,8 +423,15 @@ libcurl with C++
  any "this" pointer available etc.
 
 
+Proxies
+
+ [ regular http, authorization, ftp => http, SSL, tunneling ]
+
+
 Security Considerations
 
+ [ ps output, netrc plain text, plain text protocols / base64 ]
+
 
 Certificates and Other SSL Tricks