more text added

Building

Building

  There are many different ways to build C programs. This chapter will assume

  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

  Compiling the Program

    Your compiler needs to know where the libcurl headers are

    Your compiler needs to know where the libcurl headers are

    located. Therefore you must set your compiler's include path to point to

    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

    the directory where you installed them. The 'curl-config'[3] tool can be

    to get this information:

    used to get this information:

        $ curl-config --cflags

        $ curl-config --cflags

    different libcurls.

    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

Global Preparation

 The program must initialize some of the libcurl functionality globally. That

 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

 and the function that gets invoked by libcurl. libcurl itself won't touch the

 data you pass with CURLOPT_FILE.

 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

 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:

 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

 you intend to make another transfer. libcurl will then attempt to re-use the

 previous

 previous

When It Doesn't Work

When It Doesn't Work

 There will always be times when the transfer fails for some reason. You might

 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

 wht the server behaves the way it does. Include headers in the normal body

 output with CURLOPT_HEADER set TRUE.

 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

Upload Data to a Remote Site

 libcurl tries to keep a protocol independent approach to most transfers, thus

 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

 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.

 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++

libcurl with C++

 There's basicly only one thing to keep in mind when using C++ instead of C

 There's basicly only one thing to keep in mind when using C++ instead of C

 any "this" pointer available etc.

 any "this" pointer available etc.

Security Considerations

Certificates and Other SSL Tricks

Future

-----

-----

Footnotes:

Footnotes:

      but libcurl does not support the chunked transfers on uploading that is

      but libcurl does not support the chunked transfers on uploading that is

      necessary for this feature to work. We'd gratefully appreciate patches

      necessary for this feature to work. We'd gratefully appreciate patches

      that bring this functionality...

      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.