curl_easy_perform

Definition: include builtins\libcurl.e

CURLcode res = curl_easy_perform(atom curl)
Description: Perform a blocking file transfer synchronously.

Invoke this function after curl_easy_init and all the curl_easy_setopt calls are made, to perform the transfer as described in the options.
It must be called with the same easy_handle as input as the curl_easy_init call returned.

curl_easy_perform performs the entire request in a blocking manner and returns when done, or if it failed.
For non-blocking behavior, see curl_multi_perform.

You can do any amount of calls to curl_easy_perform while using the same easy_handle.
If you intend to transfer more than one file, you are even encouraged to do so.
libcurl will then attempt to re-use the same connection for the following transfers, thus making the operations faster, less CPU intense and using less network resources.
Just note that you will have to use curl_easy_setopt between the invokes to set options for the following curl_easy_perform.

You must never call this function simultaneously from two places using the same easy_handle.
Let the function return first before invoking it another time.
If you want parallel transfers, you must use several curl easy_handles.

While the easy_handle is added to a multi handle, it cannot be used by curl_easy_perform.

Return value: CURLE_OK (0) means everything was ok, non-zero means an error occurred - see CURLcode.
If the CURLOPT_ERRORBUFFER was set with curl_easy_setopt there will be a readable error message in the error buffer when non-zero is returned.
Utility Functions object res = curl_easy_perform_ex(atom curl)
curl: as above, a result from curl_easy_init that has been passed to a few curl_easy_setopt.

Returns: if an integer is returned, it is a CURLcode (except for CURLE_OK), otherwise it is a single string containing the entire file contents. Note this is not suitable for multi-megabyte downloads, and is not thread safe, whereas the following routine is, on both counts.

CURLcode res = curl_easy_get_file(string url, proxy, filename)

Save the text/binary from url to a new file on your local PC specified by filename. Proxy details can also be set, "" to not use a proxy.

Returns: CURLE_OK on success, any other return value represents an error.
If the specified filename cannot be opened, returns CURLE_CANT_OPEN_FILE

curl_easy_get_file() automatically performs curl_global_init() and curl_global_cleanup() when required, and also curl_easy_init() and curl_easy_cleanup() (every time).
By default libcurl keeps connections open and caches DNS entries automatically.
However, curl_easy_get_file() starts and stops a curl_session for each file downloaded, so it will not be as efficient, as several direct curl_easy_setopt() and curl_easy_perform() calls, when performing multiple downloads.
Also note that CURLOPT_ERRORBUFFER is not used and is not a natural fit for use with curl_easy_get_file(), along with most other debugging techniques, however the fairly trivial code of the included demo download.exw serves as a perfectly good template for something better.
Example 1:
include builtins\libcurl.e
curl_global_init()
atom curl = curl_easy_init()
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com")
CURLcode res = curl_easy_perform(curl)
curl_easy_cleanup(curl)
curl_global_cleanup()
Example 2:
include builtins\libcurl.e
    -- save remote file to local drive
    CURLcode res = curl_easy_get_file("http://example.com", "", "example.html")
    if res!=CURLE_OK then
        ?"error"
    end if
See Also: SEE ALSO , , curl_multi_add_handle, curl_multi_perform, curl_easy_init, curl_easy_cleanup, curl_easy_setopt, CURLcode