Utils::Uri

Utils::Uri Class Reference

#include <Uri.h> [code]

List of all members.

Detailed Description

Implements a URI as per RFC 3986.

Represents URIs as defined in http://www.rfc-editor.org/rfc/rfc3986.txt.

Uri supports both hierarchical and non-hierarchical URIs. The following fileds are provided (example from RFC 3986):

         foo://example.com:8042/over/there?name=ferret#nose
         \_/   \______________/\_________/ \_________/ \__/
          |           |            |            |        |
       scheme     authority       path        query   fragment
          |   _____________________|__
         / \ /                        \
         urn:example:animal:ferret:nose

The field authority is additionally subdivided into userInfo, host and port.

Relative URIs (scheme, authority, path possibly omitted) are also supported.

Todo:
Host must be in UTF-8 encodig for consistency?? Refer to RFC 3986: 
	Registry-based naming authorities that use the generic syntax are now
	defined within the host rule.  This change allows current
	implementations, where whatever name provided is simply fed to the
	local name resolution mechanism, to be consistent with the
	specification.  It also removes the need to re-specify DNS name
	formats here.  Furthermore, it allows the host component to contain
	percent-encoded octets, which is necessary to enable
	internationalized domain names to be provided in URIs, processed in
	their native character encodings at the application layers above URI
	processing, and passed to an IDNA library as a registered name in the
	UTF-8 character encoding.  The server, hostport, hostname,
	domainlabel, toplabel, and alphanum rules have been removed.
Also: 
	For most systems, an unreserved character appearing within a URI
	component is interpreted as representing the data octet corresponding
	to that character's encoding in US-ASCII.  Consumers of URIs assume
	that the letter "X" corresponds to the octet "01011000", and even
	when that assumption is incorrect, there is no harm in making it.  A
	system that internally provides identifiers in the form of a
	different character encoding, such as EBCDIC, will generally perform
	character translation of textual identifiers to UTF-8 [STD63] (or
	some other superset of the US-ASCII character encoding) at an
	internal interface, thereby providing more meaningful identifiers
	than those resulting from simply percent-encoding the original
	octets.
...which fields are textual? Doesn't it depend on the scheme?

Definition at line 82 of file Uri.h.

Public Types

typedef QPair< QByteArray,
QByteArray > 		QueryItem
typedef QList< QueryItem > QueryItemList
enum  Field {
  Scheme = 0x01,
  UserInfo = 0x02,
  Host = 0x04,
  Port = 0x08,
  Authority = UserInfo | Host | Port,
  Path = 0x10,
  Query = 0x20,
  Fragment = 0x40,
  AllFields = Scheme | Authority | Path | Query | Fragment
}

Public Member Functions

 Uri (const Uri &)
 Copy constructor.
Uri & operator= (const Uri &)
 Assignment operator.
bool operator== (const Uri &) const
 Equality comparison.
bool operator!= (const Uri &) const
 Inequality comparison.
 Q_DECLARE_FLAGS (Fields, Field)
 Uri ()
 Constructs a Null Uri object.
QByteArray scheme () const
 Returns the scheme component of the URI.
QByteArray userInfo () const
 Returns the userInfo component of the URI.
QByteArray host () const
 Returns the host component of the URI.
QByteArray port () const
 Returns the port component of the URI.
QByteArray authority () const
 Returns the authority component of the URI.
QByteArray path () const
 Returns the path component of the URI.
QByteArray query () const
 Returns the query component of the URI.
QByteArray queryItemValue (const QByteArray &key) const
 Returns the value associated with the key from the query part.
QueryItemList queryItems () const
 Returns the query component split in query items.
QByteArray fragment () const
 Returns the fragment component of the URI.
QByteArray unencoded (Fields fields=AllFields) const
 Returns the unencoded URI representation of this Uri object.
QByteArray encoded (Fields fields=AllFields) const
 Produces an URI representation of this URI object in encoded form.
void setScheme (const QByteArray &)
 Sets the scheme component of the URI.
void setAuthority (const QByteArray &)
 Sets the authority part of the URI.
void setAuthority (const QByteArray &userInfo, const QByteArray &host, const QByteArray &port)
 Sets the individual fields of the authority component.
void setPath (const QByteArray &)
 Sets the path component of the URI.
void setQuery (const QByteArray &)
 Sets the query component of the URI.
void appendQuery (const QByteArray &bytes)
 Appends bytes to the query URI component.
void appendQueryItem (const QByteArray &key, const QByteArray &value)
 Appends a query item (key, value pair) to the query URI component.
void appendQueryItem (const QueryItem &item)
void appendQueryItems (const QueryItemList &itemList)
 Appends a list of query items (key, value pairs) to the query URI component.
void setFragment (const QByteArray &)
 Sets the fragment component of the URI.

Static Public Member Functions

static Uri fromUnencoded (const QByteArray &)
 Named ctor for creating an Uri object from unencoded raw bytes.
static Uri fromEncoded (const QByteArray &)
 Named ctor for creating an Uri object from encoded raw bytes.

Private Member Functions

QByteArray toQByteArray (Fields fields, bool encode) const
 Builds the Uri object representation in raw bytes.
bool parse (const QByteArray &bytes, bool decode)
bool parseAuthority (const QByteArray &authority, bool decode)
 Helper to split the authority component into userInfo, host, port.

Static Private Member Functions

static QByteArray doEncode (const QByteArray &bytes, bool encode, const QByteArray &charsToExclude)
 Helper to percent encode a given string if necessary.
static bool shouldEncode (char ch, const QByteArray &charsToExclude)
 Helper that checks whether a character should be percent encoded or not.
static char hex (char)
 Helper that returns the hexadecimal digit for a given value.
static QByteArray quoted (char)
 Helper that returns the percent encoded version of a character.
static bool doDecode (QByteArray &bytes, bool decode)
 Helper to actually percent decode a string if required.
static bool fromHex (char &)
 Helper that converts a hex character to its integral value.
static char unquoted (char hex1, char hex2)
 Helper that produces the unquoted version of two hex values.
static void ensureNotNull (QByteArray &bytes)
 Helper that makes sure bytes.isNull() will return false.

Private Attributes

QSharedDataPointer< PrivateData > d
 Private data with implicit sharing.

Static Private Attributes

static const QByteArray UserInfoEncodeExcludeChars
static const QByteArray HostEncodeExcludeChars
static const QByteArray PathEncodeExcludeChars
static const QByteArray QueryEncodeExcludeChars
static const QByteArray QueryItemEncodeExcludeChars
static const QByteArray FragmentEncodeExcludeChars

Classes

struct  PrivateData
 Stores Uri's private implicitly shared data. More...

Member Typedef Documentation

typedef QPair<QByteArray, QByteArray> Utils::Uri::QueryItem
 

Definition at line 88 of file Uri.h.

typedef QList<QueryItem> Utils::Uri::QueryItemList
 

Definition at line 89 of file Uri.h.

Member Enumeration Documentation

enum Utils::Uri::Field
 

Enumerator:
Scheme 
UserInfo 
Host 
Port 
Authority 
Path 
Query 
Fragment 
AllFields 

Definition at line 91 of file Uri.h.

Constructor & Destructor Documentation

Uri::Uri (  const Uri &  other  ) 
 

Copy constructor.

Parameters:
other Object that will be used as a model in the object creation.
Constructs a copy of the other object.

Definition at line 39 of file Uri.cpp.

Uri::Uri (   ) 
 

Constructs a Null Uri object.

Definition at line 28 of file Uri.cpp.

Member Function Documentation

void Uri::appendQuery (  const QByteArray &  bytes  ) 
 

Appends bytes to the query URI component.

Parameters:
bytes are the bytes to append to the URI component. These bytes are appended as they are without any encodings or decodings taking place.

Definition at line 547 of file Uri.cpp.

void Uri::appendQueryItem (  const QueryItem &  item  ) 
 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 579 of file Uri.cpp.

void Uri::appendQueryItem (  const QByteArray &  key,
const QByteArray &  value
) 
 

Appends a query item (key, value pair) to the query URI component.

Parameters:
key is the pair key.
value is the pair value.
The function appends the query URI component with the result of combining key and value. If both are not not empty, a string of the form "key=value" will be appended. If value is empty, a string of the form "key" will be appended.

If the query component is not empty when this function is called, then the character '&' will be appended before appending key and value.

Definition at line 565 of file Uri.cpp.

void Uri::appendQueryItems (  const QueryItemList &  itemList  ) 
 

Appends a list of query items (key, value pairs) to the query URI component.

Parameters:
itemList is the list of items that should be appended to the query component.

Definition at line 589 of file Uri.cpp.

QByteArray Uri::authority (   )  const
 

Returns the authority component of the URI.

The authority component is built from the userInfo, host and port URI components:

authority = [userInfo "@"] host [":" port]

Definition at line 62 of file Uri.cpp.

bool Uri::doDecode (  QByteArray &  bytes,
bool  decode
)  [static, private]
 

Helper to actually percent decode a string if required.

Parameters:
[in,out] bytes is the string to encode.
decode is a flag indicating whether percent decoding should actual take place or not.
Returns:
true if decoding succeeds.

false if decoding fails. That would happen if an '' appears that is not followed by two hex digits.

If decode is false, then bytes will not be modified if it is not Null (isNull() returns false) and will set bytes to QByteArray ("") if bytes is Null (isNull() returns true).

If decode is true, then bytes is modified to contain the decoded version of bytes.

Note:
If decoding fails (the function returns false), then bytes will remain unmodified.

Definition at line 381 of file Uri.cpp.

QByteArray Uri::doEncode (  const QByteArray &  bytes,
bool  encode,
const QByteArray &  charsToExclude
)  [static, private]
 

Helper to percent encode a given string if necessary.

Parameters:
bytes is the string to percent encode.
encode is a flag indicating whether the encoding should take place or not.
charsToExclude is a string containing all characters that should not be percent encoded even if encode is set to true.
Returns:
A copy of bytes if encode is false.

The encoded version of bytes if encode is true. If a characters is contained in charsToExclude it will not be percent encoded.

Definition at line 185 of file Uri.cpp.

QByteArray Uri::encoded (  Fields  fields = AllFields  )  const
 

Produces an URI representation of this URI object in encoded form.

Parameters:
fields is a combination of Field flags indicating which URI fields to include in the URI representation.
Returns:
a string containing an URI representation of this object. The string will be percent encoded. This encoded representation can be used in communication with other URI conformant systems. If you'd prefer to display the URI to the user, you might prefer better to use unencoded() instead.
Extract from RFC 3986: 
	Under normal circumstances, the only time when octets within a URI
	are percent-encoded is during the process of producing the URI from
	its component parts.  This is when an implementation determines which
	of the reserved characters are to be used as subcomponent delimiters
	and which can be safely used as data.  Once produced, a URI is always
	in its percent-encoded form.
Further: 
	URIs that differ in the replacement of an unreserved character with
	its corresponding percent-encoded US-ASCII octet are equivalent: they
	identify the same resource.  However, URI comparison implementations
	do not always perform normalization prior to comparison (see Section
	6).  For consistency, percent-encoded octets in the ranges of ALPHA
	(%41-%5A and %61-%7A), DIGIT (%30-%39), hyphen (%2D), period (%2E),
	underscore (%5F), or tilde (%7E) should not be created by URI
	producers and, when found in a URI, should be decoded to their
	corresponding unreserved characters by URI normalizers.

Definition at line 299 of file Uri.cpp.

void Uri::ensureNotNull (  QByteArray &  bytes  )  [static, private]
 

Helper that makes sure bytes.isNull() will return false.

Parameters:
bytes to ensure are not Null.
For a QByteArray() object isNull() will return true. For a QByteArray("") object isNull() will return false.

This is used to determine whether an URI component is not set at all or is just empty. isEmpty() is not enough to make this destinction.

Definition at line 536 of file Uri.cpp.

QByteArray Utils::Uri::fragment (   )  const [inline]
 

Returns the fragment component of the URI.

Definition at line 200 of file Uri.h.

Uri Uri::fromEncoded (  const QByteArray &  bytes  )  [static]
 

Named ctor for creating an Uri object from encoded raw bytes.

Parameters:
bytes are raw and encoded.
Returns:
an Uri object that contains an object representation of the URI presented in bytes.

Uri() if bytes cannot correctly be parsed.

Definition at line 640 of file Uri.cpp.

bool Uri::fromHex (  char &  hex  )  [static, private]
 

Helper that converts a hex character to its integral value.

Parameters:
[in,out] hex contains the hex character that should be converted.
Returns:
true if hex could be converted (it was in the range 'a' to 'f' or 'A' to 'F' or '0' to '9').

false otherwise.

If the function returns true, the value of hex will be modified to contain the integral value of the hex character.

Definition at line 418 of file Uri.cpp.

Uri Uri::fromUnencoded (  const QByteArray &  bytes  )  [static]
 

Named ctor for creating an Uri object from unencoded raw bytes.

Parameters:
bytes are raw and unencoded.
Returns:
an Uri object that contains an object representation of the URI presented in bytes.

Uri() if bytes cannot correctly be parsed.

Definition at line 624 of file Uri.cpp.

char Uri::hex (  char  ch  )  [static, private]
 

Helper that returns the hexadecimal digit for a given value.

Parameters:
ch contains an integer value.
Returns:
The hexadecimal digit corresponding to the value of the lower bit quad of ch.

Definition at line 233 of file Uri.cpp.

QByteArray Utils::Uri::host (   )  const [inline]
 

Returns the host component of the URI.

Definition at line 188 of file Uri.h.

bool Uri::operator!= (  const Uri &  other  )  const
 

Inequality comparison.

Parameters:
other is the other object that will be compared with this object.
Returns:
true if this Uri object is not equal to the other object.

false otherwise.

Definition at line 612 of file Uri.cpp.

Uri & Uri::operator= (  const Uri &  other  ) 
 

Assignment operator.

Parameters:
other Object that will be assigned to this object.
Returns:
Reference to this object.

Definition at line 49 of file Uri.cpp.

bool Uri::operator== (  const Uri &  other  )  const
 

Equality comparison.

Parameters:
other is the other object that will be compared with this object.
Returns:
true if this Uri object is equal to the other object.

false otherwise.

Definition at line 601 of file Uri.cpp.

bool Uri::parse (  const QByteArray &  bytes,
bool  decode
)  [private]
 

Helper to parse a raw representation of an URI into this Uri object.

Parameters:
bytes is the string containing the URI.
decode is a flag indicating whether percent decoding should take place or not.
Returns:
A copy of bytes if decode is false.

The decoded version of bytes if decode is true. Percent decoding will be performed, which will replace all "%hh" stirngs ('h' is a hex digit) with a singly byte with integral value equivalent to the coded hex value.

Precondition:
Only call on a Null object - no fields are being cleared.
We use the following regular expression suggested in RFC 3986 to parse the URI: 
    ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?
     12            3  4          5       6  7        8 9

Definition at line 324 of file Uri.cpp.

bool Uri::parseAuthority (  const QByteArray &  authority,
bool  decode
)  [private]
 

Helper to split the authority component into userInfo, host, port.

Parameters:
authority contains the raw bytes of the authority component.
decode is a flag indicated whethe percent decoding should be performed or not.
Returns:
true if the authority component could be parsed successfully.

false otherwise (percent decoding error, or missing host field).

Definition at line 491 of file Uri.cpp.

QByteArray Utils::Uri::path (   )  const [inline]
 

Returns the path component of the URI.

Definition at line 196 of file Uri.h.

QByteArray Utils::Uri::port (   )  const [inline]
 

Returns the port component of the URI.

Definition at line 192 of file Uri.h.

Utils::Uri::Q_DECLARE_FLAGS (  Fields  ,
Field 
) 
 

QByteArray Uri::query (   )  const
 

Returns the query component of the URI.

Definition at line 74 of file Uri.cpp.

Uri::QueryItemList Uri::queryItems (   )  const
 

Returns the query component split in query items.

Returns:
A list of & separated key=value pairs parsed from the query component of the URI.

An empty list if the query component is empty.

Definition at line 109 of file Uri.cpp.

QByteArray Uri::queryItemValue (  const QByteArray &  key  )  const
 

Returns the value associated with the key from the query part.

Parameters:
key is the name used to lookup the value
Returns:
The value associated with the key.

QByteArray() if none is associated.

Note:
If there are more values associated with one key, then the first will be returned (for example: "?key=value1&key=value2").
Todo:
Return concatenation of all associated values instead? I haven't found any note about it in the RFC 3986.

Definition at line 94 of file Uri.cpp.

QByteArray Uri::quoted (  char  ch  )  [static, private]
 

Helper that returns the percent encoded version of a character.

Parameters:
ch is the character.
Returns:
The percent encoded version of ch in a three byte string of the form "%hh" where 'hh' are two hex digits whose decimal value is equivalent to the decimal value of ch.

Definition at line 246 of file Uri.cpp.

QByteArray Utils::Uri::scheme (   )  const [inline]
 

Returns the scheme component of the URI.

Definition at line 180 of file Uri.h.

void Uri::setAuthority (  const QByteArray &  userInfo,
const QByteArray &  host,
const QByteArray &  port
) 
 

Sets the individual fields of the authority component.

Parameters:
userInfo the value of the userInfo field to set (can be Null or empty).
host the value of the host field to set (cannot be neither Null nor empty).
port the value of the port field to set (can be Null or empty).
Precondition:
host must not be empty!

Definition at line 472 of file Uri.cpp.

void Uri::setAuthority (  const QByteArray &  authority  ) 
 

Sets the authority part of the URI.

Parameters:
authority is a string containing the authority URI component. The string is parsed and the individual components userInfo, host and port are extracted:
authority = [userInfo "@"] host [":" port]

Note:
No percent decoding is performed.

Definition at line 453 of file Uri.cpp.

void Utils::Uri::setFragment (  const QByteArray &   )  [inline]
 

Sets the fragment component of the URI.

Definition at line 212 of file Uri.h.

void Utils::Uri::setPath (  const QByteArray &   )  [inline]
 

Sets the path component of the URI.

Definition at line 208 of file Uri.h.

void Uri::setQuery (  const QByteArray &   ) 
 

Sets the query component of the URI.

Definition at line 521 of file Uri.cpp.

void Utils::Uri::setScheme (  const QByteArray &   )  [inline]
 

Sets the scheme component of the URI.

Definition at line 204 of file Uri.h.

bool Uri::shouldEncode (  char  ch,
const QByteArray &  charsToExclude
)  [static, private]
 

Helper that checks whether a character should be percent encoded or not.

Parameters:
ch is the character to check.
charsToExclude are characters that should be excluded from percent encoding.
Returns:
true if ch should be encoded (does not belong to RFC 3986's unreserved characters and is not listed in charsToExclude).

false if ch should not be encoded (does belong to RFC 3986's unreserved characters or is listed in charsToExclude).

Definition at line 212 of file Uri.cpp.

QByteArray Uri::toQByteArray (  Fields  fields,
bool  encode
)  const [private]
 

Builds the Uri object representation in raw bytes.

Parameters:
fields is a combination of Field flags indicating which URI fields to include in the URI representation.
encode determines whether percent encoding should be performed or not.
Returns:
the raw bytes (ASCII) representation of this Uri object. The individual components are combined according to RFC 3986.

Definition at line 138 of file Uri.cpp.

QByteArray Uri::unencoded (  Fields  fields = AllFields  )  const
 

Returns the unencoded URI representation of this Uri object.

Parameters:
fields is a combination of Field flags indicating which URI fields to include in the URI representation.
Returns:
a string containing an URI representation of this object. No characters will percent encoded even if what would have been required by RFC 3086. This unencoded representation is suitable for display to users only. If you want to use the returned string in communication with other URI conformant systems, you'd better use encoded() instead.

Definition at line 262 of file Uri.cpp.

char Uri::unquoted (  char  hex1,
char  hex2
)  [static, private]
 

Helper that produces the unquoted version of two hex values.

Parameters:
hex1 a hex value (0-15).
hex2 a hex value (0-15).
Returns:
A byte being the concatination of the two hex values hex1 being the high-order byte quad and hex2 being the low-order byte quad.

Definition at line 438 of file Uri.cpp.

QByteArray Utils::Uri::userInfo (   )  const [inline]
 

Returns the userInfo component of the URI.

Definition at line 184 of file Uri.h.

Member Data Documentation

QSharedDataPointer<PrivateData> Utils::Uri::d [private]
 

Private data with implicit sharing.

Definition at line 172 of file Uri.h.

const QByteArray Uri::FragmentEncodeExcludeChars [static, private]
 

Definition at line 158 of file Uri.h.

const QByteArray Uri::HostEncodeExcludeChars [static, private]
 

Definition at line 154 of file Uri.h.

const QByteArray Uri::PathEncodeExcludeChars [static, private]
 

Definition at line 155 of file Uri.h.

const QByteArray Uri::QueryEncodeExcludeChars [static, private]
 

Definition at line 156 of file Uri.h.

const QByteArray Uri::QueryItemEncodeExcludeChars [static, private]
 

Definition at line 157 of file Uri.h.

const QByteArray Uri::UserInfoEncodeExcludeChars [static, private]
 

Definition at line 153 of file Uri.h.

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