aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/libcurl-the-guide105
1 files changed, 105 insertions, 0 deletions
diff --git a/docs/libcurl-the-guide b/docs/libcurl-the-guide
index 92f16ce13..6ce5db7f4 100644
--- 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