strogo / rb-libcurl

REALbasic and Xojo bindings for 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. It is designed and tested using REALstudio 2011r4.3 on Windows 7 against curl-7.40.0-devel-mingw32 and associated security (e.g. OpenSSL, SChannel, etc.) and compression (i.e. zlib) libraries. Library binaries for other platforms are available, or can 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.

##Example This example performs a synchronous HTTP GET request on the calling thread. More examples.

  Dim curl As New cURLClient
  Dim page As String
  If curl.Get("http://www.example.com/index.html") Then 
    page = curl.GetDownloadedData
  End If

##Hilights

• Synchronous and asynchronous transfers
• Use any supported protocol (DICT, FILE, FTP, FTPS, Gopher, HTTP(1.0, 1.1, and 2.0), HTTPS, IMAP, IMAPS, LDAP, LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMTP, SMTPS, Telnet and TFTP).
• Automatic browser-like HTTP cookie management.
• SSL/TLS with certificate validation, using any one of several SSL libraries.
• Full support for RB/Xojo threads
• Automatic decompression (gzip, deflate, etc.) using zlib.
• 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.
• Easy to use, but still exposing the full range of libcURL's features.
• Interact directly with libcurl via declares and callback methods; no shell or plugins required.

##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.

---

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:

Handle Type	Object Class	Comment
curl_easy	EasyHandle	A persistent collection of sockets, caches, and options which together will be used when libcURL is told to perform a transfer.
curl_multi	MultiHandle	A set of one or more curl_easy handles whose transfers will be performed simultaneously.
curl_share	ShareHandle	A set of one or more curl_easy handles that will share SSL session data, DNS caches, and/or HTTP cookies.
slist	ListPtr	A linked list of string values.
form	MultipartForm	An HTML form which libcURL encode as multipart/form-data.

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 overridden 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 halts 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-halting 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 (Win32x86+OpenSSL+ZLib), 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 HEAD
• HTTP POST
• HTTP TRACE
• HTTP Cookies
• HTTP GET via a proxy server
• FTP Download
• FTP Upload
• FTP custom commands
• FTP directory enumeration
• SMTP Send
• DNS control
• DICT lookup example
• FILE protocol example