Terminology and Conventions

This page defines the naming and behavioral conventions used throughout LibQurl and this wiki. If a term or pattern here seems unfamiliar, this is the place to look.

Sync and Async

LibQurl renames libcurl's two transfer verbs to reflect their intent:

LibQurl	libcurl	Behavior
Sync()	curl_easy_perform()	Blocking transfer on a single easy handle. Returns when the transfer is complete.
Async()	curl_multi_perform()	Non-blocking transfer through a multi handle. Returns immediately; you poll until still_running is 0.

A single LibQurl() instance can drive any number of both. All options are remembered per-handle.

Handles

LibQurl wraps five libcurl API families, each with its own handle type:

Handle	Created by	Cleans up with	Auto-recreates?
easy_handle	Init() / EasyInit()	Cleanup() / EasyCleanup()	Yes
multi_handle	MultiInit()	MultiCleanup()	Yes
share_handle	ShareInit()	ShareCleanup()	Yes
mime_handle	MimeInit()	MimeCleanup()	No
url_handle	UrlInit()	UrlCleanup()	Yes

These are used in numerous locations throughout the library, with a few common examples being:

curl.SetOpt("URL", "https://www.google.com/", easy_handle)
curl.ReadyAsync([easy_handle],multi_handle)
mime_handle := curl.MimeInit(easy_handle)

If you clean up the last handle of a non-mime type (Easy, Multi, Share, Url), LibQurl automatically creates a fresh one so you are never left without a default. MIME handles do not auto-recreate.

Option Naming

CURLOPT options accept three equivalent forms:

; Bare option name (preferred in this wiki)
curl.SetOpt("CAINFO", "C:\certs\bundle.crt", easy_handle)

; Full libcurl name
curl.SetOpt("CURLOPT_CAINFO", "C:\certs\bundle.crt", easy_handle)

; Underlying constant
curl.SetOpt(10002, "C:\certs\bundle.crt", easy_handle)

All other interfaces — CURLINFO, CURLMOPT, CURLSHOPT, CURLU — use bare names only. There is no prefix form and no constant form. See Setting and Listing Options for examples.

Null()

LibQurl uses a Null() sentinel class to represent "this option was not set."

val := curl.GetOpt("CAINFO", easy_handle)
if (Type(val) = "Null")
    MsgBox "CAINFO is not set on this handle."

This is not AHKv2's native unset. Native unset deletes the variable entirely, which breaks type checks. Null() preserves a real type ("Null") that you can test against.

autoResetToGET

Enabled by default (curl.autoResetToGET = 1). After a transfer completes, ClearPost() is automatically invoked to scrub POST and UPLOAD state from the handle. This prevents stale upload residue from bleeding into the next transfer on the same handle.

To disable:

curl.autoResetToGET := 0

This is currently a class-wide convention but will be changed to per-handle in the future.

Default Download Mode

The default download mode for every easy handle is Magic:

• Data lands in memory.
• Once the 50 MB threshold is crossed, the buffer flushes to a temporary file in A_Temp\LibQurl\ and the transfer continues as a file download.
• GetLastBody() transparently returns text regardless of which mode fired; the transfer page further explains how to handle binary content.

You can override per-handle with WriteToMem(), WriteToFile(), or WriteToMagic(). See Download Modes.

Compressed Transfers

Enabled by default on every easy handle. ACCEPT_ENCODING is set to an empty string (enables all supported encodings) and SSH_COMPRESSION is set to 1. You do not need to configure compression for standard HTTP or SSH transfers.