FAQ

##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 usage examples of the cURLClient class.

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

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

1. All variables, constants, methods, etc. should have concise yet meaningful names, given in CamelCase.

2. If a method performs an action then the method name should include the action name; methods themselves should be written such that their entire purpose can be summed up in one or two words (i.e. the method name) plus the names and types of the parameters and return value. This does not mean that names should be phrases describing the method: CreateOrOpenFileAndMoveToEnd(Path As String) is bad ; OpenFile(Path As String, Create As Boolean, Position As Integer) is good.

3. Callback methods must explicitly declare their calling convention, even if it's not required.

4. Foo.Constructor() always creates a brand new instance of Foo. Foo.Constructor(Foo) always creates a new instance of Foo that duplicates the characteristics of the instance of Foo that is passed as an argument.

5. The lexical scope of any method, variable, constant, etc. shall default to private. It can only be promoted to protected if you have a reason, and to public if your reason is good. Global scope requires a damned good reason. Destructor methods are always private.

6. If a class has many Constructor methods, you should consider changing some of them into shared methods with more meaningful names.

7. All variables, etc. should organized in the narrowest possible logical scope. For example, a method that operates on a class should be defined in that class rather than in some "helpers" module.

8. "Helpers" modules are forbidden except as private submodules (i.e., inaccessible to users.)

9. Operator_Convert() As PRIMITIVE is forbidden. "PRIMITIVE" means any type that is not a class, array, structure, or enum.

10. Use standard RB/Xojo capitalization and formatting. Select a block of code in the IDE, right click on it, and then choose "Standardize format".

11. In accord with #7, the loop variable in a For loop should be declared within the For statement. For example:

 For i As Integer = 0 To 9

Not:

 Dim i As Integer
 For i = 0 To 9