# libcurl

A wrapper for libcurl, a free and easy-to-use client-side URL transfer library, supporting DICT, FILE, FTP, FTPS, Gopher, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet and TFTP. libcurl also supports SSL certificates, HTTP POST, HTTP PUT, FTP uploading, HTTP form based upload, proxies, cookies, user+password authentication (Basic, Digest, NTLM, Negotiate, Kerberos), file transfer resume, http proxy tunneling and more!
libcurl is highly portable, it builds and works identically on numerous (20+) platforms.
libcurl is free, thread-safe, IPv6 compatible, feature rich, well supported, fast, thoroughly documented and is already used by many known, big and successful companies.
I strongly recommend reading https://curl.haxx.se/libcurl/ - this is merely a quick lookup; think of it as documentation of the wrapper rather than the underlying functionality, not that it deliberately tries to fall short. However, libcurl is now over 20 years old, but still gets regular updates and releases, which all makes it rather unlikely that this will ever cover every last inch of it. Out of necessity, this documentation is more helpful when trying to understand/debug existing code, and although not deliberately so, it probably is a bit less helpful when writing/designing brand new code.
DEV: out-of date, the windows dlls are now part of the std distro...
While builtins\libcurl.e (not an autoinclude) is distributed as part of the standard Phix distribution, the dynamic library it needs may already be installed on linux, but on windows must be separately downloaded from https://curl.haxx.se/download.html or, for win32/64, I selected the 7.57.0 builds by Stefan Kanthak from that page and made a copy here: http://phix.x10.mx/pmwiki/pmwiki.php?n=Main.Libcurldlls
pwa/p2js: Due to the requirement of said dll/so, not to mention all the CORS restrictions, none of these routines are supported within a web browser.

### Example:

Copy

    constant url = "http://example.com",
             out = "example.html"

    printf(1, "\nattempting to download remote file %s to local file %s\n\n", {url,out})

    include libcurl.e

    CURLcode res = curl_easy_get_file(url,"",out) -- (no proxy)
    if res!=CURLE_OK then
       printf(1, "Error %d downloading file\n", res)
    else
       printf(1, "file %s saved\n", {out})
    end if

It does not get any simpler than that, however libcurl can handle almost anything you can imagine (at least as a client, rather than a server) and obviously things can, and often do, get rather more involved - but only by as much as you need it to.