Falcon::URI Class Reference

RFC 3986 - Uniform Resource Identifier. More...

#include <uri.h>

Inheritance diagram for Falcon::URI:

List of all members.

Public Member Functions

void clear ()

Clears the content of this URI.

uint32 fieldCount ()

Enumerates the query fields - counts the fields.

bool firstField (String &key, String &value)

Enumerates the query fields - gets the first field.

void fragment (const String &s)

Sets the fragment part.

const String & fragment () const

Returns the fragment part.

const String & get (bool synthQuery=true) const

Returns the current URI.

bool getField (const String &key, String &value) const

Returns the required value, if it exists.

bool hasField (const String &f) const

Returns true if the query part has this field.

void host (const String &h)

Sets a different host for this URI.

const String & host () const

Returns current host.

bool isValid () const

Returns true if the URI is valid.

const String & makeQuery () const

Synthetizes a query field out of the key-values stored in this URI object.

bool nextField (String &key, String &value)

Enumerates the query fields - gets the next field.

bool parse (const String &newUri, bool parseQuery=false, bool decode=true)

Parses the given string into this URI.

bool parseQuery (const String &q, bool decode=true)

Changes query and the parses it field.

bool parseQuery (bool decode=true)

Parses the query field.

void path (const Path &p)

Sets a different path for this URI.

void path (const String &p)

Sets a different path for this URI.

const String & path () const

Returns current path.

Path & pathElement ()

Returns current path as a path class.

const Path & pathElement () const

Returns current path as a path class.

void port (const String &h)

Sets a different port for this URI.

const String & port () const

Returns current port.

const String & query () const

Returns previously set query.

void query (const String &q, bool encode=false)

Sets the query field of this URI.

bool removeField (const String &key)

Removes a query field.

void scheme (const String &s)

Sets a different scheme for this URI.

const String & scheme () const

Normalzies the URI sequence.

void setField (const String &key, const String &value)

Sets a given query field.

URI (const URI &other)

Copy constructor.

URI (const String &suri)

Complete URI constructor.

URI ()

Empty constructor.

void userInfo (const String &s)

Sets a different userInfo for this URI.

const String & userInfo () const

Returns current userInfo.

virtual ~URI ()

Static Public Member Functions

static unsigned char CharToHex (unsigned char ch)

static unsigned char HexToChar (unsigned char ch)

static bool isGenDelim (uint32 chr)

Character is a general delimiter under RFC3986.

static bool isMainDelim (uint32 chr)

Character is main section delimiter under RFC3986.

static bool isResDelim (uint32 chr)

Character is a reserved delimiter under RFC3986.

static bool isSubDelim (uint32 chr)

Character is a subdelimiter under RFC4986.

static String URLDecode (const String &source)

static bool URLDecode (const String &source, String &target)

Decode an URI-URL encoded string.

static String URLEncode (const String &source)

static void URLEncode (const String &source, String &target)

Friends

class Path

Detailed Description

RFC 3986 - Uniform Resource Identifier.

This class offer falcon engine and its users an interface to URI.

Constructor & Destructor Documentation

Falcon::URI::URI ( )

Empty constructor.

Creates an empty URI. To be filled at a later time.

Falcon::URI::URI ( const String & suri )

Complete URI constructor.

Decodes the uri and parses it in its fields.

In case URI is not valid, isValid() will return false after construction.

Falcon::URI::URI ( const URI & other )

Copy constructor.

Copies everything in the other URI, including validity.

virtual Falcon::URI::~URI ( ) [virtual]

Member Function Documentation

static unsigned char Falcon::URI::CharToHex ( unsigned char ch ) [inline, static]

void Falcon::URI::clear ( )

Clears the content of this URI.

uint32 Falcon::URI::fieldCount ( )

Enumerates the query fields - counts the fields.

If the query has fields, or if fields have been explicitly set throug setField() method, returns the count of fields stored in this URI.

Note:: The query element must have been previously parsed, or fields must have been explicitly inserted.

Returns:: count of fields in this query, 0 for none.

bool Falcon::URI::firstField	(	String &	key,
		String &	value
	)

Enumerates the query fields - gets the first field.

Returns true if there is a first field in the query.

Note:: The query element must have been previously parsed, or fields must have been explicitly inserted.

Parameters:

	key	a string where the key of the first field will be placed
	value	a string where the value of the first field will be placed (can be an empty string).

Returns:: true if there is a first field.

void Falcon::URI::fragment ( const String & s )

Sets the fragment part.

const String& Falcon::URI::fragment ( ) const [inline]

Returns the fragment part.

const String& Falcon::URI::get ( bool synthQuery = true ) const

Returns the current URI.

This method eventually builds a new URI from the internally parsed data and returns it.

If a set of key-value pairs has been set in this URI, it is used to synthetize a query field using makeQuery() method. If this is not desired, i.e. because already done, or because the query field has been set separately, the synthQuery parameter may be set to false, and the content of the query field will be used instead.

bool Falcon::URI::getField	(	const String &	key,
		String &	value
	)			const

Returns the required value, if it exists.

bool Falcon::URI::hasField ( const String & f ) const

Returns true if the query part has this field.

static unsigned char Falcon::URI::HexToChar ( unsigned char ch ) [inline, static]

void Falcon::URI::host ( const String & h )

Sets a different host for this URI.

This will invalidate current URI until next uri() is called.

const String& Falcon::URI::host ( ) const [inline]

Returns current host.

bool Falcon::URI::isGenDelim ( uint32 chr ) [inline, static]

Character is a general delimiter under RFC3986.

Referenced by isResDelim().

bool Falcon::URI::isMainDelim ( uint32 chr ) [inline, static]

Character is main section delimiter under RFC3986.

bool Falcon::URI::isResDelim ( uint32 chr ) [inline, static]

Character is a reserved delimiter under RFC3986.

References isGenDelim(), and isSubDelim().

bool Falcon::URI::isSubDelim ( uint32 chr ) [inline, static]

Character is a subdelimiter under RFC4986.

Referenced by isResDelim().

bool Falcon::URI::isValid ( ) const [inline]

Returns true if the URI is valid.

const String& Falcon::URI::makeQuery ( ) const

Synthetizes a query field out of the key-values stored in this URI object.

This call clears the content of the query field and changes it with an RFC3986 encoded key-value pair list in the format

         k1=v1&k2=v2&...&kn=vn

Returns:: The synthetized string.

bool Falcon::URI::nextField	(	String &	key,
		String &	value
	)

Enumerates the query fields - gets the next field.

Returns true if there is a next field.

Note:: The query element must have been previously parsed, or fields must have been explicitly inserted.

Parameters:

	key	a string where the key of the first field will be placed
	value	a string where the value of the first field will be placed (can be an empty string).

bool Falcon::URI::parse	(	const String &	newUri,
		bool	parseQuery = `false`,
		bool	decode = `true`
	)

Parses the given string into this URI.

The URI will be normalized and eventually decoded, so that the internal format of the URI.

Normally, the method decodes any % code into it's value, and considers the uri as encoded into UTF-8 sequences.

If the decode param is false, the input string is read as-is.

By default, the function will just store the query field for later retrival with the query() accessor. The query field will be returned in its original form, undecoded. If the makeQueryMap boolean field is set to true, the parseQuery() method will be called upon succesful completion of URI parsing, before the function returns.

Parameters:

	newUri	the new URI to be parsed.
	decode	set to false to use the given URI as is.
	bMakeQueryMap	if true, will create a string map with pre-parsed from query field, if present.

Returns:: true on success, false if the given string is not a valid URI.

bool Falcon::URI::parseQuery	(	const String &	q,
		bool	decode = `true`
	)			`[inline]`

Changes query and the parses it field.

This method calls in sequecnce the query() accessor and then the parseQuery() method.

Parameters:

	q	a string that will be set as-is in the query field of this URI
	decode	true to automatically URL decode keys and values that will be stored in the map.

Returns:: true on success, false if the query field cannot be decoded.

bool Falcon::URI::parseQuery ( bool decode = true )

Parses the query field.

Taken the query field of this class, it perform a RFC3986 scan for "&" separated keys and values pairs, each of which separated with a "=" sign.

The result is set in the internal map of fields, that can then be inspected or changed keywise.

This method overwrites existing keys with new ones, so it is not possible to use it to implement PHP-like URI arrays as in i.e.

         k[]=1&k[]=2

Parameters:

decode

true to automatically URL decode keys and values that will be stored in the map.

Returns:: true on success, false if the query field cannot be decoded.

void Falcon::URI::path ( const Path & p )

Sets a different path for this URI.

This will invalidate current URI until next uri() is called.

void Falcon::URI::path ( const String & p )

Sets a different path for this URI.

This will invalidate current URI until next uri() is called.

const String& Falcon::URI::path ( ) const [inline]

Returns current path.

Path& Falcon::URI::pathElement ( ) [inline]

Returns current path as a path class.

const Path& Falcon::URI::pathElement ( ) const [inline]

Returns current path as a path class.

void Falcon::URI::port ( const String & h )

Sets a different port for this URI.

This will invalidate current URI until next uri() is called.

const String& Falcon::URI::port ( ) const [inline]

Returns current port.

const String& Falcon::URI::query ( ) const [inline]

Returns previously set query.

This method returns a previously set query field as-is.

The content of the key-value map of this URI object, if any, is ignored.

Note:: To make a query field out of a query-map, use the makeQuery() method.

void Falcon::URI::query	(	const String &	q,
		bool	encode = `false`
	)

Sets the query field of this URI.

The query field is set as-is. This destroys previously created maps of keys values that should be used as query field generators.

The parameter should be URL encoded before being set into this method, or the encode parameter may be used to have this method to perform URL encoding.

Parameters:

	q	the query to be set.
	encode	if true, q is considered a plain string still to be encoded.

bool Falcon::URI::removeField ( const String & key )

Removes a query field.

void Falcon::URI::scheme ( const String & s )

Sets a different scheme for this URI.

This will invalidate current URI until next uri() is called.

const String& Falcon::URI::scheme ( ) const [inline]

Normalzies the URI sequence.

Transforms ranges of ALPHA (41-5A and 61-7A), DIGIT (30-39), hyphen (2D), period (2E), underscore (5F), or tilde (7E) into their coresponding values.

Other than that, it transforms 20 in spaces.

The normalization is performed on a result string.

Every string set in input by any method in this class is normalized prior to storage.

However, notice that parts in the class may be invalid URI elements if extracted as is, as they are stored as Falcon international strings. Encoding to URI conformance happens only when required.

Parameters:

	part	the element of the URI (or the complete URI) to be normalized.
	result	the string where the normalization is performed. Returns current scheme.

void Falcon::URI::setField	(	const String &	key,
		const String &	value
	)

Sets a given query field.

As a convention, if the string contains only a single 0 character (NUL), the final result won't include = in the query part, while an empty string will result in a query string containing only a keu and a "=" followed by nothing. Strings longer than 1 element are not interpreted this way, so a nul followed by some data would be rendere as "%00" followed by the rest of the value.

static String Falcon::URI::URLDecode ( const String & source ) [inline, static]

static bool Falcon::URI::URLDecode	(	const String &	source,
		String &	target
	)			`[static]`

Decode an URI-URL encoded string.

Parameters:

	source	the string to be decoded.
	target	the target where to store the decoded string.

Returns:: true if the decoding was succesful, false otherwise.

static String Falcon::URI::URLEncode ( const String & source ) [inline, static]

static void Falcon::URI::URLEncode	(	const String &	source,
		String &	target
	)			`[static]`

void Falcon::URI::userInfo ( const String & s )

Sets a different userInfo for this URI.

This will invalidate current URI until next uri() is called.

const String& Falcon::URI::userInfo ( ) const [inline]

Returns current userInfo.

Friends And Related Function Documentation

friend class Path [friend]

The documentation for this class was generated from the following file:

/home/gian/Progetti/falcon/core/include/falcon/uri.h


Public Member Functions
void	clear ()
	Clears the content of this URI.
uint32	fieldCount ()
	Enumerates the query fields - counts the fields.
bool	firstField (String &key, String &value)
	Enumerates the query fields - gets the first field.
void	fragment (const String &s)
	Sets the fragment part.
const String &	fragment () const
	Returns the fragment part.
const String &	get (bool synthQuery=true) const
	Returns the current URI.
bool	getField (const String &key, String &value) const
	Returns the required value, if it exists.
bool	hasField (const String &f) const
	Returns true if the query part has this field.
void	host (const String &h)
	Sets a different host for this URI.
const String &	host () const
	Returns current host.
bool	isValid () const
	Returns true if the URI is valid.
const String &	makeQuery () const
	Synthetizes a query field out of the key-values stored in this URI object.
bool	nextField (String &key, String &value)
	Enumerates the query fields - gets the next field.
bool	parse (const String &newUri, bool parseQuery=false, bool decode=true)
	Parses the given string into this URI.
bool	parseQuery (const String &q, bool decode=true)
	Changes query and the parses it field.
bool	parseQuery (bool decode=true)
	Parses the query field.
void	path (const Path &p)
	Sets a different path for this URI.
void	path (const String &p)
	Sets a different path for this URI.
const String &	path () const
	Returns current path.
Path &	pathElement ()
	Returns current path as a path class.
const Path &	pathElement () const
	Returns current path as a path class.
void	port (const String &h)
	Sets a different port for this URI.
const String &	port () const
	Returns current port.
const String &	query () const
	Returns previously set query.
void	query (const String &q, bool encode=false)
	Sets the query field of this URI.
bool	removeField (const String &key)
	Removes a query field.
void	scheme (const String &s)
	Sets a different scheme for this URI.
const String &	scheme () const
	Normalzies the URI sequence.
void	setField (const String &key, const String &value)
	Sets a given query field.
	URI (const URI &other)
	Copy constructor.
	URI (const String &suri)
	Complete URI constructor.
	URI ()
	Empty constructor.
void	userInfo (const String &s)
	Sets a different userInfo for this URI.
const String &	userInfo () const
	Returns current userInfo.
virtual	~URI ()
Static Public Member Functions
static unsigned char	CharToHex (unsigned char ch)
static unsigned char	HexToChar (unsigned char ch)
static bool	isGenDelim (uint32 chr)
	Character is a general delimiter under RFC3986.
static bool	isMainDelim (uint32 chr)
	Character is main section delimiter under RFC3986.
static bool	isResDelim (uint32 chr)
	Character is a reserved delimiter under RFC3986.
static bool	isSubDelim (uint32 chr)
	Character is a subdelimiter under RFC4986.
static String	URLDecode (const String &source)
static bool	URLDecode (const String &source, String &target)
	Decode an URI-URL encoded string.
static String	URLEncode (const String &source)
static void	URLEncode (const String &source, String &target)
Friends
class	Path