extended the proxy chapter mucho

1 files changed, 144 insertions, 23 deletions

diff --git a/docs/libcurl-the-guide b/docs/libcurl-the-guide
index b52b40037..9d3a65c5f 100644
--- a/docs/libcurl-the-guide
+++ b/docs/libcurl-the-guide
@@ -137,9 +137,22 @@ Handle the Easy libcurl
 
  It returns an easy handle. Using that you proceed to the next step: setting
  up your preferred actions. A handle is just a logic entity for the upcoming
- transfer or series of transfers. One of the most basic properties to set in
- the handle is the URL. You set your preferred URL to transfer with
- CURLOPT_URL in a manner similar to:
+ transfer or series of transfers.
+
+ You set properties and options for this handle using curl_easy_setopt(). They
+ control how the subsequent transfer or transfers will be made. Options remain
+ set in the handle until set again to something different. Alas, multiple
+ requests using the same handle will use the same options.
+
+ Many of the informationals you set in libcurl are "strings", pointers to data
+ terminated with a zero byte. Keep in mind that when you set strings with
+ curl_easy_setopt(), libcurl will not copy the data. It will merely point to
+ the data. You MUST make sure that the data remains available for libcurl to
+ use until finished or until you use the same option again to point to
+ something else.
+
+ One of the most basic properties to set in the handle is the URL. You set
+ your preferred URL to transfer with CURLOPT_URL in a manner similar to:
 
     curl_easy_setopt(easyhandle, CURLOPT_URL, "http://curl.haxx.se/");
 
@@ -358,12 +371,16 @@ HTTP POSTing
 
     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.
+ Simple enough, huh? Since you set the POST options with the
+ CURLOPT_POSTFIELDS, this automaticly 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 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");
@@ -416,14 +433,14 @@ HTTP POSTing
     /* 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
+ 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 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:
+ supply your own set of custom headers to such an individual form part. You
+ can of course supply headers to as many parts 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");
@@ -439,9 +456,22 @@ HTTP POSTing
     curl_formfree(post); /* free post */
     curl_slist_free_all(post); /* 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(), you may need to tell curl to
+ go back to a plain GET request if you intend to do such a one as your next
+ request. You force an easyhandle to back to GET by using the CURLOPT_HTTPGET
+ option:
+
+    curl_easy_setopt(easyhandle, CURLOPT_HTTPGET, TRUE);
+
+ 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!
+
 
 Showing Progress
 
+ [ built-in progress meter, progress callback ]
+
 
 libcurl with C++
 
@@ -488,16 +518,107 @@ Proxies
  proxy is using the HTTP protocol. For example, you can't invoke your own
  custom FTP commands or even proper FTP directory listings.
 
- To tell libcurl to use a proxy at a given port number:
+  Proxy Options
+
+    To tell libcurl to use a proxy at a given port number:
+
+       curl_easy_setopt(easyhandle, CURLOPT_PROXY, "proxy-host.com:8080");
+
+    Some proxies require user authentication before allowing a request, and
+    you pass that information similar to this:
+
+       curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "user:password");
+
+    If you want to, you can specify the host name only in the CURLOPT_PROXY
+    option, and set the port number separately with CURLOPT_PROXYPORT.
+
+  Environment Variables
+
+    libcurl automaticly checks and uses a set of environment variables to know
+    what proxies to use for certain protocols. The names of the variables are
+    following an ancient de facto standard and are built up as
+    "[protocol]_proxy" (note the lower casing). Which makes the variable
+    'http_proxy' checked for a name of a proxy to use when the input URL is
+    HTTP. Following the same rule, the variable named 'ftp_proxy' is checked
+    for FTP URLs. Again, the proxies are always HTTP proxies, the different
+    names of the variables simply allows different HTTP proxies to be used.
+
+    The proxy environment variable contents should be in the format
+    "[protocol://]machine[:port]". Where the protocol:// part is simply
+    ignored if present (so http://proxy and bluerk://proxy will do the same)
+    and the optional port number specifies on which port the proxy operates on
+    the host. If not specified, the internal default port number will be used
+    and that is most likely *not* the one you would like it to be.
+
+    There are two special environment variables. 'all_proxy' is what sets
+    proxy for any URL in case the protocol specific variable wasn't set, and
+    'no_proxy' defines a list of hosts that should not use a proxy even though
+    a variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches
+    all hosts.
+
+  SSL and Proxies
+
+    SSL is for secure point-to-point connections. This envolves strong
+    encryption and similar things, which effectivly makes it impossible for a
+    proxy to operate as a "man in between" which the proxy's task is as
+    previously discussed. Instead, the only way to have SSL work over a HTTP
+    proxy is to ask the proxy to tunnel trough everything without being able
+    to check the traffic.
+
+    Opening an SSL connection over a HTTP proxy is therefor a matter of asking
+    the proxy for a straight connection to the target host on a specified
+    port. This is made with the HTTP request CONNECT.
+
+    Because of the nature of this operation, where the proxy has no idea what
+    kind of data that is passed in and out through this tunnel, this
+    effectively breaks some of the pros a proxy might offer, such as caching.
+    Many organizations prevent this kind of tunneling to other destination
+    port numbers than 443 (which is the default HTTPS port number).
+
+  Tunneling Through Proxy
+
+    As explained above, tunneling is required for SSL to work and often even
+    restricted to the operation intended for SSL; HTTPS.
+
+    This is however not the only time proxy-tunneling might offer benefits to
+    you or your application.
+
+    As tunneling opens a direct connection from your application to the remote
+    machine, it suddenly also re-introduces the ability to do non-HTTP
+    operations over a HTTP proxy. You can in fact use things such as FTP
+    upload or FTP custom commands this way.
+
+    Again, this is often prevented by the adminstrators of proxies and is
+    rarely allowed.
+
+    Tell libcurl to use proxy tunneling like this:
+
+       curl_easy_setopt(easyhandle, CURLOPT_HTTPPROXYTUNNEL, TRUE);
+
+  Proxy Auto-Config
+
+    Netscape first came up with this. It is basicly a web page (usually using
+    a .pac extension) with a javascript that when executed by the browser with
+    the requested URL as input, returns information to the browser on how to
+    connect to the URL. The returned information might be "DIRECT" (which
+    means no proxy should be used), "PROXY host:port" (to tell the browser
+    where the proxy for this particular URL is) or "SOCKS host:port" (to
+    direct the brower to a SOCKS proxy).
+
+    libcurl has no means to interpret or evaluate javascript and thus it
+    doesn't support this. If you get yourself in a position where you face
+    this nasty invention, the following advice have been mentioned and used in
+    the past:
 
-    curl_easy_setopt(easyhandle, CURLOPT_PROXY, "proxy-host.com:8080");
+    - Depending on the javascript complexity, write up a script that
+      translates it to another language and execute that.
 
- Some proxies require user authentication before allowing a request, and you
- pass that information similar to this:
+    - Read the javascript code and rewrite the same logic in another language.
 
-    curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "user:password");
+    - Implement a javascript interpreted, people have successfully used the
+      Mozilla javascript engine in the past.
 
- [ environment variables, SSL, tunneling, automatic proxy config (.pac) ]
+    - Ask your admins to stop this, for a static proxy setup or similar.
 
 
 Security Considerations
@@ -505,7 +626,7 @@ Security Considerations
  [ ps output, netrc plain text, plain text protocols / base64 ]
 
 
-Certificates and Other SSL Tricks
+SSL, Certificates and Other Tricks
 
 
 Future