URL Construction

libcurl's URL API provides structured access to individual components of a URL without manual string building or encoding. LibQurl exposes this through the url_handle.

As with most other APIs, url_handles have a usable default which makes the handle itself an optional parameter when working with just one.

Creating a URL Handle

url_handle := curl.UrlInit()

Setting Parts

UrlSet writes a value to a named part of the URL and accepts optional flags as an array:

ret := curl.UrlSet("SCHEME", "https")
ret := curl.UrlSet("HOST", "www.google.com")
ret := curl.UrlSet("PATH", "/search")

flags := ["APPENDQUERY", "URLENCODE"]
ret := curl.UrlSet("QUERY", "q=test&lang=en", flags)

Getting Parts

UrlGet reads a part back as a string:

scheme := curl.UrlGet("SCHEME")
host   := curl.UrlGet("HOST")
path   := curl.UrlGet("PATH")
full   := curl.UrlGet("URL")

Flags work the same way on retrieval:

full := curl.UrlGet("URL", ["DEFAULT_PORT"])

Null Behavior

By default, a part that was never set returns a Null() sentinel. You can change this to return an empty string on a per-handle basis:

fragment := curl.UrlGet("FRAGMENT", url_handle)
if (Type(fragment) = "Null")
    MsgBox "No fragment was set."

curl.UrlPartReturnsNull(false, url_handle)
fragment := curl.UrlGet("FRAGMENT", url_handle)  ; returns ""

Available Parts

Part	Description
URL	The full assembled URL
SCHEME	e.g. "https", "http", "ftp"
USER	Username
PASSWORD	Password
OPTIONS	Opaque option string
HOST	Hostname or IP
PORT	Port number
PATH	Path component
QUERY	Query string (after ?)
FRAGMENT	Fragment (after #)
ZONEID	Zone ID (IPv6)

Flags

Flag	Effect	Get or Set?
DEFAULT_SCHEME	Assume http if missing	Both
URLENCODE	Apply percent-encoding	Both
ALLOW_SPACE	Permit spaces	Set
APPENDQUERY	Append to existing query	Set
DISALLOW_USER	Reject user component	Set
GUESS_SCHEME	Infer scheme from context	Set
NO_AUTHORITY	Permit URL with no host	Set
NON_SUPPORT_SCHEME	Allow non-standard schemes	Set
PATH_AS_IS	Store path exactly as given	Set
DEFAULT_PORT	Include default port for scheme	Get
GET_EMPTY	Allow empty values	Get
NO_DEFAULT_PORT	Omit default port	Get
NO_GUESS_SCHEME	Do not infer scheme	Get
PUNY2IDN	Convert punycode to IDN	Get
PUNYCODE	Convert to punycode	Get
URLDECODE	Decode percent-encoding	Get

Duplicating a URL Handle

DupeUrl creates a copy of an existing URL handle:

original := curl.UrlInit()
curl.UrlSet("URL", "https://example.com/api/v1", ["PATH_AS_IS"], original)

copy := curl.DupeUrl(original)
; copy has the same URL, can be modified independently
curl.UrlSet("PATH", "/api/v2", ["PATH_AS_IS"], copy)

Using with an Easy Handle

The assembled URL can be fed into an easy handle's URL option:

url_handle := curl.UrlInit()
curl.UrlSet("URL", "https://api.example.com", ["PATH_AS_IS"], url_handle)
target := curl.UrlGet("URL",, url_handle)

curl.SetOpt("URL", target)
curl.Sync()

Cleanup

UrlCleanup releases the URL handle. Like other handle types, the last one auto-recreates:

curl.UrlCleanup(url_handle)

Where to Go Next

• Share Interface — sharing cookies, DNS, and SSL state across handles
• URL Handle Reference — full method list