Macros | Typedefs | Functions
URL.h File Reference

Detailed Description

URL represent 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. Here is an example where all components are used:

http://user:password@www.foo.bar:8080/document/index.csp?querystring#ref

The following URL components are automatically unescaped according to the escaping mechanism defined in RFC 2396; credentials, path and parameter values.

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

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. More...
 
T URL_create (const char *url,...)
 Factory method for building an URL object using a variable argument list. More...
 
void URL_free (T *U)
 Destroy a URL object. More...
 
const char * URL_toString (T U)
 Returns a string representation of this URL object. More...
 
Properties
const char * URL_getProtocol (T U)
 Get the protocol of the URL. More...
 
const char * URL_getUser (T U)
 Get the user name from the authority part of the URL. More...
 
const char * URL_getPassword (T U)
 Get the password from the authority part of the URL. More...
 
const char * URL_getHost (T U)
 Get the hostname of the URL. More...
 
int URL_getPort (T U)
 Get the port of the URL. More...
 
const char * URL_getPath (T U)
 Get the path of the URL. More...
 
const char * URL_getQueryString (T U)
 Get the query string of the URL. More...
 
const char ** URL_getParameterNames (T U)
 Returns an array of string objects with the names of the parameters contained in this URL. More...
 
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. More...
 
Class methods
char * URL_unescape (char *url)
 Class method, unescape an url string. More...
 
char * URL_escape (const char *url)
 Class method, escape an url string converting unsafe characters to a hex (%HEXHEX) representation. More...
 

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.

The url string must start with a protocol specifier, such as http:// or ftp://

Parameters
urlA string specifying the URL
Returns
A URL object or NULL if the url parameter cannot be parsed as an URL.

◆ URL_create()

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

Factory method for building an 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 an 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
urlA string specifying the URL
Returns
A URL object or NULL if the url parameter cannot be parsed as an URL.

◆ URL_free()

void URL_free ( T U)

Destroy a URL object.

Parameters
UA URL object reference

◆ URL_getProtocol()

const char* URL_getProtocol ( T  U)

Get the protocol of the URL.

Parameters
UAn URL object
Returns
The protocol name

◆ URL_getUser()

const char* URL_getUser ( T  U)

Get the user name from the authority part of the URL.

Parameters
UAn URL object
Returns
A username specified in the URL or NULL if not found

◆ URL_getPassword()

const char* URL_getPassword ( T  U)

Get the password from the authority part of the URL.

Parameters
UAn URL object
Returns
A password specified in the URL or NULL if not found

◆ URL_getHost()

const char* URL_getHost ( T  U)

Get the hostname of the URL.

Parameters
UAn URL object
Returns
The hostname of the URL or NULL if not found

◆ URL_getPort()

int URL_getPort ( T  U)

Get the port of the URL.

Parameters
UAn URL object
Returns
The port number of the URL or -1 if not specified

◆ URL_getPath()

const char* URL_getPath ( T  U)

Get the path of the URL.

Parameters
UAn URL object
Returns
The path of the URL or NULL if not found

◆ URL_getQueryString()

const char* URL_getQueryString ( T  U)

Get the query string of the URL.

Parameters
UAn 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
UAn 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
UAn URL object
nameThe 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
UAn URL object
Returns
The URL string

◆ URL_unescape()

char* URL_unescape ( char *  url)

Class method, unescape an url string.

The url parameter is modified by this method.

Parameters
urlan escaped url string
Returns
A pointer to the unescaped url string

◆ URL_escape()

char* URL_escape ( const char *  url)

Class method, escape an url string converting 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) The caller must free the returned string. If the url parameter is NULL then this method returns NULL, if it is the empty string "" a new empty string is returned.

Parameters
urlan url string
Returns
the escaped string

Copyright © Tildeslash Ltd. All rights reserved.