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 primary purpose of this class is to wrap database connection URLs. The URL class does not normalize the path, nor escape or unescape URL components according to the escaping mechanism defined in RFC 2396. It is the responsibility of the caller to escape or unescape fields prior to calling URL.

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

Defines

#define T   URL_T

Typedefs

typedef struct TT

Functions

T URL_new (const char *url)
 Create a new URL object from the url parameter string.
T URL_create (const char *url,...)
 Factory method for building an URL object using a variable argument list.
void URL_free (T *U)
 Destroy a URL object.
Properties
const char * URL_getProtocol (T U)
 Get the protocol of the URL.
const char * URL_getUser (T U)
 Get the user name from the authority part of the URL.
const char * URL_getPassword (T U)
 Get the password from the authority part of the URL.
const char * URL_getHost (T U)
 Get the hostname of the URL.
int URL_getPort (T U)
 Get the port of the URL.
const char * URL_getPath (T U)
 Get the path of the URL.
const char * URL_getQueryString (T U)
 Get 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.
const char * URL_toString (T U)
 Return a string representation of this URL object.
class methods
char * URL_unescape (char *url)
 Class method, unescape an url string.
char * URL_escape (const char *url)
 Class method, escape an url string converting unsafe characters to a hex (%HEXHEX) representation.
char * URL_normalize (char *path)
 Class method, normalize an URL path string.


Define Documentation

#define T   URL_T


Typedef Documentation

typedef struct T* T


Function Documentation

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

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

void URL_free ( T U  ) 

Destroy a URL object.

Parameters:
U A URL object reference

const char* URL_getProtocol ( T  U  ) 

Get the protocol of the URL.

Parameters:
U An URL object
Returns:
The protocol name

const char* URL_getUser ( T  U  ) 

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

Parameters:
U An URL object
Returns:
A username specified in the URL or NULL if not found

const char* URL_getPassword ( T  U  ) 

Get the password from the authority part of the URL.

Parameters:
U An URL object
Returns:
A password specified in the URL or NULL if not found

const char* URL_getHost ( T  U  ) 

Get the hostname of the URL.

Parameters:
U An URL object
Returns:
The hostname of the URL or NULL if not found

int URL_getPort ( T  U  ) 

Get the port of the URL.

Parameters:
U An URL object
Returns:
The port number of the URL or -1 if not specified

const char* URL_getPath ( T  U  ) 

Get the path of the URL.

Parameters:
U An URL object
Returns:
The path of the URL or NULL if not found

const char* URL_getQueryString ( T  U  ) 

Get the query string of the URL.

Parameters:
U An URL object
Returns:
The query string of the URL or NULL if not found

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 An 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

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 An URL object
name The parameter name to lookup
Returns:
The parameter value or NULL if not found

const char* URL_toString ( T  U  ) 

Return a string representation of this URL object.

Parameters:
U An URL object
Returns:
The URL string

char* URL_unescape ( char *  url  ) 

Class method, unescape an url string.

The url parameter is modified by this method.

Parameters:
url an escaped url string
Returns:
A pointer to the unescaped url string

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:
url an url string
Returns:
the escaped string

char* URL_normalize ( char *  path  ) 

Class method, normalize an URL path string.

The path parameter is modified by this method. Passing a NULL path parameter returns NULL. Examples:

pathnormalized path
/foo///foo/
/foo/.//foo/
/foo/../bar/bar
/foo/../bar//bar/
/foo/../bar/../baz/baz
//foo//./bar/foo/bar
/../foo/foo
/a/../b/../../x/x
/.././..//
/../

Parameters:
path The path to normalize
Returns:
A pointer to the path parameter

Copyright © 2004-2011 Tildeslash Ltd. All rights reserved.