FAQ

• I just got here where do I start?
• I want to translate a curl command line
• I need HALP!
• Common problems
• What are these Readable and Writeable parameters for?
• I found a bug!
• I have an idea!
• Style guide

I just got here, where do I start?

Use the cURLClient class. It uses sane defaults and handles all of the boilerplate code for you. You can drop a cURLClient onto a window or create one purely in code. Refer to the examples section for some demonstrations of the cURLClient class.

I want to translate a curl command line

Refer to the command line equivalents table.

I need HALP!

Unfortunately, Github doesn't offer any kind of user forum feature for projects. If you need help with using this project then you should post on the Xojo forums. I regularly check the forums for interesting topics, and a topic about one of my projects will certainly catch my eye.

Common problems

1. PlatformNotSupportedException on first use This means that libcURL could not be loaded at runtime, or that the loaded version is too old.
2. Cookies from a file aren't read immediately libcURL waits until the next transfer attempt before reading cookies from a file. After loading a cookie file you must attempt a transfer before querying the CookieEngine.
3. The CookieEngine doesn't see updates to cookies You must call CookieEngine.Invalidate to refresh the cookie list whenever cookies might be updated. If you're using the cURLClient class then this is done automatically after each transfer.
4. Transfers complete with one of these curl error codes:
   • CURLE_HTTP_RETURNED_ERROR (22) The server returned an error, such as 404 Not Found, and EasyHandle.FailOnServerError is set to True.
   • CURLE_WRITE_ERROR (23) Downloaded data could not be written. Ensure that either EasyHandle.DataAvailable is being handled or that EasyHandle.DownloadStream is a valid Writeable stream.
   • CURLE_READ_ERROR (26) Upload data could not be read. Ensure that either EasyHandle.DataNeeded is being handled or that EasyHandle.UploadStream is a valid Readable stream.
   • CURLE_ABORTED_BY_CALLBACK (42) An unhandled exception was raised in a callback, causing the transfer to abort.
   • CURLE_SSL_CACERT (60) The server's SSL certificate could not be verified because it is not signed by a trusted certificate authority. If this is expected (e.g. a self-signed cert) then set EasyHandle.Secure to False. If this is not expected then make sure that EasyHandle.CA_ListFile is valid.

What are these Readable and Writeable parameters for?

In many places in this project you will see methods that accept a Readable and/or Writeable object as a parameter, for example cURLClient.Get or MultipartForm.Serialize,. If you're not very familiar with them then you might be confounded by what you're expected to do and why you can't just use a plain old string.

By using these class interfaces we get several important benefits that are absent when passing strings around.

For one, it means we can automatically support any class that implements these interfaces. This includes a number of built-in classes such as the BinaryStream, TCPSocket, IPCSocket, StdIn, StdErr, and StdOut.

Another benefit is the dramatic performance boost. Strings are immutable in RB/Xojo, which means that any change involves allocating new memory and copying the old memory. Downloads and uploads might involve millions of small reads and writes and the size of the strings being copied can become exceedingly large (hundreds or thousands of MB). By eliminating the copying we can reduce CPU load and memory churn. This also minimizes the total memory use to (at most) the size of the data. (more info)

I found a bug!

First, make sure you are using the latest revision of the master branch. If you have the latest revision and the bug persists, then you should create a new issue in the bug tracker.

If you also know how to fix the bug, then please create a pull request against the latest revision on the master branch in addition to creating an issue (and reference the issue number in your pull request.) See below for the code style guide.

I have an idea!

This is an open-source project so contributions are of course welcome. Even if you don't have any code to contribute, ideas and suggestions can be submitted as issues in the bug tracker using the "suggestion" tag.

If you do have code to contribute then you should create a pull request against the latest revision on the master branch; if your code addresses a bug then reference the issue number in your pull request.

Style Guide

When contributing code, please make an effort to conform to these guidelines.