URL.h File Reference

Detailed Description

URL represents an immutable Uniform Resource Locator.

A Uniform Resource Locator (URL), is used to uniquely identify a resource on the Internet. The URL is a compact text string with a restricted syntax that consists of four main components:

protocol://<authority><path><query>

The protocol part is mandatory, the other components may or may not be present in an URL string. For instance the file protocol only use the path component while a http protocol may use all components.

The following URL components are automatically unescaped according to the escaping mechanism defined in RFC 2396; credentials, path and parameter values. If you use a password with non-URL safe characters, you must URL escape the value.

An IPv6 address can be used for host as defined in RFC2732 by enclosing the address in [brackets]. For instance, mysql://[2010:836B:4179::836B:4179]:3306/test

For more information about the URL syntax and specification, see, RFC2396 - Uniform Resource Identifiers (URI): Generic Syntax

Example:

URL_T url = URL_new("postgresql://user:password@example.com:5432/database?use-ssl=true");
 
// Retrieve and print various components of the URL
printf("Protocol: %s\n", URL_getProtocol(url));
printf("Host:     %s\n", valueOr(URL_getHost(url), "Not specified"));
printf("Port:     %d\n", valueOr(URL_getPort(url), -1));
printf("User:     %s\n", valueOr(URL_getUser(url), "Not specified"));
printf("Password. %s\n", valueOr(URL_getPassword(url), "Not specified"));
printf("Path:     %s\n", valueOr(URL_getPath(url), "Not specified"));
 
// Get a specific parameter value
printf("SSL Enabled: %s\n", valueOr(URL_getParameter(url, "use-ssl"), "false"));

Macros
#define	T   URL_T

Typedefs
typedef struct URL_S *	T

Functions
T	URL_new (const char *url)
	Create a new URL object from the url parameter string.
T	URL_create (const char *url,...)
	Build a new URL object from the url parameter string.
void	URL_free (T *U)
	Destroy a URL object.
Properties
const char *	URL_getProtocol (T U)
	Gets the protocol of the URL.
const char *	URL_getUser (T U)
	Gets the username from the URL's authority part.
const char *	URL_getPassword (T U)
	Gets the password from the URL's authority part.
const char *	URL_getHost (T U)
	Gets the hostname of the URL.
int	URL_getPort (T U)
	Gets the port of the URL.
const char *	URL_getPath (T U)
	Gets the path of the URL.
const char *	URL_getQueryString (T U)
	Gets the query string of the URL.
const char **	URL_getParameterNames (T U)
	Returns an array of string objects with the names of the parameters contained in this URL.
const char *	URL_getParameter (T U, const char *name)
	Returns the value of a URL parameter as a string, or NULL if the parameter does not exist.
Functions
const char *	URL_toString (T U)
	Returns a string representation of this URL object.
Class functions
char *	URL_unescape (char *url)
	Unescape a URL string.
char *	URL_escape (const char *url)
	Escape a URL string.

Macro Definition Documentation

T

#define T   URL_T

Typedef Documentation

T

typedef struct URL_S* T

Function Documentation

URL_new()

T URL_new

(

const char *

url

)

Create a new URL object from the url parameter string.

Parameters

url	A string specifying the URL

Returns

A URL object or NULL if the url parameter cannot be parsed as a URL.

URL_create()

T URL_create	(	const char *	url,
			... )

Build a new URL object from the url parameter string.

Factory method for building a URL object using a variable argument list. Important: since the '%' character is used as a format specifier (e.g. %s for string, %d for integer and so on), submitting a URL escaped string (i.e. a %HEXHEX encoded string) in the url parameter can produce undesired results. In this case, use either the URL_new() method or URL_unescape() the url parameter first.

Parameters

url	A string specifying the URL

Returns

A URL object or NULL if the url parameter cannot be parsed as a URL.

URL_free()

void URL_free

(

T *

U

)

Destroy a URL object.

Parameters

U	A URL object reference

URL_getProtocol()

const char * URL_getProtocol

(

T

U

)

Gets the protocol of the URL.

Parameters

U	A URL object

Returns

The protocol name

URL_getUser()

const char * URL_getUser

(

T

U

)

Gets the username from the URL's authority part.

Parameters

U	A URL object

Returns

A username specified in the URL or NULL if not found

URL_getPassword()

const char * URL_getPassword

(

T

U

)

Gets the password from the URL's authority part.

Parameters

U	A URL object

Returns

A password specified in the URL or NULL if not found

URL_getHost()

const char * URL_getHost

(

T

U

)

Gets the hostname of the URL.

Parameters

U	A URL object

Returns

The hostname of the URL or NULL if not found

URL_getPort()

int URL_getPort

(

T

U

)

Gets the port of the URL.

Parameters

U	A URL object

Returns

The port number of the URL or -1 if not specified

URL_getPath()

const char * URL_getPath

(

T

U

)

Gets the path of the URL.

Parameters

U	A URL object

Returns

The path of the URL or NULL if not found

URL_getQueryString()

const char * URL_getQueryString

(

T

U

)

Gets the query string of the URL.

Parameters

U	A URL object

Returns

The query string of the URL or NULL if not found

URL_getParameterNames()

const char ** URL_getParameterNames

(

T

U

)

Returns an array of string objects with the names of the parameters contained in this URL.

If the URL has no parameters, the method returns NULL. The last value in the array is NULL. To print all parameter names and their values contained in this URL, the following code can be used:

const char **params = URL_getParameterNames(U);
if (params) {
    for (int i = 0; params[i]; i++)
        printf("%s = %s\n", params[i], URL_getParameter(U, params[i]));
}

Parameters

U	A URL object

Returns

An array of string objects, each string containing the name of a URL parameter; or NULL if the URL has no parameters

URL_getParameter()

const char * URL_getParameter	(	T	U,
		const char *	name )

Returns the value of a URL parameter as a string, or NULL if the parameter does not exist.

If you use this method with a multi-valued parameter, the value returned is the first value found. Lookup is case-sensitive.

Parameters

U	A URL object
name	The parameter name to lookup

Returns

The parameter value or NULL if not found

URL_toString()

const char * URL_toString

(

T

U

)

Returns a string representation of this URL object.

Parameters

U	A URL object

Returns

The URL string

URL_unescape()

char * URL_unescape

(

char *

url

)

Unescape a URL string.

The url parameter is modified by this method.

Parameters

url	an escaped URL string

Returns

A pointer to the unescaped url string

URL_escape()

char * URL_escape

(

const char *

url

)

Escape a URL string.

Converts unsafe characters to a hex (HEXHEX) representation. The following URL unsafe characters are encoded: <>"#%{}|^ []` as well as characters in the interval 00-1F hex (0-31 decimal) and in the interval 7F-FF (127-255 decimal). If the url parameter is NULL then this method returns NULL, if it is the empty string "" a new empty string is returned. The caller must free the returned string.

Parameters

url	a URL string

Returns

The escaped string.