Overview

Parsed web addresses for C.

ULURL represents a parsed web address conforming to the WHATWG specification. You'll use it to validate web links and resolve relative paths before loading them into a View.

Parse an address string and load it into a View:

void LoadAddress(const char* input) {
  ULString text = ulCreateString(input);  // eg, "https://example.com/docs"
  ULURL link = ulCreateURL(text);
  ulDestroyString(text);
 
  if (ulURLIsValid(link)) {
    ULString address = ulURLGetString(link);
    ulViewLoadURL(view, address);
    ulDestroyString(address);
  }
 
  ulDestroyURL(link);
}

Creating and Destroying URLs

Ownership rules for URL handles and returned strings:

Destroy every created URL handle. Functions in the ulCreateURL() family return owned handles that you must release with ulDestroyURL().
Destroy handles even when parsing fails. A failed parse still returns an allocated ULURL, so check ulURLIsValid() before using the address.
Destroy strings returned by URL functions. Getters like ulURLGetString() and ulURLGetPath() return owned ULString handles rather than borrowed strings.

Resolve a relative path against the View's current URL and load the resolved address:

void OpenHelpPage(void) {
  // Borrowed from the View, so we don't destroy it.
  ULString current = ulViewGetURL(view);
  ULURL base = ulCreateURL(current);
 
  ULString relative = ulCreateString("../help/index.html");
  ULURL help = ulCreateURLRelative(base, relative);
  ulDestroyString(relative);
 
  // Returned by a URL function, so we destroy it.
  ULString help_address = ulURLGetString(help);
  ulViewLoadURL(view, help_address);
  ulDestroyString(help_address);
 
  ulDestroyURL(help);
  ulDestroyURL(base);
}

Parsing and Encoding Rules

URL parsing, component access, and query building follow the same rules as the C++ interface (see <Ultralight/URL.h>).

Note: Passing a NULL ULURL handle crashes every function that takes one, except ulDestroyURL(), which accepts NULL and does nothing.

See also: <Ultralight/URL.h>, ulCreateURL(), ulDestroyURL(), ulViewLoadURL()

Functions
ULURL	ulCreateURL (ULString url_string)
	Parse a string as an absolute URL (WHATWG-standard parsing).
ULURL	ulCreateURLRelative (ULURL base, ULString relative)
	Resolve a (possibly relative) reference against a base URL, following the same rules a browser uses to resolve links on a page.
ULURL	ulCreateURLFromFilePath (ULString file_path)
	Create a file: URL from a native file-system path.
ULURL	ulCreateURLCopy (ULURL url)
	Create a copy of an existing URL.
void	ulDestroyURL (ULURL url)
	Destroy a URL previously created with ulCreateURL(), ulCreateURLRelative(), ulCreateURLFromFilePath(), or ulCreateURLCopy().
bool	ulURLIsValid (ULURL url)
	Whether or not the URL parsed successfully.
bool	ulURLIsEmpty (ULURL url)
	Whether or not the URL holds nothing (equivalent to !ulURLIsValid()).
ULString	ulURLGetString (ULURL url)
	Get the canonical serialization of the whole URL ("" if invalid).
bool	ulURLEquals (ULURL url, ULURL other)
	Whether two URLs have the same canonical serialization.
ULString	ulURLGetOrigin (ULURL url)
	Get the origin serialization, like JavaScript's URL.origin.
ULString	ulURLGetScheme (ULURL url)
	Get the scheme, lowercased, without the trailing colon (eg, "https"; "" if invalid).
ULString	ulURLGetHost (ULURL url)
	Get the host, without the port (eg, "example.com"; "" if invalid or hostless).
ULString	ulURLGetHostWithPort (ULURL url)
	Get the host with the explicit port appended, if one is present (eg, "example.com:8080").
bool	ulURLHasPort (ULURL url)
	Whether or not the URL has an explicit port.
unsigned short	ulURLGetPort (ULURL url)
	Get the explicit port number (0 when ulURLHasPort() is false).
ULString	ulURLGetUsername (ULURL url)
	Get the username portion of the URL's credentials, percent-decoded ("" if none).
ULString	ulURLGetPassword (ULURL url)
	Get the password portion of the URL's credentials, percent-decoded ("" if none).
ULString	ulURLGetPath (ULURL url)
	Get the path (eg, "/a/b"; "" if invalid).
ULString	ulURLGetQuery (ULURL url)
	Get the query string, without the leading '?
ULString	ulURLGetFragment (ULURL url)
	Get the fragment, without the leading '#' ("" if none).
bool	ulURLSetScheme (ULURL url, ULString scheme)
	Set the scheme (with or without the trailing colon).
void	ulURLSetHost (ULURL url, ULString host)
	Set the host (without port).
void	ulURLSetPort (ULURL url, unsigned short port)
	Set an explicit port.
void	ulURLClearPort (ULURL url)
	Remove the explicit port, if any.
void	ulURLSetUsername (ULURL url, ULString username)
	Set the username portion of the URL's credentials (percent-encoded as needed).
void	ulURLSetPassword (ULURL url, ULString password)
	Set the password portion of the URL's credentials (percent-encoded as needed).
void	ulURLSetPath (ULURL url, ULString path)
	Set the path.
void	ulURLSetQuery (ULURL url, ULString query)
	Set the raw query string (without the leading '?
void	ulURLSetFragment (ULURL url, ULString fragment)
	Set the fragment (without the leading '#').
bool	ulURLHasQueryParameter (ULURL url, ULString key)
	Whether or not the query contains a parameter with the given key (form-decoded match).
ULString	ulURLGetQueryParameter (ULURL url, ULString key)
	Get the first query-parameter value for the given key, form-decoded ("" if absent).
void	ulURLAppendQueryParameter (ULURL url, ULString key, ULString value)
	Append a key/value pair to the query, form-encoding both.
ULString	ulURLGetFilePath (ULURL url)
	Get the native file-system path for a file: URL.
ULString	ulURLEncodeComponent (ULString component)
	Percent-encode a string for safe embedding inside a URL component.
ULString	ulURLDecodeComponent (ULString encoded)
	Decode a percent-encoded URL component.

Typedefs
typedef struct C_URL *	ULURL
	Opaque handle to a URL object.

Function Documentation

◆ ulCreateURL()

ULURL ulCreateURL ( ULString url_string )

Parse a string as an absolute URL (WHATWG-standard parsing).

Input without a scheme (eg, "example.com") does not parse. The result is then an invalid URL object, which you can test with ulURLIsValid().

Parameters

url_string The string to parse.

Returns: Returns a new ULURL instance (never NULL). You must call ulDestroyURL() when finished.

Warning: A host with non-ASCII characters (an international domain name) needs the library's Unicode data, which the renderer loads. Parse such a URL only after you've called ulCreateRenderer() or ulCreateApp().

◆ ulCreateURLCopy()

ULURL ulCreateURLCopy ( ULURL url )

Create a copy of an existing URL.

Returns: Returns a new ULURL instance. You must call ulDestroyURL() when finished.

◆ ulCreateURLFromFilePath()

ULURL ulCreateURLFromFilePath ( ULString file_path )

Create a file: URL from a native file-system path.

Platform path conventions are handled for you (eg, Windows drive letters and backslashes). Use ulURLGetFilePath() for the reverse conversion.

Parameters

file_path An absolute native file-system path.

Returns: Returns a new ULURL instance (never NULL), invalid if the path cannot be represented. You must call ulDestroyURL() when finished.

◆ ulCreateURLRelative()

ULURL ulCreateURLRelative	(	ULURL	base,
		ULString	relative )

Resolve a (possibly relative) reference against a base URL, following the same rules a browser uses to resolve links on a page.

Parameters

base	The base URL to resolve against.
relative	The reference to resolve: a path, an absolute path, a fragment, or a full absolute URL (which ignores the base).

Returns: Returns a new ULURL instance (never NULL). The result is invalid when the base is invalid, unless relative is itself an absolute URL. You must call ulDestroyURL() when finished.

◆ ulDestroyURL()

void ulDestroyURL ( ULURL url )

Destroy a URL previously created with ulCreateURL(), ulCreateURLRelative(), ulCreateURLFromFilePath(), or ulCreateURLCopy().

◆ ulURLAppendQueryParameter()

void ulURLAppendQueryParameter	(	ULURL	url,
		ULString	key,
		ULString	value )

Append a key/value pair to the query, form-encoding both.

Spaces become + and reserved characters are percent-encoded, so this is the safe way to build search or query URLs from arbitrary text.

Parameters

url	The URL handle.
key	The parameter name (unencoded).
value	The parameter value (unencoded).

◆ ulURLClearPort()

void ulURLClearPort ( ULURL url )

Remove the explicit port, if any.

◆ ulURLDecodeComponent()

ULString ulURLDecodeComponent ( ULString encoded )

Decode a percent-encoded URL component.

This matches JavaScript's decodeURIComponent for well-formed input. Unlike its JavaScript counterpart this function never fails: a malformed escape is passed through unchanged.

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLEncodeComponent()

ULString ulURLEncodeComponent ( ULString component )

Percent-encode a string for safe embedding inside a URL component.

This matches JavaScript's encodeURIComponent: every character except letters, digits, and - _ . ! ~ * ' ( ) is replaced by the percent-encoding of its UTF-8 bytes.

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLEquals()

bool ulURLEquals	(	ULURL	url,
		ULURL	other )

Whether two URLs have the same canonical serialization.

Note: The comparison is textual, not a semantic equivalence test (two URLs that differ only in fragment compare unequal).

◆ ulURLGetFilePath()

ULString ulURLGetFilePath ( ULURL url )

Get the native file-system path for a file: URL.

Returns: Returns a new string, "" for any other scheme or if the URL is invalid. You must call ulDestroyString() when finished.

See also: ulCreateURLFromFilePath()

◆ ulURLGetFragment()

ULString ulURLGetFragment ( ULURL url )

Get the fragment, without the leading '#' ("" if none).

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLGetHost()

ULString ulURLGetHost ( ULURL url )

Get the host, without the port (eg, "example.com"; "" if invalid or hostless).

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLGetHostWithPort()

ULString ulURLGetHostWithPort ( ULURL url )

Get the host with the explicit port appended, if one is present (eg, "example.com:8080").

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLGetOrigin()

ULString ulURLGetOrigin ( ULURL url )

Get the origin serialization, like JavaScript's URL.origin.

Returns: Returns a new string. You must call ulDestroyString() when finished.

Note: Opaque origins (eg, data: URLs) serialize as "null".

◆ ulURLGetPassword()

ULString ulURLGetPassword ( ULURL url )

Get the password portion of the URL's credentials, percent-decoded ("" if none).

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLGetPath()

ULString ulURLGetPath ( ULURL url )

Get the path (eg, "/a/b"; "" if invalid).

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLGetPort()

unsigned short ulURLGetPort ( ULURL url )

Get the explicit port number (0 when ulURLHasPort() is false).

◆ ulURLGetQuery()

ULString ulURLGetQuery ( ULURL url )

Get the query string, without the leading '?

' ("" if none).

Values inside the query are stored encoded. Use ulURLGetQueryParameter() to read a decoded value.

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLGetQueryParameter()

ULString ulURLGetQueryParameter	(	ULURL	url,
		ULString	key )

Get the first query-parameter value for the given key, form-decoded ("" if absent).

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLGetScheme()

ULString ulURLGetScheme ( ULURL url )

Get the scheme, lowercased, without the trailing colon (eg, "https"; "" if invalid).

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLGetString()

ULString ulURLGetString ( ULURL url )

Get the canonical serialization of the whole URL ("" if invalid).

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLGetUsername()

ULString ulURLGetUsername ( ULURL url )

Get the username portion of the URL's credentials, percent-decoded ("" if none).

Returns: Returns a new string. You must call ulDestroyString() when finished.

◆ ulURLHasPort()

bool ulURLHasPort ( ULURL url )

Whether or not the URL has an explicit port.

Note: A scheme-default port is elided during canonicalization and does not count as explicit.

◆ ulURLHasQueryParameter()

bool ulURLHasQueryParameter	(	ULURL	url,
		ULString	key )

Whether or not the query contains a parameter with the given key (form-decoded match).

◆ ulURLIsEmpty()

bool ulURLIsEmpty ( ULURL url )

Whether or not the URL holds nothing (equivalent to !ulURLIsValid()).

Note: A valid URL's canonical serialization is never empty.

◆ ulURLIsValid()

bool ulURLIsValid ( ULURL url )

Whether or not the URL parsed successfully.

◆ ulURLSetFragment()

void ulURLSetFragment	(	ULURL	url,
		ULString	fragment )

Set the fragment (without the leading '#').

Pass an empty string to remove the fragment entirely.

◆ ulURLSetHost()

void ulURLSetHost	(	ULURL	url,
		ULString	host )

Set the host (without port).

Invalid input (eg, a stray colon) and empty input are ignored, leaving the URL unchanged.

Note: This has no effect on non-hierarchical URLs (eg, data:).

◆ ulURLSetPassword()

void ulURLSetPassword	(	ULURL	url,
		ULString	password )

Set the password portion of the URL's credentials (percent-encoded as needed).

Pass an empty string to remove it.

Note: This has no effect on non-hierarchical URLs.

◆ ulURLSetPath()

void ulURLSetPath	(	ULURL	url,
		ULString	path )

Set the path.

The path is encoded as needed. On http(s) URLs an empty path becomes "/".

◆ ulURLSetPort()

void ulURLSetPort	(	ULURL	url,
		unsigned short	port )

Set an explicit port.

A scheme-default port (eg, 443 for https) is elided from the serialization.

Note: This has no effect on non-hierarchical URLs.

◆ ulURLSetQuery()

void ulURLSetQuery	(	ULURL	url,
		ULString	query )

Set the raw query string (without the leading '?

').

Pass an empty string to remove the query entirely. The value is used as-is, so you are responsible for encoding it. To build a query from arbitrary text safely, use ulURLAppendQueryParameter() instead.

◆ ulURLSetScheme()

bool ulURLSetScheme	(	ULURL	url,
		ULString	scheme )

Set the scheme (with or without the trailing colon).

The new scheme is validated and canonicalized (lowercased).

Returns: Returns whether or not the scheme was accepted. On failure the URL is unchanged.

◆ ulURLSetUsername()

void ulURLSetUsername	(	ULURL	url,
		ULString	username )

Set the username portion of the URL's credentials (percent-encoded as needed).

Pass an empty string to remove it.

Note: This has no effect on non-hierarchical URLs.

Typedef Documentation

◆ ULURL

typedef struct C_URL* ULURL

Opaque handle to a URL object.

See also: ulCreateURL(), ulDestroyURL()

Go to the source code of this file.

Overview

Creating and Destroying URLs

Parsing and Encoding Rules

Functions

Typedefs

Function Documentation

◆ ulCreateURL()

◆ ulCreateURLCopy()

◆ ulCreateURLFromFilePath()

◆ ulCreateURLRelative()

◆ ulDestroyURL()

◆ ulURLAppendQueryParameter()

◆ ulURLClearPort()

◆ ulURLDecodeComponent()

◆ ulURLEncodeComponent()

◆ ulURLEquals()

◆ ulURLGetFilePath()

◆ ulURLGetFragment()

◆ ulURLGetHost()

◆ ulURLGetHostWithPort()

◆ ulURLGetOrigin()

◆ ulURLGetPassword()

◆ ulURLGetPath()

◆ ulURLGetPort()

◆ ulURLGetQuery()

◆ ulURLGetQueryParameter()

◆ ulURLGetScheme()

◆ ulURLGetString()

◆ ulURLGetUsername()

◆ ulURLHasPort()

◆ ulURLHasQueryParameter()

◆ ulURLIsEmpty()

◆ ulURLIsValid()

◆ ulURLSetFragment()

◆ ulURLSetHost()

◆ ulURLSetPassword()

◆ ulURLSetPath()

◆ ulURLSetPort()

◆ ulURLSetQuery()

◆ ulURLSetScheme()

◆ ulURLSetUsername()

Typedef Documentation

◆ ULURL