[Translate]libcurl_tutorial

Handle the Easy Libcurl

To use the easy interface, you must first create yourself a easy handle. You need one handle for each easy session, you want to perform. Basically, you should the use of one handle for every the thread you plan to use for transferring. You must never share the same handle in multiple threads.
To use the easy interface, you need to first create an easy handle.
A handle is used in an easy session, which basically means that every thread that needs to use curl has its own easy handle.
The same handle cannot be used in multiple threads.

Get an easy handle with
Easyhandle = Curl_easy_init ();

This way to get an easy handle
Easyhandle = Curl_easy_init ();

It returns an easy handle. Using that, proceed to the next step:setting up your preferred actions. A handle is just a logic entity for the upcoming transfer or series of transfers.
Curl_easy_init () returns an easy handle, and then proceeds to the next step after you get the handle, a handle is a logical entity for
One or more data transfers that are about to be performed.

You set the properties and options for this handle using curl_easy_setopt. They control how the subsequent transfer or transfers would be made. Options remain set in the handle until set again to something different. They is sticky. Multiple requests using the same handle would use the same options.

Use Curl_easy_setopt to set handle properties and options.
These settings take effect in subsequent data transfers, and they will remain in effect as long as these properties and options are not modified.

If you are on any of the would like to blank all previously set options for a single easy handle and you can call Curl_easy_reset And you can also make a clone of an easy handle (with all its set options) using Curl_easy_duphandle.
If you want to empty the properties and options in easy handle, use Curl_easy_reset.
If you want to clone an easy handle, use Curl_easy_duphandle. (Cloning will bring all of the original properties and options)

Many of the options you set in Libcurl is "strings", pointers to data terminated with a zero byte. When your set strings with curl_easy_setopt, Libcurl makes it own copy so that they don ' t need to be kept around in your a Pplication after being set[4].
Most of the options in Libcurl are string, with ' s ' as The Terminator.
After you set the properties using Curl_easy_setopt, you do not need to save this string,libcurl to copy the string.

One of the most basic properties to set in the handle is the URL. You set your preferred URL to transfer with Curlopt_url in a manner similar to:
Curl_easy_setopt (handle, Curlopt_url, "http://domain.com/");

Handle the most basic property setting is to set the URL as follows:
Curl_easy_setopt (handle, Curlopt_url, "http://domain.com/");

Let's assume for a while that want to receive data as the URL identifies a remote resource you want to get here. Since you write a sort of application so needs this transfer, I assume so you would like to get the data passed to you Directly instead of simply getting it passed to stdout. So, you write your own function, which matches this prototype:
size_t write_data (void *buffer, size_t size, size_t nmemb, void *userp);

Let's say you want to receive data from a remote URL now,
When you write a short program, I assume you want to receive data directly instead of outputting it to stdout.
size_t write_data (void *buffer, size_t size, size_t nmemb, void *userp);

You tell Libcurl to pass all data to this function by issuing a function similar to this:
Curl_easy_setopt (Easyhandle, curlopt_writefunction, Write_data);
Send the data by using the following code:
Curl_easy_setopt (Easyhandle, curlopt_writefunction, Write_data);

Can control what data your callback function gets in the fourth argument by setting another property:
Curl_easy_setopt (Easyhandle, Curlopt_writedata, &internal_struct);
You can control the data using the callback parameter, and the fourth parameter is the callback parameter
Curl_easy_setopt (Easyhandle, Curlopt_writedata, &internal_struct);

Using the, can easily pass local data between your application and the function that gets invoked by Libcurl . Libcurl itself won ' t touch the data you pass with Curlopt_writedata.
With this property, you can easily transfer local data, which is awakened by Libcurl.
Libcurl itself does not modify the data of the Curlopt_writedata property

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 would then simply output of the received data to stdout. You can has the default callback write the data to a different file handle by passing a ' file * ' to a file opened for WRI Ting with the curlopt_writedata option.
If you do not use Curlopt_writefunction to set the callback, LIBCURL provides the default internal callback, and he outputs the received data directly to stdout.
You can also write data to a file using Curlopt_writedata and the file pointer ' file * '.

Now, we need-take a step back and has a deep breath. Here ' s one of those rare platform-dependent nitpicks. Did you spot it? On some platforms[2], Libcurl won ' is able to operate on files opened by the program. Thus, if you use the default callback and pass in a open file with Curlopt_writedata, it'll crash. You should therefore avoid the to make your program run fine virtually everywhere.
On some platforms, Libcurl cannot manipulate files opened by the program (in the case of Windows, Libcurl as a DLL, this cannot be done).
Therefore, if you use the default callback and use Curlopt_writedata to pass in a file that is already open, it will cause a crash.

(Curlopt_writedata was formerly known as Curlopt_file. Both names still work and do the same thing).
Curlopt_file is Curlopt_writedata's former name and is still available, meaning unchanged.

If you ' re using Libcurl as a Win32 DLL, you must use the curlopt_writefunction if you set curlopt_writedata-or you'll Experience crashes.
If Libcurl is used as a DLL under Win32 and Curlopt_writedata is set, you must use curlopt_writefunction or else crash.

There is of course many more options can set, and we'll get back to a few of them later. Let's instead continue to the actual transfer:
Success = Curl_easy_perform (Easyhandle);
With so much set up, let's take a look first:
Success = Curl_easy_perform (Easyhandle);

Curl_easy_perform'll connect to the remote site, do the necessary commands and receive the transfer. Whenever it receives data, it calls the callback function we previously set. The function may get one byte at a time, or it could get many kilobytes at once. Libcurl delivers as much as possible as often as possible. Your callback function should return the number of bytes it "took care of". If that's not the exact same amount of bytes that's passed to it, Libcurl'll abort the operation and return with an E Rror code.

Curl_easy_perform connects to the remote server, performs operations, and accepts data.
When data is received, the previously set callback function is called.
The function may accept 1 bytes at a time, and can accept multiple bytes at a time, not necessarily, Libcurl will try to deliver.
Your callback function should return the number of bytes received.
If the transmitted data is inconsistent with the expected, the Libcurl is interrupted and an error code is returned.

When the transfer are complete, the function returns a return code that informs if it succeeded in its mission or not. If a return code isn ' t enough for your, you can use the Curlopt_errorbuffer to point Libcurl to a buffer of yours where it ' ll store a human readable error message as well.
When the transfer is complete, the function returns the result.
If the return value is not sufficient, you can use Curlopt_errorbuffer to get the error reason string.

If you then want to transfer another file, the handle are ready for be used again. Mind you, it's even preferred that re-use a existing handle if you intend to make another transfer. Libcurl'll then attempt to re-use the previous connection.
If you want to transfer other files, handle can already be used again, Libcurl will be reused handle

For some protocols, downloading a file can involve a complicated process of logging in, setting the transfer mode, Changin G The current directory and finally transferring the file data. Libcurl takes care of all, complication for you. Given simply the URL to a file, Libcurl'll take care of all the details needed to get the file moved from another.
Some protocols that download files can be complex, such as logging in, setting up transfer mode, directory switching, and finally transmitting data.
Libcurl will help you with these complex processes.

multi-threading issues
Multithreading issues

The first basic rule is, you must never simultaneously share a libcurl handle (being it easy or multi or whatever) betwee n Multiple threads. Only use one handle on one thread at any time. You can pass the handles around among threads, but do must never use a single handle from more than one thread at any giv En time.
The basic principle is that you cannot share Libcurl handle (easy, multi, or anything) in multiple threads.
A handle can only be used in one thread at a time.
You can pass handle between threads, but you can't use them at the same time.

Libcurl is completely the thread safe, except for the Issues:signals and SSL/TLS handlers. Signals is used for timing out name resolves (during DNS lookup) – when built without using either the c-ares or threaded Resolver backends.

Libcurl is thread safe, with the exception of 2 questions:
Signals and SSL/TLS handle.
The signal is used in DNS lookup.

If you were accessing HTTPS or FTPS URLs in a multi-threaded manner, you were then the course using the underlying SSL Librar Y multi-threaded and those Libs might has their own requirements on this issue. Basically, you need to provide one or both functions to allow it to function properly. For any details, see this:
If you access HTTPS and FTPS URLs in multiple threads, you will definitely use the SSL library

Openssl

Http://www.openssl.org/docs/crypto/threads.html#DESCRIPTION

GnuTLS

Http://gnutls.org/manual/html_node/Thread-safety.html

Nss

is claimed to be thread-safe already without anything required.

Polarssl

Required actions unknown.

Yassl

Required actions unknown.

Axtls

Required actions unknown.

Secure Transport

The engine is fully thread-safe, and no additional steps is required.

When using multiple threads you should set the Curlopt_nosignal option to 1 for all handles. Everything would or might work fine except that timeouts is not honored during the DNS Lookup-which you can work around By building Libcurl and c-ares support. C-ares is a library of that provides asynchronous name resolves. On some platforms, Libcurl simply won't function properly multi-threaded unless this option is set.

Also, note that curlopt_dns_use_global_cache are not thread-safe.

[Translate]libcurl_tutorial