aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl-the-guide
diff options
context:
space:
mode:
Diffstat (limited to 'docs/libcurl-the-guide')
-rw-r--r--docs/libcurl-the-guide84
1 files changed, 78 insertions, 6 deletions
diff --git a/docs/libcurl-the-guide b/docs/libcurl-the-guide
index 6ce5db7f4..b52b40037 100644
--- a/docs/libcurl-the-guide
+++ b/docs/libcurl-the-guide
@@ -20,13 +20,15 @@ About this Document
source code that you write that is using libcurl for transfers. The program
is outside libcurl and libcurl is outside of the program.
+ To get the more details on all options and functions described herein, please
+ refer to their respective man pages.
Building
- There are many different ways to build C programs. This chapter will assume
- a unix-style build process. If you use a different build system, you can
- still read this to get general information that may apply to your
- environment as well.
+ There are many different ways to build C programs. This chapter will assume a
+ unix-style build process. If you use a different build system, you can still
+ read this to get general information that may apply to your environment as
+ well.
Compiling the Program
@@ -222,6 +224,11 @@ When It Doesn't Work
possible of your code that uses libcurl, operating system name and version,
compiler name and version etc.
+ Getting some in-depth knowledge about the protocols involved is never wrong,
+ and if you're trying to funny things, you might very well understand libcurl
+ and how to use it better if you study the appropriate RFC documents at least
+ briefly.
+
Upload Data to a Remote Site
@@ -297,7 +304,42 @@ Passwords
curl_easy_setopt(easyhandle, CURLOPT_PROXYUSERPWD, "myname:thesecret");
- [ more options, setting passsword callback ]
+ There's a long time unix "standard" way of storing ftp user names and
+ passwords, namely in the $HOME/.netrc file. The file should be made private
+ so that only the user may read it (see also the "Security Considerations"
+ chapter), as it might contain the password in plain text. libcurl has the
+ ability to use this file to figure out what set of user name and password to
+ use for a particular host. As an extension to the normal functionality,
+ libcurl also supports this file for non-FTP protocols such as HTTP. To make
+ curl use this file, use the CURLOPT_NETRC option:
+
+ curl_easy_setopt(easyhandle, CURLOPT_NETRC, TRUE);
+
+ And a very basic example of how such a .netrc file may look like:
+
+ machine myhost.mydomain.com
+ login userlogin
+ password secretword
+
+ All these examples have been cases where the password has been optional, or
+ at least you could leave it out and have libcurl attempt to do its job
+ without it. There are times when the password isn't optional, like when
+ you're using an SSL private key for secure transfers.
+
+ You can in this situation either pass a password to libcurl to use to unlock
+ the private key, or you can let libcurl prompt the user for it. If you prefer
+ to ask the user, then you can provide your own callback function that will be
+ called when libcurl wants the password. That way, you can control how the
+ question will appear to the user.
+
+ To pass the known private key password to libcurl:
+
+ curl_easy_setopt(easyhandle, CURLOPT_SSLKEYPASSWD, "keypassword");
+
+ To make a password callback:
+
+ int enter_passwd(void *ourp, const char *prompt, char *buffer, int len);
+ curl_easy_setopt(easyhandle, CURLOPT_PASSWDFUNCTION, enter_passwd);
HTTP POSTing
@@ -425,7 +467,37 @@ libcurl with C++
Proxies
- [ regular http, authorization, ftp => http, SSL, tunneling ]
+ What "proxy" means according to Merriam-Webster: "a person authorized to act
+ for another" but also "the agency, function, or office of a deputy who acts
+ as a substitute for another".
+
+ Proxies are exceedingly common these days. Companies often only offer
+ internet access to employees through their HTTP proxies. Network clients or
+ user-agents ask the proxy for docuements, the proxy does the actual request
+ and then it returns them.
+
+ libcurl has full support for HTTP proxies, so when a given URL is wanted,
+ libcurl will ask the proxy for it instead of trying to connect to the actual
+ host identified in the URL.
+
+ The fact that the proxy is a HTTP proxy puts certain restrictions on what can
+ actually happen. A requested URL that might not be a HTTP URL will be still
+ be passed to the HTTP proxy to deliver back to libcurl. This happens
+ transparantly, and an application may not need to know. I say "may", because
+ at times it is very important to understand that all operations over a HTTP
+ 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:
+
+ 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");
+
+ [ environment variables, SSL, tunneling, automatic proxy config (.pac) ]
Security Considerations