charonn0 / RB-libcURL

Introduction

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.

RB-libcURL is a libcurl binding for Realbasic and Xojo ("classic" framework) projects. Library binaries for various platforms are available, or can be built from source.

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.

Example

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

Highlights

• 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. gzip or deflate).†
• 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

Synopsis

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 a simplified client interface that is appropriate for most types of transfers, you should use the cURLClient class. Refer to the examples below for demonstrations of cURLClient.

For more thorough documentation of individual classes and methods refer to the wiki.

Each libcURL handle or handle equivalent is managed by an object class. These handle-managing classes all descend from a common ancestor, the abstract cURLHandle class.

libcURL uses several different handle types or equivalents:

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 EasyHandle.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 MultiHandle.Perform (or MultiHandle.PerformOnce on a RB/Xojo thread.)

How to incorporate libcURL into your Realbasic/Xojo project

Import the libcURL module

1. Download the RB-libcURL project either in ZIP archive format or by cloning the repository with your Git client.
2. Open the RB-libcURL project in REALstudio or Xojo. Open your project in a separate window.
3. 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.

Examples

• 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