Building
There are many different ways to build C programs. This chapter will assume
- a unix-style build process
+ 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
Your compiler needs to know where the libcurl headers are
located. Therefore you must set your compiler's include path to point to
- the directory where you installed them. The 'curl-config' tool can be used
- to get this information:
+ the directory where you installed them. The 'curl-config'[3] tool can be
+ used to get this information:
$ curl-config --cflags
different libcurls.
+Portable Code in a Portable World
+
+ The people behind libcurl have put a considerable effort to make libcurl work
+ on a large amount of different operating systems and environments.
+
+ You program libcurl the same way on all platforms that libcurl runs on. There
+ are only very few minor considerations that differs. If you just make sure to
+ write your code portable enough, you may very well create yourself a very
+ portable program. libcurl shouldn't stop you from that.
+
+
Global Preparation
The program must initialize some of the libcurl functionality globally. That
and the function that gets invoked by libcurl. libcurl itself won't touch the
data you pass with CURLOPT_FILE.
+ libcurl offers its own default internal callback that'll take care of the
+ data if you don't set the callback with CURLOPT_WRITEFUNCTION. It will then
+ simply output the received data to stdout. You can have the default callback
+ write the data to a different file handle by passing a 'FILE *' to a file
+ opened for writing with the CURLOPT_FILE option.
+
+ Now, we need to take a step back and have a deep breath. Here's one of those
+ rare platform-dependent nitpicks. Did you spot it? On some platforms[2],
+ libcurl won't be able to operate on files opened by the program. Thus, if you
+ use the default callback and pass in a an open file with CURLOPT_FILE, it
+ will crash. You should therefore avoid this to make your program run fine
+ virtually everywhere.
+
There are of course many more options you can set, and we'll get back to a
few of them later. Let's instead continue to the actual transfer:
you intend to make another transfer. libcurl will then attempt to re-use the
previous
+
When It Doesn't Work
There will always be times when the transfer fails for some reason. You might
wht the server behaves the way it does. Include headers in the normal body
output with CURLOPT_HEADER set TRUE.
+ Of course there are bugs left. We need to get to know about them to be able
+ to fix them, so we're quite dependent on your bug reports! When you do report
+ suspected bugs in libcurl, please include as much details you possibly can: a
+ protocol dump that CURLOPT_VERBOSE produces, library version, as much as
+ possible of your code that uses libcurl, operating system name and version,
+ compiler name and version etc.
+
+
Upload Data to a Remote Site
libcurl tries to keep a protocol independent approach to most transfers, thus
fast as possible. The callback should return the number of bytes it wrote in
the buffer. Returning 0 will signal the end of the upload.
+
+Passwords
+
+ Many protocols use or even require that user name and password are provided
+ to be able to download or upload the data of your choice. libcurl offers
+ several ways to specify them.
+
+ [ URL, options, callback ]
+
+
+Showing Progress
+
+
libcurl with C++
There's basicly only one thing to keep in mind when using C++ instead of C
any "this" pointer available etc.
+Security Considerations
+
+
+Certificates and Other SSL Tricks
+
+
+Future
+
+
+
-----
Footnotes:
but libcurl does not support the chunked transfers on uploading that is
necessary for this feature to work. We'd gratefully appreciate patches
that bring this functionality...
+
+[2] = This happens on Windows machines when libcurl is built and used as a
+ DLL. However, you can still do this on Windows if you link with a static
+ library.
+
+[3] = The curl-config tool is generated at build-time (on unix-like systems)
+ and should be installed with the 'make install' or similar instruction
+ that installs the library, header files, man pages etc.