The fundamentals you need to learn with libcurl:

First you create an "easy handle", which is your handle to a transfer, really:

CURL *easy_handle = curl_easy_init();

You then set options in that handle to control the upcoming transfer. This example sets the URL:

/* set URL to operate on */
res = curl_easy_setopt(easy_handle, CURLOPT_URL, "http://example.com/");

If curl_easy_setopt() returns CURLE_OK, we know it stored the option fine.

Creating the easy handle and setting options on it does not make any transfer happen, and usually do not even make much more happen other than libcurl storing your wish to be used later when the transfer actually occurs. Lots of syntax checking and validation of the input may also be postponed, so just because curl_easy_setopt did not complain, it does not mean that the input was correct and valid; you may get an error returned later.

Read more on easy options in its separate section.

When you are done setting options to your easy handle, you can fire off the actual transfer.

The actual performing of the transfer can be done using different methods and function calls, depending on what kind of behavior you want in your application and how libcurl is best integrated into your architecture. Those are further described later in this chapter.

While the transfer is ongoing, libcurl calls your specified functions—known as callbacks — to deliver data, to read data or to do a wide variety of things.

After the transfer has completed, you can figure out if it succeeded or not and you can extract statistics and other information that libcurl gathered during the transfer from the easy handle. See Post transfer information.

Reuse!

Easy handles are meant and designed to be reused. When you have done a single transfer with the easy handle, you can immediately use it again for your next transfer. There are lots of gains to be had by this.

All options are "sticky". They remain set in the handle until you change them again, or call curl_easy_reset() on the handle. If you make a second transfer with the same handle, the same options are used.