libcurl is a cross-platform multi-protocol network transfer library. It is widely used both as a stand-alone command-line utility and as a standard or optional library for many programming languages and development environments.
The minimum supported libcURL version is 7.15.2. The recommended minimum version is 7.33.0. Versions prior to 7.33.0 will function with degraded features, but versions prior to 7.15.2 will not function properly at all. The minimum supported Xojo version is RS2010R4.
This example performs a synchronous HTTP GET request on the calling thread. More examples.
Dim curl As New cURLClient If curl.Get("http://www.example.com/index.html") Then Dim page As String = curl.GetDownloadedData() End If
- Synchronous and asynchronous transfers
- Use any protocol supported by libcURL: DICT, FILE, FTP, FTPS, Gopher, HTTP(1.0, 1.1, and 2† ), HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet and TFTP.
- Support for modern HTTP features like persistent connections, pipelining, and multiplexing†.
- Automatic browser-like HTTP cookie management.
- Automatic decompression of compressed HTTP downloads (i.e.
- Automatic decoding of HTTP chunked Transfer-Encoding.
- SSL/TLS with certificate validation, using any one of several SSL libraries†.
- Transparent support for RB/Xojo threads.
- Full support for HTTP, SOCKS4, SOCKS4A, SOCKS5, and SOCKS5_HOSTNAME proxy servers.
- Stream-oriented, using Xojo's built-in Readable and Writeable interfaces. Download or upload directly to or from a file, MemoryBlock, Xojo socket, or your own custom class.
- A consistent, high-level API over the full range of libcURL's features.
- Interact directly with libcurl using idiomatic RB/Xojo objects, methods, and events; no shell or plugins required.
- International domain name support†.
- 64-bit ready.
- IPv6 support.
- High performance, even when doing several transfers at once.
- Build complex HTTP forms, including nested forms and file uploads.
†= feature might not be available at run-time due to a build-time decision of the installed version of libcURL
It is strongly recommended that you familiarize yourself with libcURL, as this project preserves the semantics of libcURL's API in an object-oriented, Xojo-flavored wrapper.
For more thorough documentation of individual classes and methods refer to the wiki.
libcURL uses several different handle types or equivalents:
|Handle Type||Object Class||Comment|
||A persistent collection of sockets, caches, and options which together will be used when libcURL is told to perform a transfer.|
||A set of one or more
||A set of one or more
||A linked list of string values.|
||An HTTP form which libcURL will encode as
||A MIME message (HTTP form, email message, etc.) (libcURL 7.56.0 or later)|
||An interface to libcurl's URL parser (libcURL 7.62.0 or later)|
Every transfer is associated with an
EasyHandle. After creating a new
EasyHandle instance, you can set various options for the handle by calling the
SetOption method with the desired cURL option number and its new value. Options will persist until they are overwritten or reset.
Once all the desired options have been set (e.g. URL, port, username and/or password, cookies, etc.) you are ready to begin the transfer. Depending on your specific requirements, you can do it in one of several ways.
You may call
Perform directly. However, this is a blocking call; not merely synchronous: the entire application blocks for the duration of the transfer. As such, it is useful only in single-threaded console applications.
To perform one or more transfers in a non-blocking manner use the
MultiHandle class. The
MultiHandle class represents a
curl_multi handle (AKA a "stack"). Add the
EasyHandle to the multi stack and then call
PerformOnce on a RB/Xojo thread.)
How to incorporate libcURL into your Realbasic/Xojo project
Import the libcURL module
- Download the RB-libcURL project either in ZIP archive format or by cloning the repository with your Git client.
- Open the RB-libcURL project in REALstudio or Xojo. Open your project in a separate window.
- Copy the libcURL module and the DEFAULT_CA_INFO_PEM file into your project and save.
Ensure the libcURL shared library is installed
libcURL is installed by default on most Unix-like operating systems, including OS X and most Linux distributions.
Windows does not have it installed by default, you will need to ship all the necessary DLLs with your application. You can use pre-built DLLs available here, or you can build them yourself from source.
Depending on compile-time options, you may need to include additional DLLs for other libraries like OpenSSL or ZLib. Newly added features like HTTP/2 support may require building the latest version from source with special build flags and additional libraries. Review the libcURL documentation for the feature you're interested in.
RB-libcURL will raise a PlatformNotSupportedException when used if all required DLLs/SOs/DyLibs are not available at runtime.
- HTTP GET
- HTTP GET with a persistent connection
- HTTP GET with pipelining
- HTTP HEAD
- HTTP POST
- HTTP TRACE
- HTTP Cookies
- Using a proxy
- FTP Download
- FTP Upload
- FTP custom commands
- FTP directory listing
- SMTP Send
- POP3 examples
- DNS control
- DICT lookup example
- FILE protocol example
- Multiple Simultaneous Transfers
- Query the server for protocol-specific metadata