lots of multi interface description but also some general updates and additions

    possibly together with a few other features that can be on and off on

    different libcurls.

    See also the "Features libcurl Provides" further down.

Portable Code in a Portable World

 avoided. They should only be called once each.

Features libcurl Provides

 It is considered best-practise to determine libcurl features run-time rather

 than build-time (if possible of course). By calling curl_version_info() and

 checking tout he details of the returned struct, your program can figure out

 exactly what the currently running libcurl supports.

Handle the Easy libcurl

 libcurl version 7 is oriented around the so called easy interface. All

 operations in the easy interface are prefixed with 'curl_easy'.

 libcurl first introduced the so called easy interface. All operations in the

 easy interface are prefixed with 'curl_easy'.

 Future libcurls will also offer the multi interface. More about that

 interface, what it is targeted for and how to use it is still only debated on

 the libcurl mailing list and developer web pages. Join up to discuss and

 figure out!

 Recent libcurl versions also offer the multi interface. More about that

 interface, what it is targeted for and how to use it is detailed in a

 separate chapter further down. You still need to understand the easy

 interface first, so please continue reading for better understanding.

 To use the easy interface, you must first create yourself an easy handle. You

 need one handle for each easy session you want to perform. Basicly, you

    information with faked data.

SSL, Certificates and Other Tricks

 [ seeding, passwords, keys, certificates, ENGINE, ca certs ]

Multiple Transfers Using the multi Interface

 The easy interface as described in detail in this document is a synchronous

 multiple files in both directions at the same time, without forcing you to

 use multiple threads.

 [fill in lots of more multi stuff here]

 To use this interface, you are better off if you first understand the basics

 of how to use the easy interface. The multi interface is simply a way to make

 multiple transfers at the same time, by adding up multiple easy handles in to

 a "multi stack".

 You create the easy handles you want and you set all the options just like

 you have been told above, and then you create a multi handle with

 curl_multi_init() and add all those easy handles to that multi handle with

 curl_multi_add_handle().

 When you've added the handles you have for the moment (you can still add new

 ones at any time), you start the transfers by call curl_multi_perform().

 curl_multi_perform() is asynchronous. It will only execute as little as

 possible and then return back control to your program. It is designed to

 never block. If it returns CURLM_CALL_MULTI_PERFORM you better call it again

 soon, as that is a signal that it still has local data to send or remote data

 to receive.

 The best usage of this interface is when you do a select() on all possible

 file descriptors or sockets to know when to call libcurl again. This also

 makes it easy for you to wait and respond to actions on your own

 application's sockets/handles. You figure out what to select() for by using

 curl_multi_fdset(), that fills in a set of fd_set variables for you with the

 particular file descriptors libcurl uses for the moment.

 When you then call select(), it'll return when one of the file handles signal

 action and you then call curl_multi_perform() to allow libcurl to do what it

 wants to do. Take note that libcurl does also feature some time-out code so

 we advice you to never use very long timeouts on select() before you call

 curl_multi_perform(), which thus should be called unconditionally every now

 and then even if none of its file descriptors have signalled ready. Another

 precation you should use: always call curl_multi_fdset() immediately before

 the select() call since the current set of file descriptors may change when

 calling a curl function.

 If you want to stop the transfer of one of the easy handles in the stack, you

 can use curl_multi_remove_handle() to remove individual easy

 handles. Remember that easy handles should be curl_easy_cleanup()ed.

 When a transfer within the multi stack has finished, the counter of running

 transfers (as filled in by curl_multi_perform()) will decrease. When the

 number reaches zero, all transfers are done.

 curl_multi_info_read() can be used to get information about completed

 transfers. It then returns the CURLcode for each easy transfer, to allow you

 to figure out success on each individual transfer.

SSL, Certificates and Other Tricks

 [ seeding, passwords, keys, certificates, ENGINE, ca certs ]

Future

 [ sharing between handles, mutexes, pipelining ]

Sharing Data Between Easy Handles

 [ fill in ]

-----

Footnotes: