##Introduction RB-libcURL is a libcURL binding for Realbasic and Xojo projects. It is designed and tested on Windows 7 against curl-7.40.0-devel-mingw32 and associated security and compression libraries (more platforms). The minimum supported libcURL version is 7.15.2.
##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).
- SSL/TLS with certificate validation.
- Full support for RB/Xojo threads
- Automatic decompression (gzip, deflate, etc.) using zlib.
- Stream-oriented, using Xojo's built-in Readable and Writeable interfaces. Download or upload directly to or from a file, MemoryBlock, 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.
Once all the desired options have been set (e.g. URL, port, 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 asynchronous: 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.)
##Examples
- HTTP GET
- HTTP HEAD
- HTTP Pipelining
- HTTP POST
- FTP Download
- FTP Upload
- FTP custom commands
- SMTP Send
- DNS control
