Download Modes

LibQurl supports three download modes for the response body. The default is Magic. You can override per-handle with WriteToMem(), WriteToFile(), or WriteToMagic().

Headers have their own parallel pair: HeaderToMem() and HeaderToFile().

Memory

The body lands in a buffer in RAM. Retrieve it as text with GetLastBody().

curl.SetOpt("URL", "https://example.com/api/data")
curl.HeaderToMem()
curl.WriteToMem()
curl.Sync()

headers := curl.GetLastHeaders()
body    := curl.GetLastBody()

Best for: API responses, JSON payloads, anything you need as a string in a variable.

File

The body is written directly to a path on disk. No buffer in RAM, no GetLastBody() call needed — the data is already where you put it.

curl.SetOpt("URL", "https://example.com/large-file.zip")
curl.HeaderToFile("C:\downloads\headers.txt")
curl.WriteToFile("C:\downloads\file.zip")
curl.Sync()

Best for: large downloads, archives, anything you want on disk without touching memory.

Magic

The hybrid. Data starts in memory. Once the size threshold is crossed, the buffer flushes to a temporary file in A_Temp\LibQurl\ and the transfer continues as a file download. These temporary files are deleted as the class shuts down; it is the caller's responsibility to save anything that got flushed to disk.

This is the default mode, so you do not need to call WriteToMagic() explicitly. Calling it is how you set a custom threshold:

; Default 50 MB threshold (no call needed, this is the default)
curl.WriteToMagic()

; Custom 25 MB threshold
curl.WriteToMagic(1024 ** 2 * 25)

; Custom 100 MB threshold
curl.WriteToMagic(1024 ** 2 * 100)

GetLastBody() & GetLastHeaders()

GetLastBody() is the retrieval method that works across all three payload download modes. Regardless of whether the body ended up as a Buffer or a File, this method hands it back to you. GetLastHeaders() functions identically for headers.

Signature

GetLastHeaders(returnAsEncoding := "UTF-8", easy_handle?)
GetLastBody(returnAsEncoding := "UTF-8", easy_handle?)

First Parameter: Encoding or Sentinel

The first parameter is primarily a StrGet encoding. Pass any Windows codepage or encoding name:

body := curl.GetLastBody("UTF-8")
body := curl.GetLastBody("UTF-16LE")
body := curl.GetLastBody("CP1252")

It also accepts three sentinel values that bypass encoding and return the raw stored object, but only if the stored type matches:

Sentinel	Returns raw object if stored type is
"Object"	any Object
"File"	File
"Buffer"	Buffer

If the sentinel does not match the stored type, the method falls through to normal text retrieval.

Second Parameter: Handle

Optional. Defaults to the first created easy handle. Pass a specific handle when you have multiple:

body := curl.GetLastBody(, easy_handle)

Integer Convenience

If you pass an integer as the first parameter and do not pass a handle, it is reinterpreted as the easy handle:

; These two are equivalent:
body := curl.GetLastBody(, easy_handle)
body := curl.GetLastBody(easy_handle)

; These two are also equivalent:
headers := curl.GetLastHeaders(, easy_handle)
headers := curl.GetLastHeaders(easy_handle)

Safely handling returned data objects

All three WriteToX modes (Mem/File/Magic) funnel downloads to either a File object or a Buffer object. File always writes to a File, Mem always writes to a Buffer, and Magic can be either based on if it hit the flush threshold or not.

For both object types, pure ASCII/UTF text is returned identically. For example, a 10mb json payload can be parsed with the same calls as a 100mb json payload even though the default Magic flush would result in different underlying objects.

If you're working with binary data then AHK's interactions differ depending on the object in question. A simple switch statement can help you normalize between the two when using Magic mode:

; Get the raw object and check which mode fired
body := curl.GetLastBody("Object")

switch Type(body) {
    case "Buffer":
        bytes := body.size
    case "File":
        bytes := body.length
}

;script continues using the bytes variable
do.something(bytes)

Quick Reference

You want...	Call
Body as UTF-8 text (default)	curl.GetLastBody()
Body as a specific encoding	curl.GetLastBody("CP1252")
Raw object, check type yourself	curl.GetLastBody("Object")
Force File return (if it is a File)	curl.GetLastBody("File")
Force Buffer return (if it is a Buffer)	curl.GetLastBody("Buffer")
Specific handle	curl.GetLastBody(, easy_handle)

Choosing a Mode

Situation	Mode
API response, JSON, small payload	Memory
Large file, archive, you want it on disk	File
API where payloads are usually small but can spike	Magic (default)
You want to cap memory usage at a specific size	Magic with custom threshold

Where to Go Next

• Setting and Inspecting Headers — header retrieval and inspection in detail
• POST and Upload — sending data in the opposite direction