The QUrl class provides a convenient interface for working with URLs. More...

Inheritance diagram for QtCore.QUrl:

Collaboration diagram for QtCore.QUrl:

Public Types
enum	FormattingOption { None = 0, RemoveAuthority = 30, RemoveFragment = 128, RemovePassword = 2, RemovePath = 32, RemovePort = 8, RemoveQuery = 64, RemoveScheme = 1, RemoveUserInfo = 6, StripTrailingSlash = 65536 }
	More...

enum	ParsingMode { StrictMode = 1, TolerantMode = 0 }
	More...

Public Member Functions
override bool	Equals (object o)

override int	GetHashCode ()

	QUrl ()


	QUrl (QUrl copy)


	QUrl (string url)


	QUrl (string url, QUrl.ParsingMode mode)


virtual void	CreateProxy ()

new void	AddEncodedQueryItem (QByteArray key, QByteArray value)


new void	AddQueryItem (string key, string value)


new System.Collections.Generic.List < QByteArray >	AllEncodedQueryItemValues (QByteArray key)


new System.Collections.Generic.List < string >	AllQueryItemValues (string key)


new void	Clear ()


new void	Detach ()

new QByteArray	EncodedQueryItemValue (QByteArray key)


new string	ErrorString ()


new bool	HasEncodedQueryItem (QByteArray key)


new bool	HasFragment ()


new bool	HasQuery ()


new bool	HasQueryItem (string key)


new bool	IsDetached ()

new bool	IsEmpty ()


new bool	IsLocalFile ()


new bool	IsParentOf (QUrl url)


new bool	IsRelative ()


new bool	IsValid ()


new int	Port ()


new int	Port (int defaultPort)


new string	QueryItemValue (string key)


new sbyte	QueryPairDelimiter ()


new sbyte	QueryValueDelimiter ()


new void	RemoveAllEncodedQueryItems (QByteArray key)


new void	RemoveAllQueryItems (string key)


new void	RemoveEncodedQueryItem (QByteArray key)


new void	RemoveQueryItem (string key)


new QUrl	Resolved (QUrl relative)


new void	SetEncodedUrl (QByteArray url)


new void	SetEncodedUrl (QByteArray url, QUrl.ParsingMode mode)


new void	SetPort (int port)


new void	SetQueryDelimiters (sbyte valueDelimiter, sbyte pairDelimiter)


new void	SetUrl (string url)


new void	SetUrl (string url, QUrl.ParsingMode mode)


new void	Swap (QUrl other)


new QByteArray	ToEncoded (QUrl.FormattingOption options=QUrl.FormattingOption.None)


new string	ToLocalFile ()


override string	ToString ()


new string	ToString (QUrl.FormattingOption options=QUrl.FormattingOption.None)


new string	TopLevelDomain ()


new void	Dispose ()

Static Public Member Functions
static string	FromAce (QByteArray arg1)


static QUrl	FromEncoded (QByteArray url)


static QUrl	FromEncoded (QByteArray url, QUrl.ParsingMode mode)


static QUrl	FromLocalFile (string localfile)


static string	FromPercentEncoding (QByteArray arg1)


static string	FromPunycode (QByteArray arg1)


static QUrl	FromUserInput (string userInput)


static bool	operator!= (QUrl arg1, QUrl arg2)


static bool	operator< (QUrl arg1, QUrl arg2)

static bool	operator== (QUrl arg1, QUrl arg2)


static QByteArray	ToAce (string arg1)


static QByteArray	ToPercentEncoding (string arg1)


static QByteArray	ToPercentEncoding (string arg1, QByteArray exclude)


static QByteArray	ToPercentEncoding (string arg1, QByteArray exclude, QByteArray include)


static QByteArray	ToPunycode (string arg1)


static bool	operator> (QUrl arg1, QUrl arg2)

Protected Member Functions
	QUrl (System.Type dummy)

Protected Attributes
SmokeInvocation	interceptor

Properties
new string	Authority `[get, set]`


new QByteArray	EncodedFragment `[get, set]`


new QByteArray	EncodedHost `[get, set]`


new QByteArray	EncodedPassword `[get, set]`


new QByteArray	EncodedPath `[get, set]`


new QByteArray	EncodedQuery `[get, set]`


new QByteArray	EncodedUserName `[get, set]`


new string	Fragment `[get, set]`


new string	Host `[get, set]`


static System.Collections.Generic.List < string >	IdnWhitelist `[get, set]`


new string	Password `[get, set]`


new string	Path `[get, set]`


new string	Scheme `[get, set]`


new string	UserInfo `[get, set]`


new string	UserName `[get, set]`


virtual System.IntPtr	SmokeObject `[get, set]`

Detailed Description

The QUrl class provides a convenient interface for working with URLs.

It can parse and construct URLs in both encoded and unencoded form. QUrl also has support for internationalized domain names (IDNs).

The most common way to use QUrl is to initialize it via the constructor by passing a QString. Otherwise, setUrl() and setEncodedUrl() can also be used.

URLs can be represented in two forms: encoded or unencoded. The unencoded representation is suitable for showing to users, but the encoded representation is typically what you would send to a web server. For example, the unencoded URL "http://bühler.example.com/List of applicants.xml" would be sent to the server as "http://xn–bhler-kva.example.com/List%20of%20applicants.xml", and this can be verified by calling the toEncoded() function.

A URL can also be constructed piece by piece by calling setScheme(), setUserName(), setPassword(), setHost(), setPort(), setPath(), setEncodedQuery() and setFragment(). Some convenience functions are also available: setAuthority() sets the user name, password, host and port. setUserInfo() sets the user name and password at once.

Call isValid() to check if the URL is valid. This can be done at any point during the constructing of a URL.

Constructing a query is particularly convenient through the use of setQueryItems(), addQueryItem() and removeQueryItem(). Use setQueryDelimiters() to customize the delimiters used for generating the query string.

For the convenience of generating encoded URL strings or query strings, there are two static functions called fromPercentEncoding() and toPercentEncoding() which deal with percent encoding and decoding of QStrings.

Calling isRelative() will tell whether or not the URL is relative. A relative URL can be resolved by passing it as argument to resolved(), which returns an absolute URL. isParentOf() is used for determining whether one URL is a parent of another.

fromLocalFile() constructs a QUrl by parsing a local file path. toLocalFile() converts a URL to a local file path.

The human readable representation of the URL is fetched with toString(). This representation is appropriate for displaying a URL to a user in unencoded form. The encoded form however, as returned by toEncoded(), is for internal use, passing to web servers, mail clients and so on.

QUrl conforms to the URI specification from RFC 3986 (Uniform Resource Identifier: Generic Syntax), and includes scheme extensions from RFC 1738 (Uniform Resource Locators). Case folding rules in QUrl conform to RFC 3491 (Nameprep: A Stringprep Profile for Internationalized Domain Names (IDN)).

Character Conversions

Follow these rules to avoid erroneous character conversion when dealing with URLs and strings:

When creating an QString to contain a URL from a QByteArray or a char*, always use QString::fromUtf8().

Favor the use of QUrl::fromEncoded() and QUrl::toEncoded() instead of QUrl(string) and QUrl::toString() when converting a QUrl to or from a string.

Member Enumeration Documentation

enum QtCore.QUrl.FormattingOption

The formatting options define how the URL is formatted when written out as text.

Note that the case folding rules in Nameprep, which QUrl conforms to, require host names to always be converted to lower case, regardless of the Qt::FormattingOptions used.

Enumerator:

None	The format of the URL is unchanged.
RemoveAuthority
RemoveFragment
RemovePassword	Any password in the URL is removed.
RemovePath	The URL's path is removed, leaving only the scheme, host address, and port (if present).
RemovePort	Any specified port is removed from the URL.
RemoveQuery	The query part of the URL (following a '?' character) is removed.
RemoveScheme	The scheme is removed from the URL.
RemoveUserInfo	Any user information in the URL is removed.
StripTrailingSlash	The trailing slash is removed if one is present.

enum QtCore.QUrl.ParsingMode

The parsing mode controls the way QUrl parses strings.

In TolerantMode, the parser corrects the following invalid input:

Spaces and "%20": If an encoded URL contains a space, this will be replaced with "%20". If a decoded URL contains "%20", this will be replaced with a single space before the URL is parsed.

Single "%" characters: Any occurrences of a percent character "%" not followed by exactly two hexadecimal characters (e.g., "13% coverage.html") will be replaced by "%25".

Reserved and unreserved characters: An encoded URL should only contain a few characters as literals; all other characters should be percent-encoded. In TolerantMode, these characters will be automatically percent-encoded where they are not allowed: space / double-quote / "<" / ">" / "[" / "" / "]" / "^" / "`" / "{" / "|" / "}"

Enumerator:

StrictMode	Only valid URLs are accepted. This mode is useful for general URL validation.
TolerantMode	QUrl will try to correct some common errors in URLs. This mode is useful when processing URLs entered by users.

Constructor & Destructor Documentation

QtCore.QUrl.QUrl ( System.Type dummy )

protected

QtCore.QUrl.QUrl ( )

Constructs an empty QUrl object.

QtCore.QUrl.QUrl ( QUrl copy )

Constructs a copy of other.

QtCore.QUrl.QUrl ( string url )

Constructs a URL by parsing url. url is assumed to be in human readable representation, with no percent encoding. QUrl will automatically percent encode all characters that are not allowed in a URL. The default parsing mode is TolerantMode.

Example:

QUrl url("http://www.example.com/List of holidays.xml");

// url.toEncoded() == "http://www.example.com/List%20of%20holidays.xml"

To construct a URL from an encoded string, call fromEncoded():

QUrl url = QUrl::fromEncoded("http://qt.nokia.com/List%20of%20holidays.xml");

See also setUrl(), setEncodedUrl(), fromEncoded(), and TolerantMode.

QtCore.QUrl.QUrl	(	string	url,
		QUrl.ParsingMode	mode
	)

This is an overloaded function.

Parses the url using the parser mode parsingMode. The default parsing mode is TolerantMode.

Member Function Documentation

new void QtCore.QUrl.AddEncodedQueryItem	(	QByteArray	key,
		QByteArray	value
	)

Inserts the pair key = value into the query string of the URL.

Note: this function does not verify that either key or value are properly encoded. It is the caller's responsibility to ensure that the query delimiters are properly encoded, if any.

This function was introduced in Qt 4.4.

See also addQueryItem() and setQueryDelimiters().

new void QtCore.QUrl.AddQueryItem	(	string	key,
		string	value
	)

Inserts the pair key = value into the query string of the URL.

The key/value pair is encoded before it is added to the query. The pair is converted into separate strings internally. The key and value is first encoded into UTF-8 and then delimited by the character returned by valueDelimiter(). Each key/value pair is delimited by the character returned by pairDelimiter().

Note: This method does not encode spaces (ASCII 0x20) as plus (+) signs, like HTML forms do. If you need that kind of encoding, you must encode the value yourself and use QUrl::addEncodedQueryItem.

Member Data Documentation

SmokeInvocation QtCore.QUrl.interceptor

protected

Property Documentation

new string QtCore.QUrl.Authority

getset

Returns the authority of the URL if it is defined; otherwise an empty string is returned.

Sets the authority of the URL to authority.

The authority of a URL is the combination of user info, a host name and a port. All of these elements are optional; an empty authority is therefore valid.

The user info and host are separated by a '@', and the host and port are separated by a ':'. If the user info is empty, the '@' must be omitted; although a stray ':' is permitted if the port is empty.

The following example shows a valid authority string:

new QByteArray QtCore.QUrl.EncodedFragment

getset

Returns the fragment of the URL if it is defined; otherwise an empty string is returned. The returned value will have its non-ASCII and other control characters percent-encoded, as in toEncoded().

This function was introduced in Qt 4.4.

Sets the URL's fragment to the percent-encoded fragment. The fragment is the last part of the URL, represented by a '#' followed by a string of characters. It is typically used in HTTP for referring to a certain link or point on a page:

The fragment is sometimes also referred to as the URL "reference".

Passing an argument of QByteArray() (a null QByteArray) will unset the fragment. Passing an argument of QByteArray("") (an empty but not null QByteArray) will set the fragment to an empty string (as if the original URL had a lone "#").

This function was introduced in Qt 4.4.

new QByteArray QtCore.QUrl.EncodedHost

getset

Returns the host part of the URL if it is defined; otherwise an empty string is returned.

Note: encodedHost() does not return percent-encoded hostnames. Instead, the ACE-encoded (bare ASCII in Punycode encoding) form will be returned for any non-ASCII hostname.

This function is equivalent to calling QUrl::toAce() on the return value of host().

This function was introduced in Qt 4.4.

Sets the URL's host to the ACE- or percent-encoded host. The host is part of the user info element in the authority of the URL, as described in setAuthority().

This function was introduced in Qt 4.4.

new QByteArray QtCore.QUrl.EncodedPassword

getset

Returns the password of the URL if it is defined; otherwise an empty string is returned. The returned value will have its non-ASCII and other control characters percent-encoded, as in toEncoded().

This function was introduced in Qt 4.4.

Sets the URL's password to the percent-encoded password. The password is part of the user info element in the authority of the URL, as described in setUserInfo().

Note: this function does not verify that password is properly encoded. It is the caller's responsibility to ensure that the any delimiters (such as colons or slashes) are properly encoded.

This function was introduced in Qt 4.4.

new QByteArray QtCore.QUrl.EncodedPath

getset

Returns the path of the URL if it is defined; otherwise an empty string is returned. The returned value will have its non-ASCII and other control characters percent-encoded, as in toEncoded().

This function was introduced in Qt 4.4.

Sets the URL's path to the percent-encoded path. The path is the part of the URL that comes after the authority but before the query string.

For non-hierarchical schemes, the path will be everything following the scheme declaration, as in the following example:

Note: this function does not verify that path is properly encoded. It is the caller's responsibility to ensure that the any delimiters (such as '?' and '#') are properly encoded.

This function was introduced in Qt 4.4.

new QByteArray QtCore.QUrl.EncodedQuery

getset

Returns the query string of the URL in percent encoded form.

Sets the query string of the URL to query. The string is inserted as-is, and no further encoding is performed when calling toEncoded().

This function is useful if you need to pass a query string that does not fit into the key-value pattern, or that uses a different scheme for encoding special characters than what is suggested by QUrl.

Passing a value of QByteArray() to query (a null QByteArray) unsets the query completely. However, passing a value of QByteArray("") will set the query to an empty value, as if the original URL had a lone "?".

new QByteArray QtCore.QUrl.EncodedUserName

getset

Returns the user name of the URL if it is defined; otherwise an empty string is returned. The returned value will have its non-ASCII and other control characters percent-encoded, as in toEncoded().

This function was introduced in Qt 4.4.

Sets the URL's user name to the percent-encoded userName. The userName is part of the user info element in the authority of the URL, as described in setUserInfo().

Note: this function does not verify that userName is properly encoded. It is the caller's responsibility to ensure that the any delimiters (such as colons or slashes) are properly encoded.

This function was introduced in Qt 4.4.

new string QtCore.QUrl.Fragment

getset

Returns the fragment of the URL.

Sets the fragment of the URL to fragment. The fragment is the last part of the URL, represented by a '#' followed by a string of characters. It is typically used in HTTP for referring to a certain link or point on a page:

The fragment is sometimes also referred to as the URL "reference".

Passing an argument of QString() (a null QString) will unset the fragment. Passing an argument of QString("") (an empty but not null QString) will set the fragment to an empty string (as if the original URL had a lone "#").

new string QtCore.QUrl.Host

getset

Returns the host of the URL if it is defined; otherwise an empty string is returned.

Sets the host of the URL to host. The host is part of the authority.

System.Collections.Generic.List<string> QtCore.QUrl.IdnWhitelist

staticgetset

Returns the current whitelist of top-level domains that are allowed to have non-ASCII characters in their compositions.

See setIdnWhitelist() for the rationale of this list.

This function was introduced in Qt 4.2.

Sets the whitelist of Top-Level Domains (TLDs) that are allowed to have non-ASCII characters in domains to the value of list.

Note that if you call this function, you need to do so \em before you start any threads that might access idnWhitelist().

Qt has comes a default list that contains the Internet top-level domains that have published support for Internationalized Domain Names (IDNs) and rules to guarantee that no deception can happen between similarly-looking characters (such as the Latin lowercase letter 'a' and the Cyrillic equivalent, which in most fonts are visually identical).

This list is periodically maintained, as registrars publish new rules.

This function is provided for those who need to manipulate the list, in order to add or remove a TLD. It is not recommended to change its value for purposes other than testing, as it may expose users to security risks.

This function was introduced in Qt 4.2.

new string QtCore.QUrl.Password

getset

Returns the password of the URL if it is defined; otherwise an empty string is returned.

Sets the URL's password to password. The password is part of the user info element in the authority of the URL, as described in setUserInfo().

new string QtCore.QUrl.Path

getset

Returns the path of the URL.

Sets the path of the URL to path. The path is the part of the URL that comes after the authority but before the query string.

For non-hierarchical schemes, the path will be everything following the scheme declaration, as in the following example:

new string QtCore.QUrl.Scheme

getset

Returns the scheme of the URL. If an empty string is returned, this means the scheme is undefined and the URL is then relative.

Sets the scheme of the URL to scheme. As a scheme can only contain ASCII characters, no conversion or encoding is done on the input.

The scheme describes the type (or protocol) of the URL. It's represented by one or more ASCII characters at the start the URL, and is followed by a ':'. The following example shows a URL where the scheme is "ftp":

The scheme can also be empty, in which case the URL is interpreted as relative.

virtual System.IntPtr QtCore.QUrl.SmokeObject

getset

new string QtCore.QUrl.UserInfo

getset

Returns the user info of the URL, or an empty string if the user info is undefined.

Sets the user info of the URL to userInfo. The user info is an optional part of the authority of the URL, as described in setAuthority().

The user info consists of a user name and optionally a password, separated by a ':'. If the password is empty, the colon must be omitted. The following example shows a valid user info string:

new string QtCore.QUrl.UserName

getset

Returns the user name of the URL if it is defined; otherwise an empty string is returned.

Sets the URL's user name to userName. The userName is part of the user info element in the authority of the URL, as described in setUserInfo().

new void QtCore.QUrl.SetQueryDelimiters	(	sbyte	valueDelimiter,
		sbyte	pairDelimiter
	)

new void QtCore.QUrl.SetEncodedUrl	(	QByteArray	url,
		QUrl.ParsingMode	mode
	)

new void QtCore.QUrl.SetUrl	(	string	url,
		QUrl.ParsingMode	mode
	)

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Properties

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

Property Documentation