Contents

• Public Functions
• Static Public Members
• Protected Functions
• Detailed Description

Detailed Description

TheQ3Url class provides a URL parser and simplifies working with URLs.

TheQ3Url class is provided for simple work with URLs. It can parse, decode, encode, etc.

Q3Url works with the decoded path and encoded query in turn.

Example:

<tt>http://example.com:80/cgi-bin/test%20me.pl?cmd=Hello%20you</tt>

Example:

<tt>http://doc.qt.io/qt-4.8/qdockwidget.html#widget</tt>

The individual parts of a URL can be set withsetProtocol(),setHost(),setPort(),setPath(),setFileName(),setRef() andsetQuery(). A URL could contain, for example, an ftp address which requires a user name and password; these can be set withsetUser() andsetPassword().

Because path is always encoded internally you must not use "%00" in the path, although this is okay (but not recommended) for the query.

Q3Url is normally used like this:

Q3Url url("http://qt.nokia.com" );// orQ3Url url("file:///home/myself/Mail","Inbox" );

You can then access and manipulate the various parts of the URL.

To make it easy to work with Q3Urls and QStrings,Q3Url implements the necessary cast and assignment operators so you can do following:

Q3Url url("http://qt.nokia.com" );QString s= url;// orQString s("http://qt.nokia.com" );Q3Url url( s );

Use the static functions,encode() anddecode() to encode or decode a URL in a string. (They operate on the string in-place.) TheisRelativeUrl() static function returns true if the given string is a relative URL.

If you want to use a URL to work on a hierarchical structure (e.g. a local or remote filesystem), you might want to use the subclass Q3UrlOperator.

Member Function Documentation

Q3Url::Q3Url()

Constructs an empty URL that is invalid.

Q3Url::Q3Url(constQString & url)

Constructs a URL by parsing the stringurl.

If you pass a string like "/home/qt", the "file" protocol is assumed.

Q3Url::Q3Url(constQ3Url & url)

Copy constructor. Copies the data ofurl.

Q3Url::Q3Url(constQ3Url & url, constQString & relUrl,bool checkSlash = false)

Constructs an URL takingurl as the base (context) andrelUrl as a relative URL tourl. IfrelUrl is not relative,relUrl is taken as the new URL.

For example, the path of

Q3Url url("ftp://ftp.qt.nokia.com/qt/source","qt-2.1.0.tar.gz" );

will be "/qt/srource/qt-2.1.0.tar.gz".

On the other hand,

Q3Url url("ftp://ftp.qt.nokia.com/qt/source","/usr/local" );

will result in a new URL, "ftp://ftp.qt.nokia.com/usr/local", because "/usr/local" isn't relative.

Similarly,

Q3Url url("ftp://ftp.qt.nokia.com/qt/source","file:///usr/local" );

will result in a new URL, with "/usr/local" as the path and "file" as the protocol.

Normally it is expected that the path ofurl points to a directory, even if the path has no slash at the end. But if you want the constructor to handle the last part of the path as a file name if there is no slash at the end, and to let it be replaced by the file name ofrelUrl (if it contains one), setcheckSlash to true.

[virtual]Q3Url::~Q3Url()

Destructor.

[virtual]void Q3Url::addPath(constQString & pa)

Adds the pathpa to the path of the URL.

See alsosetPath() andhasPath().

[virtual]bool Q3Url::cdUp()

Changes the directory to one directory up. This function always returns true.

See alsosetPath().

[static]void Q3Url::decode(QString & url)

Decodes theurl in-place into UTF-8. For example

QString url="http%3A//qt%20nokia%20com"Q3Url::decode( url );// url is now "http://qt.nokia.com"

See alsoencode().

QString Q3Url::dirPath() const

Returns the directory path of the URL. This is the part of the path of the URL without thefileName(). See the documentation offileName() for a discussion of what is handled as file name and what is handled as directory path.

See alsosetPath() andhasPath().

[static]void Q3Url::encode(QString & url)

Encodes theurl in-place into UTF-8. For example

QString url= http://qt.nokia.comQ3Url::encode( url );// url is now "http%3A//qt%20nokia%20com"

See alsodecode().

QString Q3Url::encodedPathAndQuery()

Returns the encoded path and query.

See alsosetEncodedPathAndQuery() anddecode().

QString Q3Url::fileName() const

Returns the file name of the URL. If the path of the URL doesn't have a slash at the end, the part between the last slash and the end of the path string is considered to be the file name. If the path has a slash at the end, an empty string is returned here.

See alsosetFileName().

bool Q3Url::hasHost() const

Returns true if the URL contains a hostname; otherwise returns false.

See alsosetHost().

bool Q3Url::hasPassword() const

Returns true if the URL contains a password; otherwise returns false.

Warning: Passwords passed in URLs are normallyinsecure; this is due to the mechanism, not because of Qt.

See alsosetPassword() andsetUser().

bool Q3Url::hasPath() const

Returns true if the URL contains a path; otherwise returns false.

See alsopath() andsetPath().

bool Q3Url::hasPort() const

Returns true if the URL contains a port; otherwise returns false.

See alsosetPort().

bool Q3Url::hasRef() const

Returns true if the URL has a reference; otherwise returns false.

See alsosetRef().

bool Q3Url::hasUser() const

Returns true if the URL contains a username; otherwise returns false.

See alsosetUser() andsetPassword().

QString Q3Url::host() const

Returns the hostname of the URL.

See alsosetHost() andhasHost().

bool Q3Url::isLocalFile() const

Returns true if the URL is a local file; otherwise returns false.

[static]bool Q3Url::isRelativeUrl(constQString & url)

Returns true ifurl is relative; otherwise returns false.

bool Q3Url::isValid() const

Returns true if the URL is valid; otherwise returns false. A URL is invalid if it cannot be parsed, for example.

[virtual protected]bool Q3Url::parse(constQString & url)

Parses theurl. Returns true on success; otherwise returns false.

QString Q3Url::password() const

Returns the password of the URL.

Warning: Passwords passed in URLs are normallyinsecure; this is due to the mechanism, not because of Qt.

See alsosetPassword() andsetUser().

QString Q3Url::path(bool correct = true) const

Returns the path of the URL. Ifcorrect is true, the path is cleaned (deals with too many or too few slashes, cleans things like "/../..", etc). Otherwise path() returns exactly the path that was parsed or set.

See alsosetPath() andhasPath().

int Q3Url::port() const

Returns the port of the URL or -1 if no port has been set.

See alsosetPort().

QString Q3Url::protocol() const

Returns the protocol of the URL. Typically, "file", "http", "ftp", etc.

See alsosetProtocol().

QString Q3Url::query() const

Returns the (encoded) query of the URL.

See alsosetQuery() anddecode().

QString Q3Url::ref() const

Returns the (encoded) reference of the URL.

See alsosetRef(),hasRef(), anddecode().

[virtual protected]void Q3Url::reset()

Resets all parts of the URL to their default values and invalidates it.

[virtual]void Q3Url::setEncodedPathAndQuery(constQString & pathAndQuery)

ParsespathAndQuery for a path and query and sets those values. The whole string must be encoded.

See alsoencodedPathAndQuery() andencode().

[virtual]void Q3Url::setFileName(constQString & name)

Sets the file name of the URL toname. If this URL contains afileName(), the original file name is replaced byname.

See the documentation offileName() for a more detailed discussion of what is handled as file name and what is handled as a directory path.

See alsofileName().

[virtual]void Q3Url::setHost(constQString & host)

Sets the hostname of the URL tohost.

See alsohost() andhasHost().

[virtual]void Q3Url::setPassword(constQString & pass)

Sets the password of the URL topass.

Warning: Passwords passed in URLs are normallyinsecure; this is due to the mechanism, not because of Qt.

See alsopassword() andsetUser().

[virtual]void Q3Url::setPath(constQString & path)

Sets the path of the URL topath.

See alsopath() andhasPath().

[virtual]void Q3Url::setPort(int port)

Sets the port of the URL toport.

See alsoport().

[virtual]void Q3Url::setProtocol(constQString & protocol)

Sets the protocol of the URL toprotocol. Typically, "file", "http", "ftp", etc.

See alsoprotocol().

[virtual]void Q3Url::setQuery(constQString & txt)

Sets the query of the URL totxt.txt must be encoded.

See alsoquery() andencode().

[virtual]void Q3Url::setRef(constQString & txt)

Sets the reference of the URL totxt.txt must be encoded.

See alsoref(),hasRef(), andencode().

[virtual]void Q3Url::setUser(constQString & user)

Sets the username of the URL touser.

See alsouser() andsetPassword().

[virtual]QString Q3Url::toString(bool encodedPath = false,bool forcePrependProtocol = true) const

Composes a string version of the URL and returns it. IfencodedPath is true the path in the returned string is encoded. IfforcePrependProtocol is true andencodedPath looks like a local filename, the "file:/" protocol is also prepended.

See alsoencode() anddecode().

QString Q3Url::user() const

Returns the username of the URL.

See alsosetUser() andsetPassword().

Q3Url::operator QString() const

Composes a string version of the URL and returns it.

See alsoQ3Url::toString().

Q3Url & Q3Url::operator=(constQ3Url & url)

Assigns the data ofurl to this class.

Q3Url & Q3Url::operator=(constQString & url)

This is an overloaded function.

Parsesurl and assigns the resulting data to this class.

If you pass a string like "/home/qt" the "file" protocol will be assumed.

bool Q3Url::operator==(constQ3Url & url) const

Compares this URL withurl and returns true if they are equal; otherwise returns false.

bool Q3Url::operator==(constQString & url) const

This is an overloaded function.

Compares this URL withurl.url is parsed first. Returns true ifurl is equal to this url; otherwise returns false.